GenIce3

Getting started

Quick start

To generate a hydrogen-disordered ice structure, install the package and pass a unit cell name (e.g. 1h for Ice Ih, 4 for Ice IV) as the first argument:

pip install genice3
genice3 1h > ice.gro

This is the current GenIce. Manual: genice-dev.github.io/GenIce3. For AI assistants: for-ai-assistants · llms.txt.

New in GenIce3

• Command line
  • Option syntax is unified; hierarchical options and YAML config files (-Y / --config) replace many GenIce2-style flags.
  • Polarization control uses pol_loop_1 and pol_loop_2 (replacing depol_loop).
  • Package and entry points are genice3 (PyPI: genice3); plugin groups use the genice3.* namespaces.
• API
  • Python API redesigned around GenIce3 and DependencyEngine: specify what you need and dependent quantities recompute automatically.
  • Embed protonic defects (H₃O⁺, OH⁻) and Bjerrum topological defects from Python (see the API examples in the manual).
  • Setter-style configuration and expanded notebooks/examples (API.ipynb, examples/api/).
• Algorithm and core
  • Ice-rule and depolarization logic delegated to genice-core (≥1.6.0); GenIce3 focuses on unit cells, guests, ions, and exporters.
  • Reactive pipeline: @reactive properties and explicit dependency tracking replace ad-hoc recalculation.
• Unit cells and structures
  • Lattice plugins moved to genice3.unitcell; many GenIce2 structures ported with identity comparison tests.
  • CIF-derived unit cells branch on whether hydrogen positions are supplied; partial_order removed.
  • New or updated structures include auxiliary ices, YKD, ice21 (and aliases), and cylindrical prism ice (API).
• Clathrates, ions, and defects
  • Cage assessment: GenIce2’s --assess_cages removed — use exporter cage_survey (JSON). Default max cage ring count is 16 (override via exporter options).
  • Spot ions use -A / -C (spot anion/cation; not the old cage-assessment flag). Group guests and spot-cation cage reporting extended; unit-cell ion suboptions (e.g. --group) in YAML.
• Exporters and visualization
  • Built-in and plugin exporters (GROMACS, CIF, LAMMPS, yaplot, plotly, py3Dmol, etc.); format functions and option parsing refined.
  • Optional Web API (genice3-web) with client examples and tests.
• Documentation and tooling
  • Manual on GitHub Pages; plugin tables and citations generated from the repo (make docs, make README.md).
  • For a narrative of the GenIce3 development period and compatibility notes, see RELEASE_NOTE.md in the repository.

Example — cage survey (formerly --assess_cages):

genice3 CS2 -e cage_survey > cages.json

Demo

GenIce3 works well in interactive environments.
Try it on Google Colaboratory.

Requirements

• networkx >=2.0.dev20160901144005
• numpy >=2.0
• pairlist >=1.0.0
• cycless >=0.7
• graphstat >=0.3.3
• yaplotlib >=0.1.2
• openpyscad >=0.5.0
• pyyaml >=6.0
• jinja2 >=3.1.4
• cif2ice (>=0.4.1,<0.5.0)
• genice-core (>=1.6.0,<2.0.0)
• fastapi (>=0.135.3,<0.136.0)
• uvicorn (>=0.44.0,<0.45.0)

Installation

GenIce3 is on PyPI. Install with pip:

pip install genice3

Uninstallation

pip uninstall genice3

This site is open source. Improve this page.