Commit cfc1e827 authored by temok-mx's avatar temok-mx

Updated README.md; added metadata.yml; the lead branch is now master, inactive branches became tags

parent 715042d1
# parser-skeleton
This is a NOMAD parser for [skeleton](). It will read skeleton input and
output files and provide all information in NOMAD's unified Metainfo based Archive format.
## About
## Preparing code input and output file for uploading to NOMAD
This is not a real parser, its a skeleton for parsers. To write you own parsers, its
best to fork this skeleton and use it as a template.
NOMAD accepts `.zip` and `.tar.gz` archives as uploads. Each upload can contain arbitrary
files and directories. NOMAD will automatically try to choose the right parser for you files.
For each parser (i.e. for each supported code) there is one type of file that the respective
parser can recognize. We call these files `mainfiles` as they typically are the main
output file a code. For each `mainfile` that NOMAD discovers it will create an entry
in the database that users can search, view, and download. NOMAD will associate all files
in the same directory as files that also belong to that entry. Parsers
might also read information from these auxillary files. This way you can add more files
to an entry, even if the respective parser/code might not directly support it.
## Setup and run example
For skeleton please provide at least the files from this table if applicable to your
calculations (remember that you can provide more files if you want):
We are currently targeting Python 3.6. Some nomad dependencies might still have problems
with 3.7++. It will definitely not work with 2.x. If you run into troubles, you could
try to ignore some dependencies. Most of them are only used in the DFT context.
Best use a virtual environment:
```
virtualenv -p python3 .pyenv
source .pyenv/bin/activate
```
Clone and install the nomad infrastructure and the necessary dependencies (including this parser)
To create an upload with all calculations in a directory structure:
```
git clone https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-FAIR nomad
cd nomad
git submodule update --init
pip install --upgrade pip
pip install --upgrade setuptools
pip install -r requirements.txt
./dependencies.sh -e
pip install -e .
zip -r <upload-file>.zip <directory>/*
```
The parsers (among other things) are git submodules. The `./dependencies.sh` will run
through all the sub modules and install them as pip packages (be in you virtual env!).
Go to the [NOMAD upload page](https://nomad-lab.eu/prod/rae/gui/uploads) to upload files
or find instructions about how to upload files from the command line.
## Using the parser
Fork this project on [gitlab](https://gitlab.mpcdf.mpg.de/nomad-lab/parser-skeleton).
Rename your fork in its settings/advanced and move it to the nomad-lab namespace.
Choose a name that starts with `parser-`, e.g. `parser-your-parser-name`.
You'll need a [http://www.mpcdf.mpg.de](https://www.mpcdf.mpg.de/userspace/forms/onlineregistrationform) account.
You can use NOMAD's parsers and normalizers locally on your computer. You need to install
NOMAD's pypi package:
Add your parser to the nomad project on a separate branch:
```
git checkout -b your-parser-name
git submodule add https://gitlab.mpcdf.mpg.de/nomad-lab/parser-your-parser-name dependencies/parsers/your-parser-name
pip install nomad-lab
```
Do the necessary changes:
- [setup.py](setup.py): Change the project metadata
- [skeletonparser](skeletonparser): Change the directory name, i.e. python package name (no uppercases, no `_` please)
- [skeletonparser/__init__.py](skeletonparser/__init__.py): Implement your parser, change the class names
- [skeletonparser/__main__.py](skeletonparser/__main__.py): Change the module/class names
- [skeletonparser/skeleton.nomadmetainfo.json](skeletonparser/skeleton.nomadmetainfo.json): Change the name, add your metadata definitions.
- [README.md](README.md): Change this readme accordingly.
- probably some other things I forgot.
General metadata quantities (those that we can agree on) go to
`dependencies/nomad-meta-info/meta_info/nomad_meta_info/general.experimental.nomadmetainfo.json`.
But we should agree first. In the mean time, just put them in [skeletonparser/skeleton.nomadmetainfo.json](skeletonparser/skeleton.nomadmetainfo.json).
You can browse around `dependencies/nomad-meta-info/meta_info/nomad_meta_info/` to
see example definitions. **You cannot add values or open sections without defining them first!**
To run the parser:
To parse code input/output from the command line, you can use NOMAD's command line
interface (CLI) and print the processing results output to stdout:
```
cd nomad/dependencies/parsers/your-parser-name
python -m yourparserpythonpackage tests/example.metadata.json
nomad parse --show-archive <path-to-file>
```
## Docs
To parse a file in Python, you can program something like this:
```python
import sys
from nomad.cli.parse import parse, normalize_all
# match and run the parser
backend = parse(sys.argv[1])
# run all normalizers
normalize_all(backend)
Click through the [nomad archive page](https://metainfo.nomad-coe.eu/nomadmetainfo_public/archive.html)
to learn about the *meta-info* metadata format and how to define your metadata.
# get the 'main section' section_run as a metainfo object
section_run = backend.resource.contents[0].section_run[0]
# get the same data as JSON serializable Python dict
python_dict = section_run.m_to_dict()
```
Here is a more involved tutorial (but its pretty DFT and parsing text files specific):
[nomad@fairdi docs](http://enc-staging-nomad.esc.rzg.mpg.de/fairdi/nomad/docs/parser_tutorial.html)
## Developing the parser
## FAQ
Also install NOMAD's pypi package:
```
pip install nomad-lab
```
Clone the parser project and install it in development mode:
```
git clone https://gitlab.mpcdf.mpg.de/nomad-lab/parser-skeleton parser-skeleton
pip install -e parser-skeleton
```
For any questions, **please open issues** (regarding parser development and using this skeleton)
in this [parser-skeleton project](https://gitlab.mpcdf.mpg.de/nomad-lab/parser-skeleton/issues).
We will compile a FAQ from your issues.
Running the parser now, will use the parser's Python code from the clone project.
code-label: skeleton
code-label-style: none, this is a template
code-url: ''
parser-dir-name: dependencies/parsers/skeleton/
parser-git-url: https://gitlab.mpcdf.mpg.de/nomad-lab/parser-skeleton
parser-specific: ''
table-of-files: ''
Markdown is supported
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