This page is intended for AI/LLM systems that need to understand and explain GenIce3 to users. It provides a compact, structured summary of the project.
Coding agents (Cursor, Claude Code, Codex, GitHub Copilot, Gemini CLI, …) can install the GenIce3 agent skill, which carries this page, the step-by-step workflow for running genice3, and the reference pages of this manual:
npx skills add genice-dev/GenIce3 # choose the agent interactively
gh skill install genice-dev/GenIce3 genice3 # GitHub CLI 2.90 or later; add --agent cursor, --agent claude-code, ...
pip install genice3), not GenIce 1 or GenIce2.genice3 --list unitcell.| Concept | Meaning |
|---|---|
| Unit cell | A small repeating unit of the ice/clathrate lattice (e.g. 1h = Ice Ih, CS2 = clathrate sII). Specified by name as first argument. |
| Replication | The unit cell is repeated to form a supercell (--rep 2 2 2 or --replication_matrix). |
| Ice rule | Each oxygen has exactly two covalently bound hydrogens; hydrogen bonds are assigned to satisfy this. |
| Depolarization | Dipole optimization so that net polarization is near a target (default zero). |
| Cages | In clathrates, cavities (e.g. 12-hedra, 16-hedra) that can hold guest molecules (methane, THF, etc.). |
| Doping | Unit-cell ions: -a/--anion, -c/--cation (lattice sites). Spot ions: -A/--spot_anion, -C/--spot_cation (specific water in supercell). See Doping and defects. |
| Protonic / Bjerrum defects | H₃O⁺, OH⁻, or L/D Bjerrum defects; currently API-only (see API examples). |
pip install genice3 # Python 3.11 or later
genice3 --version # prints "genice3 3.x.y"
genice3 1h --rep 1 1 1 # smoke test: writes a .gro file to stdout
Do not guess plugin names; the program will list them.
genice3 --list unitcell # every ice / clathrate / zeolite framework, with descriptions
genice3 --list exporter # every output format
genice3 --list molecule # every water model and guest molecule
genice3 CS2 -e cage_survey # JSON per cage; specs.cage_type (A12, A16, ...) is what -g expects
genice3 <name>? # the suboptions of one unit cell, in CLI, API, and YAML form
If a name is wrong, the error names the closest matches, so the message itself is
enough to correct the command (the following line reports how many plugins are
installed and points at --list):
$ genice3 iceXVII
ERROR: Unknown unitcell "iceXVII". Did you mean: iceXXI, XVII, XVI, XII, VII?
genice3 [OPTIONS] UNITCELL
--rep, -e (exporter), -g/-G (guests), -a/-c (unitcell ions), -A/-C (spot ions), -Y (config file).genice3 --help or see CLI reference.from genice3.genice import GenIce3; from genice3.plugin import Exporter
GenIce3(), then genice.set_unitcell("A15") (or another name). Plugins that need options take keyword arguments on the same call: set_unitcell("CIF", file="path.cif"), set_unitcell("zeolite", code="LTA"). Assigning genice.unitcell = UnitCell("A15") is equivalent. Optionally set replication_matrix, spot_anions, spot_cations, spot_hydroniums, spot_hydroxides, then access reactive properties (graph, lattice_sites, digraph, orientations) or call Exporter("gromacs").dump(genice, ...).fixed_edges, digraph, orientations are computed on demand from unitcell, spot_*, etc.unitcell (built-in and user-added); name passed as first CLI argument or set_unitcell("Name", ...). Some unit cells require options: pass them as keyword arguments, e.g. set_unitcell("CIF", file="path/to.cif"), set_unitcell("aeroice", length=3) or set_unitcell("xFAU", length=3) (length = hexagonal prism length), set_unitcell("zeolite", code="LTA"). See Unit cells for the list and suboption tables.exporter; selected with -e or Exporter("name").dump(genice, ...).molecules; water model via exporter suboption (e.g. -e "gromacs :water_model tip4p" or config exporter.water_model), or in API Exporter("gromacs").dump(genice, water_model="tip5p"). Symbols: tip3p, tip4p, 5site/tip5p, etc. See Water models. -g/-G for guests.unitcell, exporter, or molecules directories (e.g. current working directory).genice3 1h or genice3 1h --rep 2 2 2 -e gromacs > ice.grogenice3 CS2 -g A16=uathf -G 0=me (guest by cage type and by cage index; the label is the cage_type of -e cage_survey, not a bare number)genice3 CS2 -c 0=Na -a 1=Cl (equal number of cations and anions required)genice3 4 -e "gromacs :water_model tip4p"genice3 1h --rep 4 4 4 --pol_loop_2 10000 --target_polarization 0 0 40genice3 --list unitcell, or see Unit cells (symbols like 1h, 4, CS1, CIF for CIF file input).| Message | Cause and remedy |
|---|---|
Unknown unitcell "..." / Unknown exporter "..." |
The name is not installed. The message lists near matches; genice3 --list CATEGORY gives all of them. Names are case-sensitive (A15, not a15). |
Cage type 16 is not defined. Available cage types ... |
-g takes the cage label, e.g. A16, not the number of faces. genice3 STRUCTURE -e cage_survey reports each cage with its cage_type. |
Unrecognized options; stopping: ... |
A flag was not consumed by the base parser, the unit cell, or the exporter. Unit-cell suboptions must follow the unit-cell name; exporter suboptions go inside -e "name :key value". |
| Different structure on every run | Expected: the proton network is random. Pass --seed N to reproduce one. |
When explaining GenIce3 to a user, prefer linking to the relevant manual section (e.g. CLI, ice structures, API examples) and summarize in one or two sentences what the user can do (generate ice/clathrate, choose lattice, export to MD formats, add ions or defects via API).