This is a template repository how you can publish your calculation with pyiron. It consists of the repository itself, a small website created with Jupyterbook and a mybinder environment for testing the calculation.
You can fork this repository and populate it with your own data.
- Move your notebooks to the repository folder and remove the example notebook
example.ipynb. - Update the conda
environment.ymlfile with the conda dependencies required for your notebook. - Include the export of your pyiron database in the
pyiron/calculationfolder or in case no calculation are required you can remove thepyiron/calculation/save.tar.gzarchive and thepyiron/calculation/export.csvdatabase backup file. - Include additional pyiron resources in the
pyiron/resourcesfolder if required, otherwise thepyiron/resourcesfolder can be deleted.
In the following the repsoitory structure is explained in more detail:
The repository folder contains one or more jupyter notebooks. These notebooks are executed during the unit tests and included in the website for easy readablity. The example notebook example.ipynb should be removed before publication.
The repository folder also includes the conda environment.yml file which defines the conda environment required to execute the notebooks in the repository folder. An existing environment can be exported using conda env export > environment.yml but it is recommended to reduce the environment to the minimal requirements as a large environment is less performant. Example conda environment.yml file:
channels:
- conda-forge
dependencies:
- python
- pyiron_atomistics =0.2.8
- lammps =2021.02.10=*openmpi*_4
- nglview =2.7.7
The pyiron/calculation folder includes previous calculation results which are published with this repository. In this example the calculation were calculated and exported using:
from pyiron_atomistics import Project
pr = Project("old_calculation")
job = pr.create.job.Lammps(job_name="lmp_si")
job.structure = pr.create.structure.ase.bulk("Si")
job.run()
pr.pack(destination_path="save")
The resulting files export.csv and save.tar.gz have been copied to the pyiron/calculation folder.
Just like the pyiron resources folder the pyiron/resources folder can include additional resources like links to special executables or parameter files. In this example the pyiron/resources folder contains a special LAMMPS potential named Si-quip-xml which is required for the example notebook example.ipynb.
The jupyterbook is build using the github action .github/workflows/book.yml and it is deployed to github pages using .github/workflows/deploy.yml. Both github actions internally use the conda environment defined in .github/ci_support/environment.yml. But there should be no need to modify these files.
Besides the conda environment in environment.yml the .binder/postBuild script is used to import the calculations stored in pyiron/calculation and install NGLview for both jupyter notebooks and jupyter lab. Finally the pyiron environment on mybinder is configured using the .binder/.pyiron file in this repository. Only the conda environment file environment.yml has to be updated by the user.
The rest of the files in the repository are used to test the environment. For continous integration the github actions are defined in .github/workflows/notebooks.yml. Again the conda environment file environment.yml is used to install all the dependencies, afterwards pyiron is configured in the test environment using .github/ci_support/pyironconfig.py and finally the notebooks are executed using .github/ci_support/build_notebooks.sh. Usually there is no need for the user to adjust any of these files other than the conda environment environment.yml file.
In order to register the workflow in the PMD workflow store, the file meta.json is required. The file includes the essential metadata. The keys and their possible values are listed in the following table:
| Key | Requirement | Description |
|---|---|---|
| title | Mandatory | the Label of the workflow |
| workflow_environment | Mandatory | pyiron or SimStack |
| description | Mandatory | the description of the workflow |
| authors | Mandatory | a list of authors' names and optional their email addresses e.g. ["Author One a1@example.de", "Author Two a2@example.de"] |
| release | Mandatory | version information of the release |
| keywords | Mandatory | a list of keywords for the workflow (From a list of available keywords, making it possible to be queried via Ontology) |
| categories | Optional | a list of categories, e.g., atomistics, continuum, experimental |
| steps/codes | Optional | a list of steps/codes, e.g., LAMMPS, DAMASK, calculation of elastic modulus |
| licenses | Optional | a dictionary where the keys are the packages used in the workflow and the values are the corresponding license type. e.g. 'pyiron':'BSD-3' |
| publications | Optional | a list of publications |
| logo | Optional | path to the logo of the workflow within the repository |
pyiron and also the pyiron publication template are licensed under the BSD-3-Clause license which is included in the LICENSE file. In addition an CODE_OF_CONDUCT.md file is included to foster an open and welcoming environment.