Commit 6ac10391 authored by Markus Scheidgen's avatar Markus Scheidgen
Browse files

Updated the docs structure.

parent 7b761aa7
Pipeline #122873 passed with stages
in 39 minutes and 27 seconds
# Archive Query
# Query and Access Processed Data
The asynchronous archive query class `ArchiveQuery` provides a "downloader", which adopts a different mechanism compared to the
synchronous version. The configuration is handled by the construction of the target object.
## Argument List
The following arguments are acceptable.
- `owner` : `str` The scope of data to access. Default: `'visible'`
- `query` : `dict` The API query. There are no validations of any means carried out by the class, users shall make sure
the provided query is valid. Otherwise, server would return error message.
- `required` : `dict` The required quantities.
- `url` : `str` The database url. It can be the one of your local database. The official NOMAD database is used be
default if no valid one defined. Default: `http://nomad-lab.eu/prod/v1/api`
- `after` : `str` It can be understood that the data is stored in a sequential list. Each upload has a unique ID,
if `after` is not provided, the query always starts from the first upload. One can choose to query the uploads in the
middle of storage by assigning a proper value of `after`.
- `results_max` : `int` Determine how many entries to download. Note each upload may have multiple entries.
- `page_size` : `int` Page size.
- `username` : `str` Username for authentication.
- `password` : `str` Password for authentication.
- `retry` : `int` In the case of server errors, the fetch process is automatically retried every `sleep_time` seconds.
This argument limits the maximum times of retry.
- `sleep_time` : `float` The interval of fetch retry.
The `ArchiveQuery` allows you to search for entries and access their parsed and processed *archive* data
at the same time. Furthermore, all data is accessible through a convenient Python interface
based on the [NOMAD metainfo](archive.md) rather than plain JSON.
## Basic Usage
......@@ -181,4 +161,25 @@ Fetching remote uploads...
Downloading required data...
Downloaded 102 entries.
[('-NiRWNGjS--JtFoEnYrCfg', 8), ('-OcPUKZtS6u3lXlkWBM4qg', 129), ('-PA35e2ZRsq4AdDfBU4M_g', 14), ('-TG77dGiSTyrDAFNqTKa6Q', 366), ('-VzlPYtnS4q1tSl3NOmlCw', 178), ('-XeqzVqwSMCJFwhvDqWs8A', 14), ('-Y7gwnleQI6Q61jp024fXQ', 16), ('-Zf1RO1MQXegYVTbFybtQQ', 8), ('-Zm4S9VGRdOX-kbF1J5lOA', 50)]
```
\ No newline at end of file
```
## Argument List
The following arguments are acceptable.
- `owner` : `str` The scope of data to access. Default: `'visible'`
- `query` : `dict` The API query. There are no validations of any means carried out by the class, users shall make sure
the provided query is valid. Otherwise, server would return error message.
- `required` : `dict` The required quantities.
- `url` : `str` The database url. It can be the one of your local database. The official NOMAD database is used be
default if no valid one defined. Default: `http://nomad-lab.eu/prod/v1/api`
- `after` : `str` It can be understood that the data is stored in a sequential list. Each upload has a unique ID,
if `after` is not provided, the query always starts from the first upload. One can choose to query the uploads in the
middle of storage by assigning a proper value of `after`.
- `results_max` : `int` Determine how many entries to download. Note each upload may have multiple entries.
- `page_size` : `int` Page size.
- `username` : `str` Username for authentication.
- `password` : `str` Password for authentication.
- `retry` : `int` In the case of server errors, the fetch process is automatically retried every `sleep_time` seconds.
This argument limits the maximum times of retry.
- `sleep_time` : `float` The interval of fetch retry.
\ No newline at end of file
# Run NOMAD parser locally
If you install `nomad-lab[parsers]`, you can use the NOMAD parsers locally on your computer.
To use the NOMAD parsers from the command line, you can use the parse CLI command. The parse command will automatically match the right parser to your code output file and run the parser. There are two output formats, `--show-metadata` (a JSON representation of the basic metadata) and `--show-archive` (a JSON representation of the full parse results).
```sh
nomad parser --show-archive <path-to-your-mainfile-code-output-file>
```
You can also use the NOMAD parsers within Python, as shown below. This will give you the parse results as metainfo objects to conveniently analyze the results in Python. See metainfo for more details on how to use the metainfo in Python.
```python
import sys
from nomad.client import parse, normalize_all
# match and run the parser
archive = parse(sys.argv[1])
# run all normalizers
normalize_all(archive)
# get the 'main section' section_run as a metainfo object
section_run = archive.run[0]
# get the same data as JSON serializable Python dict
python_dict = section_run.m_to_dict()
```
You can also clone a parser project to debug or fix a parser:
```sh
git clone https://github.com/nomad-coe/nomad-parser-vasp.git
cd nomad-parser-vasp
git checkout metainfo-refactor
python -m nomad.cli nomad parser --show-archive <path-to-your-vasp-file>
```
Our parsers are hosted in github. They are in the [nomad-coe](https://github.com/nomad-coe) organization. They are typically named `nomad-parser-<code-name>`. The parser version
that fits the NOMAD v1 metainfo schema is typically in the `metainfo-refactor` branch.
Run the CLI with `python -m nomad.cli` to automatically include the current working directory
in the Python path. This will use the cloned parser code over the installed parser code.
\ No newline at end of file
# Using the Python library
# Install the Python library
NOMAD provides a Python package called `nomad-lab`.
## Install
The package is hosted on [pypi](https://pypi.org/project/nomad-lab/)
and you can install it with *pip* (or conda).
......@@ -42,52 +40,3 @@ The various extras have the following meaning:
- *dev*, additional tools that are necessary to develop NOMAD
- *all*, all of the above
## Access parsed NOMAD data with `ArchiveQuery`
The `ArchiveQuery` allows you to search for entries and access their parsed *archive* data
at the same time. Furthermore, all data is accessible through a convenient Python interface
based on the [NOMAD metainfo](archive.md) rather than plain JSON.
Please check [this page](async_archive.md) for details.
## Use NOMAD parser locally
If you install `nomad-lab[parsers]`, you can use the NOMAD parsers locally on your computer.
To use the NOMAD parsers from the command line, you can use the parse CLI command. The parse command will automatically match the right parser to your code output file and run the parser. There are two output formats, `--show-metadata` (a JSON representation of the basic metadata) and `--show-archive` (a JSON representation of the full parse results).
```sh
nomad parser --show-archive <path-to-your-mainfile-code-output-file>
```
You can also use the NOMAD parsers within Python, as shown below. This will give you the parse results as metainfo objects to conveniently analyze the results in Python. See metainfo for more details on how to use the metainfo in Python.
```python
import sys
from nomad.client import parse, normalize_all
# match and run the parser
archive = parse(sys.argv[1])
# run all normalizers
normalize_all(archive)
# get the 'main section' section_run as a metainfo object
section_run = archive.run[0]
# get the same data as JSON serializable Python dict
python_dict = section_run.m_to_dict()
```
You can also clone a parser project to debug or fix a parser:
```sh
git clone https://github.com/nomad-coe/nomad-parser-vasp.git
cd nomad-parser-vasp
git checkout metainfo-refactor
python -m nomad.cli nomad parser --show-archive <path-to-your-vasp-file>
```
Our parsers are hosted in github. They are in the [nomad-coe](https://github.com/nomad-coe) organization. They are typically named `nomad-parser-<code-name>`. The parser version
that fits the NOMAD v1 metainfo schema is typically in the `metainfo-refactor` branch.
Run the CLI with `python -m nomad.cli` to automatically include the current working directory
in the Python path. This will use the cloned parser code over the installed parser code.
\ No newline at end of file
......@@ -6,7 +6,10 @@ nav:
- Introduction: index.md
- web.md
- api.md
- pythonlib.md
- The nomad-lab Python package:
- pythonlib.md
- archive_query.md
- local_parsers.md
- archive.md
# - Using the AI Toolkit and other remote tools: aitoolkit.md
- Extending and Developing NOMAD:
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment