API-level examples for GenIce3.
Each subdirectory groups examples by topic, showing how to call GenIce3 from Python.
| Directory | Description |
|---|---|
| basic | Basic usage (reactive properties, simple structure generation) |
| cif_io | Reading from and writing to CIF files |
| doping | Ionic substitution and group (cation group) doping |
| exotic_ice | Exotic/nonstandard ice examples (e.g. cylindrical nanotube-like prism ice) |
| guest_occupancy | Guest placement and cage survey for clathrate hydrates |
| polarization | Polarization and dipole optimization (target_pol, pol_loop_1) |
| unitcell_transform | Extending the unit cell (replication_matrix) |
| topological_defects | Topological defects (Bjerrum, H3O⁺, OH⁻) |
| mdanalysis | GRO → PDB via MDAnalysis (optional: pip install MDAnalysis matplotlib) |
| visualize | GRO viewer with py3Dmol (optional: pip install py3dmol) |
| tools | Helper scripts for YAML ↔ shell conversions used by the examples |
Each subdirectory has its own README.md describing the example scripts it contains.
docs/api-examples/<category>.md, e.g. polarization.md, mdanalysis.md): built by scripts/build_api_docs.py, which concatenates each examples/api/<category>/README.md with a Sample code section (embedded *.py / *.sh / *.yaml in that folder). Run as part of make docs. No per-category switch: every subdirectory that has a README.md gets a page.scripts/build_api_notebook.py (make api-notebook); categories are listed explicitly in CATEGORIES inside that script (includes mdanalysis, visualize, …).In an environment where genice3 can be imported, you can run each .py file directly from the project root:
python examples/api/basic/2_simple.py
Run all examples at once (from project root):
make run-api-examples
# or
python scripts/run_api_examples.py
By default only .py files are run. To include .sh and/or .yaml:
python scripts/run_api_examples.py --sh # .py + .sh (bash)
python scripts/run_api_examples.py --yaml # .py + .yaml (genice3 --config)
python scripts/run_api_examples.py --all # .py + .sh + .yaml
List entries without running: python scripts/run_api_examples.py --dry-run.
On failure, stdout/stderr are written to run_api_examples.log.
Note: doping/11_ion_group_unitcell.py may occasionally fail due to random depolarization; re-run if needed.
Examples that need optional pip packages (e.g. mdanalysis/, visualize/) are not run by default. Install what you need explicitly, then use --with-optional:
pip install -r examples/api/requirements-mdanalysis.txt # MDAnalysis + matplotlib
pip install -r examples/api/requirements-py3dmol.txt # py3dmol
python scripts/run_api_examples.py --with-optional
Or run one script directly (from repo root, with genice3 on PYTHONPATH or installed):
pip install MDAnalysis matplotlib
python examples/api/mdanalysis/15_mdanalysis.py
From examples/api only:
pip install -r requirements-mdanalysis.txt
make mdanalysis
pip install -r requirements-py3dmol.txt
make visualize
(make mdanalysis / make visualize use the Poetry venv’s Python from the repo root; install the optional packages into that venv first.)
To generate .sh from YAML (or vice versa), use tools/gen_sh_from_yaml.py and tools/gen_yaml_from_sh.py.
API.ipynb is generated from these examples (make api-notebook). It includes all categories except tools (those scripts rely on __file__ and are meant to be run from the command line). After Installation, run Optional: MDAnalysis and/or Optional: py3Dmol if you use those sections (those packages are not part of the minimal Colab install). Then run Setup so paths like cif/MEP.cif resolve correctly.