This document explains the philosophy, approach, and design decisions behind QuickIce.
QuickIce generates ice structure candidates for given thermodynamic conditions (temperature and pressure). Given T and P inputs, it:
- Maps conditions to ice phases - Determines which ice polymorph is stable at the given T, P
- Generates candidate structures - Uses GenIce2 to create plausible atomic configurations
- Ranks candidates - Scores structures based on geometric assumptions
- Outputs results - Saves ranked PDB files and a phase diagram
The goal is to quickly generate starting structures for further analysis, not to perform physics simulations.
QuickIce is a pure "vibe coding" project - built for exploration and learning, not production science.
The original motivation was simple curiosity:
- What does Ice VII look like at 2 GPa?
- How does Ice XI differ from Ice Ih?
- Can I quickly generate reasonable starting structures for arbitrary conditions?
QuickIce answers these questions without requiring:
- Complex simulation setup
- Deep knowledge of molecular dynamics
- Expensive computational resources
It's a tool for rapid exploration of ice phase space.
QuickIce operates in a pipeline of phases:
CLI arguments are validated for correct types and ranges:
- Temperature: 0-500 K
- Pressure: 0-10000 MPa
- Molecules: 4-100000
Invalid inputs exit immediately with helpful error messages.
Temperature and pressure are mapped to an ice polymorph using:
- IAPWS R14-08 melting curves (high confidence)
- Triple point data from literature
- Linear interpolation for solid-solid boundaries (medium confidence)
Phase detection identifies regions for:
- 8 generatable phases (Ih, Ic, II, III, V, VI, VII, VIII)
- 4 detectable-only phases (IX, X, XI, XV) — no GenIce2 lattices available
- Liquid water and vapor regions
Candidates are generated using GenIce2, a combinatorial ice structure generator:
- Creates hydrogen-disordered structures consistent with the ice rules
- Uses cell dimensions appropriate for the phase
- Generates multiple candidates with different random seeds
Candidates are scored and ranked using three estimated components:
- Energy score: O-O distance deviation from ideal (0.276 nm)
- Density score: Deviation from expected phase density
- Diversity score: Measures structural diversity via O-O distance histogram fingerprints (cosine similarity between candidates)
Lower combined score = better candidate.
Results are saved to the output directory:
candidate_N.pdb- Ranked structures in PDB formatphase_diagram.png- Water phase diagram with input conditions marked
QuickIce does NOT perform:
- Molecular dynamics (MD) simulations
- Energy minimization
- Force field calculations
- Quantum chemistry calculations
Structures are generated combinatorially by GenIce2 and scored with geometric estimations. This makes QuickIce fast but approximate.
Why? Real MD simulations require:
- Hours to days of computation
- Specialized software (GROMACS, LAMMPS, etc.)
- Force field expertise
- Careful equilibration protocols
QuickIce provides structures in seconds for rapid exploration.
Phase boundaries are based on IAPWS R14-08 (International Association for the Properties of Water and Steam), the internationally validated standard for water/ice thermodynamics.
This ensures high confidence for:
- Ice Ih/Liquid boundary (melting curve)
- Ice III, V, VI, VII boundaries at high pressure
Solid-solid boundaries use linear interpolation between triple points (medium confidence).
GenIce2 is a well-established tool for generating ice structures. It:
- Enforces the ice rules (two donors, two acceptors per oxygen)
- Supports all common ice polymorphs
- Generates hydrogen-disordered (proton-disordered) structures
QuickIce wraps GenIce2 with condition-based selection and ranking.
The ranking system uses simple geometric estimations:
- O-O distances as an energy proxy
- Density matching for phase consistency
- O-O distance histogram fingerprints for structural diversity
These are not physics - they're practical metrics for distinguishing "good" structures from "obviously wrong" ones.
For accurate energetics, feed QuickIce outputs into proper MD simulations.
Structures come straight from GenIce2 without optimization. They may have:
- Suboptimal hydrogen bond angles
- Local strains
- Non-equilibrium configurations
Solution: Run energy minimization with your preferred MD engine if needed.
QuickIce generates initial structures, not equilibrated ones. Real ice at given T, P will have:
- Thermal fluctuations
- Proton dynamics
- Density variations
Solution: Run MD equilibration after generating structures.
QuickIce cannot determine phase stability. It maps T, P to phases based on literature boundaries, not thermodynamic calculations.
For phase stability analysis, use:
- Free energy perturbation methods
- Thermodynamic integration
- Enhanced sampling techniques
QuickIce generates ideal crystalline structures. Real ice contains:
- Vacancies
- Interstitials
- Grain boundaries
- Dislocations
Solution: Introduce defects manually or through simulation.
GenIce2 is used for structure generation:
- Repository: https://github.com/genice-dev/GenIce2
- Paper: "GenIce: Hydrogen-disordered ice structures by combinatorial generation" (J. Comput. Chem. 2017)
- DOI: https://doi.org/10.1002/jcc.25077
Phase boundaries are based on the IAPWS Release on the Pressure along the Melting and Sublimation Curves of Ordinary Water Substance (R14-08):
- Document: https://www.iapws.org/relguide/MeltSub.html
- Provides melting curves for ice phases (Ih, III, V, VI, VII) and sublimation curve
spglib is used for crystal symmetry analysis and validation:
- Repository: https://github.com/atztogo/spglib
- Paper: "Spglib: a software library for crystal symmetry search" (Sci. Technol. Adv. Mater. Meth. 2024)
- DOI: https://doi.org/10.1080/27660400.2024.2384822
Phase boundary data compiled from multiple sources:
- Wagner et al., "The IAPWS Industrial Formulation 1997 for the Thermodynamic Properties of Water and Steam"
- Londono et al., "Neutron diffraction studies of ices III and IX" (J. Chem. Phys. 1993) — DOI: https://doi.org/10.1063/1.464942
- Lobban et al., "The structure of a new phase of ice" (Nature 1998) — DOI: https://doi.org/10.1038/34622
- Salzmann et al., "Ice XV: A New Thermodynamically Stable Phase of Ice" (Phys. Rev. Lett. 2009) — DOI: https://doi.org/10.1103/physrevlett.103.105701
- Exploring ice phase space quickly
- Generating starting structures for MD simulations
- Teaching and learning about ice polymorphs
- Rapid prototyping of ice structure workflows
- Accurate thermodynamic properties
- Phase stability predictions
- Production-quality scientific publications (validate with MD)
- Studying defects or dynamics
QuickIce is a vibe coding project. Contributions welcome:
- Bug reports and fixes
- Additional ice phases
- Improved estimations
- Documentation improvements
- CLI Reference - Command-line usage
- Ranking Methodology - How candidates are scored
QuickIce: Generate ice structures quickly, for the joy of exploration.