|
1 | | -# pyiron workflow template |
2 | | -This is a template repository how you can publish your calculation with pyiron. It consists of the repository [itself](https://github.com/materialdigital/pyiron-workflow-template), a small [website](http://materialdigital.github.io/pyiron-workflow-template/) created with Jupyterbook and a [mybinder environment](https://mybinder.org/v2/gh/materialdigital/pyiron-workflow-template/HEAD?filepath=notebooks%2Fexample.ipynb) for testing the calculation. |
| 1 | +# Surface energies (pyiron_workflow) |
| 2 | +This repository demonstrates computing surface energies using the `pyiron_workflow` framework. The workflow is engine-agnostic and is demonstrated here with LAMMPS. |
3 | 3 |
|
4 | | -You can fork this repository and populate it with your own data. |
| 4 | +## Installation |
| 5 | +Create and activate the conda environment from the provided `environment.yml`: |
5 | 6 |
|
6 | | -## Step by step |
7 | | -* Move your notebooks to the repository folder and remove the example notebook `example.ipynb`. |
8 | | -* Update the conda `environment.yml` file with the conda dependencies required for your notebook. |
9 | | -* 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. |
10 | | -* Include additional pyiron resources in the `pyiron/resources` folder if required, otherwise the `pyiron/resources` folder can be deleted. |
| 7 | +```bash |
| 8 | +# Using mamba (recommended) |
| 9 | +mamba env create -f environment.yml -n pyiron-workflow-surface-energies |
| 10 | +conda activate pyiron-workflow-surface-energies |
11 | 11 |
|
12 | | -## Repository structure |
13 | | -In the following the repsoitory structure is explained in more detail: |
| 12 | +# Or using conda |
| 13 | +conda env create -f environment.yml -n pyiron-workflow-surface-energies |
| 14 | +conda activate pyiron-workflow-surface-energies |
14 | 15 |
|
15 | | -### notebooks |
16 | | -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. |
17 | | - |
18 | | -### conda environment |
19 | | -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: |
20 | | - |
21 | | -``` |
22 | | -channels: |
23 | | -- conda-forge |
24 | | -dependencies: |
25 | | -- python |
26 | | -- pyiron_atomistics =0.2.8 |
27 | | -- lammps =2021.02.10=*openmpi*_4 |
28 | | -- nglview =2.7.7 |
| 16 | +# To update an existing environment after changes to environment.yml |
| 17 | +mamba env update -f environment.yml -n pyiron-workflow-surface-energies |
| 18 | +# or |
| 19 | +conda env update -f environment.yml -n pyiron-workflow-surface-energies |
29 | 20 | ``` |
30 | 21 |
|
31 | | -### Existing calculation |
32 | | -The `pyiron/calculation` folder includes previous calculation results which are published with this repository. In this example the calculation were calculated and exported using: |
| 22 | +## Run the workflow |
| 23 | +Open and execute the notebook `surface_energy.ipynb` in this directory: |
33 | 24 |
|
| 25 | +```bash |
| 26 | +jupyter lab |
| 27 | +# or |
| 28 | +jupyter notebook |
34 | 29 | ``` |
35 | | -from pyiron_atomistics import Project |
36 | | -pr = Project("old_calculation") |
37 | | -job = pr.create.job.Lammps(job_name="lmp_si") |
38 | | -job.structure = pr.create.structure.ase.bulk("Si") |
39 | | -job.run() |
40 | | -pr.pack(destination_path="save") |
41 | | -``` |
42 | | - |
43 | | -The resulting files `export.csv` and `save.tar.gz` have been copied to the `pyiron/calculation` folder. |
44 | | - |
45 | | -### Additional pyiron resources |
46 | | -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`. |
47 | | - |
48 | | -### Jupyterbook |
49 | | -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. |
50 | | - |
51 | | -### mybinder |
52 | | -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. |
53 | | - |
54 | | -### Continous integration |
55 | | -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. |
56 | | - |
57 | | -### Metadata |
58 | | -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: |
59 | | - |
60 | | -| Key | Requirement | Description| |
61 | | -|-----|------------|------------| |
62 | | -| title | Mandatory | the Label of the workflow | |
63 | | -| workflow_environment | Mandatory | pyiron or SimStack | |
64 | | -| description | Mandatory | the description of the workflow | |
65 | | -| authors | Mandatory | a list of authors' names and optional their email addresses e.g. ["Author One <a1@example.de>", "Author Two <a2@example.de>"] | |
66 | | -| release | Mandatory | version information of the release | |
67 | | -| keywords | Mandatory | a list of keywords for the workflow (From a list of available keywords, making it possible to be queried via Ontology) | |
68 | | -| categories | Optional | a list of categories, e.g., atomistics, continuum, experimental| |
69 | | -| steps/codes | Optional | a list of steps/codes, e.g., LAMMPS, DAMASK, calculation of elastic modulus| |
70 | | -| licenses | Optional | a dictionary where the keys are the packages used in the workflow and the values are the corresponding license type. <br> e.g. 'pyiron':'BSD-3' | |
71 | | -| publications | Optional | a list of publications | |
72 | | -| logo | Optional | path to the logo of the workflow within the repository| |
73 | 30 |
|
74 | | -### License |
75 | | -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. |
| 31 | +Then open `surface_energy.ipynb` and run all cells. |
0 commit comments