https://github.com/pyiron/pyiron-publication-template
Template repository - how to publish your pyiron workflow
https://github.com/pyiron/pyiron-publication-template
publication pyiron
Last synced: 3 months ago
JSON representation
Template repository - how to publish your pyiron workflow
- Host: GitHub
- URL: https://github.com/pyiron/pyiron-publication-template
- Owner: pyiron
- License: bsd-3-clause
- Created: 2021-03-19T14:49:49.000Z (over 5 years ago)
- Default Branch: main
- Last Pushed: 2024-05-22T14:30:02.000Z (about 2 years ago)
- Last Synced: 2024-05-22T14:56:20.622Z (about 2 years ago)
- Topics: publication, pyiron
- Language: Jupyter Notebook
- Homepage: http://pyiron.org/pyiron-publication-template/
- Size: 2.35 MB
- Stars: 0
- Watchers: 9
- Forks: 5
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# pyiron publication template
This is a template repository how you can publish your calculation with pyiron. It consists of the repository [itself](https://github.com/pyiron/pyiron-publication-template), a small [website](http://pyiron.org/pyiron-publication-template/) created with Jupyterbook and a [mybinder environment](https://mybinder.org/v2/gh/pyiron/pyiron-publication-template/HEAD?filepath=notebooks%2Fexample.ipynb) 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:
```python
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.