Skip to content

Latest commit

 

History

History
58 lines (44 loc) · 4.4 KB

README.md

File metadata and controls

58 lines (44 loc) · 4.4 KB

pyiron publication template

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.

Step by step

  • Move your notebooks to the repository folder and remove the example notebook example.ipynb.
  • Update the conda environment.yml file with the conda dependencies required for your notebook.
  • Include the export of your pyiron database in the pyiron/calculation folder or in case no calculation are required you can remove the pyiron/calculation/save.tar.gz archive and the pyiron/calculation/export.csv database backup file.
  • Include additional pyiron resources in the pyiron/resources folder if required, otherwise the pyiron/resources folder can be deleted.

Repository structure

In the following the repsoitory structure is explained in more detail:

notebooks

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.

conda environment

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

Existing calculation

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.

Additional pyiron resources

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.

Jupyterbook

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.

mybinder

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.

Continuous integration

The rest of the files in the repository are used to test the environment. For continuous 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.

License

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.