README.md 3.38 KB
Newer Older
1
2
3
4
5
6
# parser-skeleton

## About

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.
Markus Scheidgen's avatar
Markus Scheidgen committed
7

8
9
## Setup and run example

10
We are currently targeting Python 3.6. Some nomad dependencies might still have problems
Markus Scheidgen's avatar
Markus Scheidgen committed
11
12
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.
13
14
15
16
17
18
19
20
21

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)
```
22
git clone https://gitlab.mpcdf.mpg.de/nomad-lab/nomad-FAIR nomad
Markus Scheidgen's avatar
Markus Scheidgen committed
23
cd nomad
24
25
26
git submodule update --init
pip install -r requirements.txt
./dependencies.sh -e
Markus Scheidgen's avatar
Markus Scheidgen committed
27
pip install -e .
28
29
```

Markus Scheidgen's avatar
Markus Scheidgen committed
30
31
32
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!).

33
Fork this project on [gitlab](https://gitlab.mpcdf.mpg.de/nomad-lab/parser-skeleton).
34
Rename your fork in its settings/advanced and move it to the nomad-lab namespace.
Markus Scheidgen's avatar
Markus Scheidgen committed
35
36
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.
37
38
39
40
41
42
43
44
45

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
```

Do the necessary changes:
- [setup.py](setup.py): Change the project metadata
Markus Scheidgen's avatar
Markus Scheidgen committed
46
- [skeletonparser](skeletonparser): Change the directory name, i.e. python package name (no uppercases, no `_` please)
47
48
49
50
- [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.
Markus Scheidgen's avatar
Markus Scheidgen committed
51
- probably some other things I forgot.
52

Markus Scheidgen's avatar
Markus Scheidgen committed
53
54
55
56
57
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!**
58

59
60
To run the parser:
```
Markus Scheidgen's avatar
Markus Scheidgen committed
61
62
cd nomad/dependencies/parsers/your-parser-name
python -m yourparserpythonpackage tests/example.metadata.json
63
64
65
66
```

## Docs

Markus Scheidgen's avatar
Markus Scheidgen committed
67
68
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.
69

Markus Scheidgen's avatar
Markus Scheidgen committed
70
71
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)
72
73
74

## FAQ

Markus Scheidgen's avatar
Markus Scheidgen committed
75
For any questions, **please open issues** (regarding parser development and using this skeleton)
76
77
in this [parser-skeleton project](https://gitlab.mpcdf.mpg.de/nomad-lab/parser-skeleton/issues).
We will compile a FAQ from your issues.