genice2 2.2.13.1
A Swiss army knife to generate hydrogen-disordered ice structures.
License: MIT
Requires Python: <4.0,>=3.10

![Logo](https://raw.githubusercontent.com/vitroid/GenIce/develop/logo/genice-v0.png)

# GenIce2

A Swiss army knife to generate hydrogen-disordered ice structures.

Version 2.2.13.1

## New in GenIce2.2

- The core algorithm and its API are in a separate module, [`genice-core`](https://github.com/genice-dev/genice-core).

## Demo

The new GenIce works very well with interactive execution.
[Try instantly](https://colab.research.google.com/github/vitroid/GenIce/blob/main/jupyter.ipynb) on Google Colaboratory.

## Requirements

- networkx>=2.0.dev20160901144005
- python^3.10
- numpy^2.0
- pairlist>=0.6.4
- cycless>=0.4.2
- graphstat>=0.3.3
- yaplotlib>=0.1.2
- openpyscad>=0.5.0
- genice-core>=1.2
- deprecation^2.1.0


<!-- **Note**: The package management system `poetry`, new in GenIce version 2.1, ignores all symlinks in package directories.
Because of this, some module "aliases" do not work correctly. (e.g. `genice2 1h` does not work, but `genice ice1h` does, because `1h.py` is an alias for `ice1h.py` .) -->

## Installation

GenIce is registered to [PyPI (Python Package Index)](https://pypi.python.org/pypi/GenIce).
Install with pip3.

```shell
% pip3 install genice2
```

## Uninstallation

```shell
% pip3 uninstall genice2
```

## Usage

    usage: genice2 [-h] [--version] [--rep REP REP REP] [--reshape RESHAPE]
                   [--shift SHIFT SHIFT SHIFT] [--dens DENS] [--add_noise percent]
                   [--seed SEED] [--format name] [--water model] [--guest 14=me]
                   [--Guest 13=me] [--Group 13=bu-:0] [--anion 3=Cl]
                   [--cation 3=Na] [--depol DEPOL]
                   [--target_polarization TARGET_POLARIZATION TARGET_POLARIZATION TARGET_POLARIZATION]
                   [--asis] [--debug] [--quiet] [--assess_cages]
                   Type
    
    GenIce is a swiss army knife to generate hydrogen-disordered ice structures.
    (version 2.2.13.0)
    
    positional arguments:
      Type                  Crystal type (1c, 1h, etc. See
                            https://github.com/vitroid/GenIce for available ice
                            structures.)
                            If you want to analyze your own structures, please try
                            analice tool.
    
    
                            [Available lattice structures]
    
                            1. Lattice structures served with GenIce
    
                            0, ice0         Metastable ice "0".
                            11, XI, ice11   A candidate for an antiferroelectric
                                            Ice XI #19.
                            115_2_114, 12_1_11, 144_2_7301, 151_2_4949650,
                                            153_2_155471, 176_2_5256, 207_1_4435,
                                            2_2_623457, ACO, CS4, DDR, IWV, LTA,
                                            MAR, NON, PCOD8007225, PCOD8036144,
                                            PCOD8204698, PCOD8301974, PCOD8321499,
                                            PCOD8324623, SGT, SOD, engel01,
                                            engel03, engel04, engel17, engel20,
                                            engel23, engel24, engel26, engel29,
                                            engel30, engel31, engel34, sVII
                                            Hypothetical zeolitic ice
                            11alt           A layered ferroelectric Ice XI.
                            11i             Sixteen candidates for Ice XI.
                            12, XII, ice12  Metastable high-pressure ice XII.
                            13, XIII, ice13 Ice XIII, a hydrogen-ordered
                                            counterpart of ice V.
                            14, ice14       Ice XIV, a partially hydrogen-ordered
                                            counterpart of ice XII. Note that it
                                            does not reproduce the occupancies
                                            (probability of occupation) of the
                                            possible hydrogen sites.
                            16, CS2, MTN, XVI, ice16, sII   Ultralow-density Ice
                                            XVI.
                            17, XVII, ice17 Ultralow-density Ice XVII.
                            1c, Ic, ice1c   Cubic type of ice I.
                            1h, Ih, ice1h   Most popular Ice I (hexagonal). NOTE:
                                            Due to a historical reason, the crystal
                                             axes of hexagonal ice are exchanged.
                                            If you want the basal plane to be Z
                                            axis, please use 'one[hh]' instead.
                            2, II, ice2     Hydrogen-ordered ice II.
                            2D3             Trilayer honeycomb ice.
                            2d, ice2d, ice2rect             A hydrogen-disordered
                                            counterpart of ice II.
                            3, III, ice3    Ice III.
                            4, IV, ice4     Ice IV.
                            4R              Orthogonalized ice IV.
                            5, V, ice5      Monoclinic ice V (testing).
                            5R              Ice V with orthogonal unit cell.
                                            (testing)
                            6, VI, ice6     Conventional high-pressure ice VI.
                            6h              Half lattice of ice VI.
                            7, VII, ice7    Conventional high-pressure ice VII.
                            8, VIII, ice8   Ice VIII, a hydrogen-ordered
                                            counterpart of ice VII.
                            9, IX, ice9     Ice IX, a hydrogen-ordered counterpart
                                            of ice III.
                            A, iceA         Hypothetical ice A.
                            A15, Struct33   Cubic Structure I of clathrate hydrate.
                            B, iceB         Hypothetical ice B.
                            BSV, engel05    Hypothetical zeolitic ice of the gyroid
                                             structure.
                            C14, C15, C36, FK6layers, FK9layers, HS2, Hcomp,
                                            Struct01, Struct03, Struct04, Struct05,
                                             Struct06, Struct07, Struct08,
                                            Struct09, Struct10, Struct11, Struct12,
                                             Struct13, Struct14, Struct15,
                                            Struct16, Struct17, Struct18, Struct19,
                                             Struct20, Struct21, Struct22,
                                            Struct23, Struct24, Struct25, Struct26,
                                             Struct27, Struct28, Struct29,
                                            Struct30, Struct31, Struct32, Struct34,
                                             Struct35, Struct36, Struct37,
                                            Struct38, Struct39, Struct40, Struct41,
                                             Struct42, Struct43, Struct44,
                                            Struct45, Struct46, Struct47, Struct48,
                                             Struct49, Struct50, Struct51,
                                            Struct52, Struct53, Struct54, Struct55,
                                             Struct56, Struct57, Struct58,
                                            Struct59, Struct60, Struct61, Struct62,
                                             Struct63, Struct64, Struct65,
                                            Struct66, Struct67, Struct68, Struct69,
                                             Struct70, Struct71, Struct72,
                                            Struct73, Struct74, Struct75, Struct76,
                                             Struct77, Struct78, Struct79,
                                            Struct80, Struct81, Struct82, Struct83,
                                             Struct84, Z, delta, mu, psigma, sV,
                                            sigma, zra-d     A space fullerene.
                            CRN1, CRN2, CRN3                A continuous random
                                            network of Sillium.
                            CS1, MEP, sI    Clathrate hydrates sI.
                            DOH, HS3, sH    Clathrate type H.
                            EMT             Hypothetical ice with a large cavity.
                            FAU             Hypothetical ice at negative pressure
                                            ice 'sIV'.
                            HS1, sIV        Hydrogen-disordered ice Ih.
                            M, iceM         A hypothetical hydrogen-ordered high-
                                            density ice.
                            RHO             Hypothetical ice at negative pressure
                                            ice 'sIII'.
                            Struct02        A space fullerene. (I phase?)
                            T               Hypothetical clathrate type T.
                            XIc-a           A candidate for the proton-ordered
                                            counterpart of ice Ic. The structure
                                            'a' in Figure 1.
                            YKD             Ice in a d-surface (testing).
                            bilayer         A Bilayer Honeycomb Ice Phase in
                                            Hydrophobic Nanopores.
                            c0te            Filled ice C0 by Teeratchanan
                                            (Hydrogen-disordered.) (Positions of
                                            guests are supplied.)
                            c1te            Hydrogen-ordered hydrogen hydrate C1 by
                                             Teeratchanan. (Positions of guests are
                                             supplied.)
                            c2te            Filled ice C2 (cubic ice) by
                                            Teeratchanan (Hydrogen disordered).
                                            (Positions of guests are supplied.)
                            eleven          Ice XI w/ stacking faults.
                            i               Hypothetical ice "i".
                            ice1hte         Filled ice Ih by Teeratchanan (Hydrogen
                                             disordered). (Positions of guests are
                                            supplied.)
                            iceL            The hypothetical Ice L
                            iceMd           A hydrogen-disordered counterpart of
                                            ice M.
                            iceR            Hypothetical ice R.
                            iceT            Hypothetical ice T.
                            iceT2           Hypothetical ice T2.
                            one             Ice I w/ stacking disorder.
                            oprism          Hydrogen-ordered ice nanotubes.
                            sTprime         Filled ice sT'.
                            xFAU            Aeroice xFAU.
                            xdtc            A porous ice with cylindrical channels.
                            ----
                            (Undocumented) 1h_unit TS1 dtc ice1h_unit sIII
    
    
                            2. Lattice structures served by external plugins
    
                            cif             Read a CIF file.
                            ----
                            (Undocumented) zeolite
    
    
                            3. Lattice structures served locally
    
                            (None)
                            ----
    
    
    
    options:
      -h, --help            show this help message and exit
      --version, -V         show program's version number and exit
      --rep REP REP REP, -r REP REP REP
                            Repeat the unit cell along a, b, and c axes. [1,1,1]
      --reshape RESHAPE, -R RESHAPE
                            Convert the unit cell shape by specifying the new
                            (a,b,c) set from the original (a,b,c) of the unit
                            cell. The combination of (a,b,c) is specified by nine
                            integers. For example, '--reshape 3,0,0,0,2,0,0,0,1'
                            specifies that the new cell vectors are (3a, 2b, c),
                            which is equivalent to '--rep 3 2 1'.
      --shift SHIFT SHIFT SHIFT, -S SHIFT SHIFT SHIFT
                            Shift the unit cell along a, b, and c axes. (0.5==half
                            cell) [0,0,0]
      --dens DENS, -d DENS  Specify the ice density in g/cm3 (Guests are not
                            included.)
      --add_noise percent   Add a Gauss noise with given width (SD) to the
                            molecular positions of water. The value 1 corresponds
                            to 1 percent of the molecular diameter of water.
      --seed SEED, -s SEED  Random seed [1000]
      --format name, -f name
                            Specify the output file format. [gromacs]
    
    
                            [Available formatters]
    
                            1. Formatters served with GenIce
    
                            _KG             Kirkworrd G factor.
                            _pol            Polarization check.
                            _ringstat       Bond direction statistics.
                            d, digraph      Directed graph of HBs.
                            e, euler        Rigid rotor (Euler angle).
                            exmol           Extended XMol file format.
                            exyz            Extended XYZ format.
                            g, gromacs      Gromacs .gro file.
                            graph           Undirected graph of HBs.
                            m, mdv_au, mdview               MDView file (in
                                            Angdtrom).
                            p, python       A formatter plugin to produce a python
                                            lattice plugin.
                            povray          Povray.
                            q, quaternion   Rigid rotor (Quaternion).
                            raw             Raw data. (For use with Jupyter)
                            rings           Show rings in Yaplot.
                            y, yaplot       Yaplot.
                            ----
                            (Undocumented) c cif cif2 com null r rcom towhee xyz
    
    
                            2. Formatters served by external plugins
    
                            cage            Cage analysis.
                            mdanalysis      MDAnalysis integration.
                            png             PNG (Portable Network Graphics).
                            svg             SVG (Standard Vector Graphics).
                            ----
    
    
                            3. Formatters served locally
    
                            (None)
                            ----
    
    
      --water model, -w model
                            Specify the water model. [tip3p]
    
    
                            [Available molecules]
    
                            1. Molecules served with GenIce
    
                            3site, tip3p    A typical 3-site model.
                            4site, tip4p    A typical 4-site model.
                            5site, tip5p    A typical 5-site model.
                            6site, NvdE     A 6-site water model.
                            7site           A seven-site water model.
                            physical_water  Physical model of water; Oxygen atom is
                                             on the lattice point.
                            ----
                            (Undocumented) ice spce
    
    
                            2. Molecules served by external plugins
    
                            (None)
                            ----
    
    
                            3. Molecules served locally
    
                            (None)
                            ----
    
    
      --guest 14=me, -g 14=me
                            Specify guest(s) in the cage type. (D=empty,
                            T=co2*0.5+me*0.3, etc.)
    
    
                            [Available molecules]
    
                            1. Molecules served with GenIce
    
                            H2              Hydrogen molecule.
                            ch4             An all-atom methane model.
                            et              A united-atom ethane model.
                            me              A united-atom methane model.
                            mol             Loader for MOL files (generated by
                                            MolView.org), e.g. mol[THF.mol].
                            thf             An all-atom tetrahydrofuran (THF)
                                            model.
                            uathf           A united-atom five-site tetrahydrofuran
                                             (THF) model.
                            ----
                            (Undocumented) co2 empty g12 g14 g15 g16 one uathf6
    
    
                            2. Molecules served by external plugins
    
                            (None)
                            ----
    
    
                            3. Molecules served locally
    
                            (None)
                            ----
    
    
      --Guest 13=me, -G 13=me
                            Specify guest in the specific cage. (13=me, 32=co2,
                            etc.)
      --Group 13=bu-:0, -H 13=bu-:0
                            Specify the group. (-H 13=bu-:0, etc.)
      --anion 3=Cl, -a 3=Cl
                            Specify a monatomic anion that replaces a water
                            molecule. (3=Cl, 39=F, etc.)
      --cation 3=Na, -c 3=Na
                            Specify a monatomic cation that replaces a water
                            molecule. (3=Na, 39=NH4, etc.)
      --depol DEPOL         Depolarization. (strict, optimal, or none) ["strict"]
      --target_polarization TARGET_POLARIZATION TARGET_POLARIZATION TARGET_POLARIZATION
                            Target polarization. [0.0, 0.0, 0.0]
      --asis                Assumes all given HB pairs to be fixed. No shuffle and
                            no depolarization.
      --debug, -D           Output debugging info.
      --quiet, -q           Do not output progress messages.
      --assess_cages, -A    Assess the locations of cages based on the HB network
                            topology. Note: it may fail when the unit cell is too
                            small.


Use `./genice.x` instead of `genice2` if you want to use it inside the source tree.

## Examples

- To make a 3x3x3 units of a hydrogen-disordered ice IV (4) of TIP4P water in GROMACS
  .gro format:

```
          genice2 --water tip4p --rep 3 3 3  4 > ice4.gro
```

- To make a 2x2x4 units of CS2 clathrate hydrate structure of TIP4P water containing THF (united atom with a dummy site) in the large cage in GROMACS
  .gro format:

```
          genice2 -g 16=uathf6 --water tip4p --rep 2 2 4  CS2 > cs2-224.gro
```

## Basics

The program generates various ice lattice with proton disorder and without defect. The total dipole moment is always set to zero (except in the case you specify `--depol` option). The minimal structure (with --rep 1 1 1 option) is not always the unit cell of the lattice because it is difficult to deal with the hydrogen bond network topology of tiny lattice under periodic boundary condition. Note that the generated structure is not optimal according to the potential energy.

- To get a large repetition of ice Ih in XYZ format,

        genice2 --rep 8 8 8 1h --format xyz > 1hx888.xyz

- To get a ice V lattice of different hydrogen order in CIF format, use `-s` option to specify the random seed.

        genice2 5 -s 1024 --format cif > 5-1024.cif

- To obtain an ice VI lattice with different density and with TIP4P water model in gromacs format, use `--dens x` option to specify the density in g cm<sup>-3</sup>.

        genice2 6 --dens 1.00 --format g --water tip4p > 6d1.00.gro

GenIce is a modular program; it reads a unit cell data from a lattice plugin defined in the lattices folder, put water and guest molecules using a molecule plugin defined in the molecules/ folder, and output in various formats using a format plugin defined in the formats/ folder. You can write your plugins to extend GenIce. Some plugins also accept options.

## Clathrate hydrates

For clathrate hydrates, you can prepare the lattice with cages partially occupied by various guest molecules.

- To make a CS1 clathrate hydrate structure of TIP4P water containing CO2 in GROMACS .gro format: (60% of small cages are filled with co2 and 40% are methane)

        genice2 -g 12=co2*0.6+me*0.4 -g 14=co2 --water tip4p CS1 > cs1.gro

- To make a CS2 clathrate hydrate structure of TIP5P water containing THF molecules in the large cage, while only one cage is filled with methane molecule, first, just run `genice2` without guest specifications:

        genice2 CS2 > CS2.gro

  The list of cages will be output as follows:

        INFO   Cage types: ['12', '16']
        INFO   Cage type 12: {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 144, 145, 146, 147, 148, 149, 150, 151, 152, 153, 154, 155, 156, 157, 158, 159, 168, 169, 170, 171, 172, 173, 174, 175, 176, 177, 178, 179, 180, 181, 182, 183}
        INFO   Cage type 16: {136, 137, 138, 139, 140, 141, 142, 143, 16, 17, 18, 19, 20, 21, 22, 23, 160, 161, 162, 163, 164, 165, 166, 167, 40, 41, 42, 43, 44, 45, 46, 47, 184, 185, 186, 187, 188, 189, 190, 191, 64, 65, 66, 67, 68, 69, 70, 71, 88, 89, 90, 91, 92, 93, 94, 95, 112, 113, 114, 115, 116, 117, 118, 119}

  This indicates that there are two types of cages named `12` and `16`. Fill the `16` cages with THF and put a methane molecule in the `0`th cage of type `12` as follows:

        genice2 CS2 -g 16=uathf -G 0=me > CS2.gro

Although only a few kinds of guest molecules are preset, you can easily prepare new guest molecules as a module. Here is an example of the ethylene oxide molecule.

```python
import numpy as np
import genice2.molecules

class Molecule(genice2.molecules.Molecule):
    def __init__(self):
        # United-atom EO model with a dummy site
        LOC = 0.1436 # nm
        LCC = 0.1472 # nm

        Y = (LOC**2 - (LCC/2)**2)**0.5

        self.sites = np.array([[ 0.,    0., 0. ],
                               [-LCC/2, Y,  0. ],
                               [+LCC/2, Y,  0. ],])

        mass = np.array([16,14,14])
        # center of mass
        CoM = mass @ self.sites / np.sum(mass)
        self.sites -= CoM

        self.atoms_  = ["O","C","C"]
        self.labels_ = ["Oe","Ce","Ce"]
        self.name_   = "EO"
```

Write the code in eo.py. Make a folder named `molecules` in the current working directory and put it in.

_Note_: multiple occupancy is not implemented. If it is required, make a module of a virtual molecule that contains multiple molecules.

## Doping ions

Small ions may replace the host molecules. In that case, you can use `-a` and `-c` options to replace the specified water molecules with anions and cations.

The following example replaces the `0`th water molecule (in the replicated lattice) with Na cation and `1`st water molecule with Cl anion. The hydrogen bonds around the ions are organized appropriately.

    genice2 CS2 --depol=optimal -c 0=Na -a 1=Cl > CS2.gro

_Note 1_: The numbers of cations and anions must be the same. Otherwise, the ice rule is never satisfied and the program does not stop.

_Note 2_: The option `--depol=optimal` is also required because it is impossible to completely depolarize the structure containing ions.

_Note 3_: Protonic defects (H<sub>3</sub>O<sup>+</sup> and OH<sup>-</sup>) are not yet implemented.

## Semiclathrate hydrates

### Placement of a tetrabutylammonium ion (testing)

Let us assume that the id of the water molecule to be replaced by nitrogen of the TBA as zero. Place the nitrogen as a cation and also replace the water 2 by the counter-ion Br.

    genice2 HS1 -c 0=N -a 2=Br --depol=optimal > HS1.gro

Then you will see the following info.

```
INFO   Hints:
INFO     Cage types: ['12', '14', '15']
INFO     Cage type 12: {0, 1, 2, 3, 4, 5}
INFO     Cage type 14: {8, 9, 6, 7}
INFO     Cage type 15: {10, 11, 12, 13}
...
INFO Stage7: Arrange guest atoms.
INFO     Cages adjacent to dopant 2: {0, 9, 2, 13}
INFO     Cages adjacent to dopant 0: {0, 9, 2, 7}
```

It indicates that the nitrogen is surrounded by cages with ids 0, 9, 2, and 7. Types for these cages can also be found in the info. Then, we put the Bu- group (minus does not mean ions) in these cages adjacent to dopant 0.

```shell
% genice2 HS1 -c 0=N -a 2=Br -H 0=Bu-:0 -H 9=Bu-:0 -H 2=Bu-:0 -H 7=Bu-:0 --depol=optimal > HS1.gro
```

Here the option `-H` specifies the group by `-H (cage id)=(group name):(root)`, and the root is the nitrogen that is specified by `-c` (cation) option.

### Placement of TBAB in the lattice module

_Under preparation_

It is more convenient if the lattice of the semiclathrate hydrate contains molecular ions in the appropriate locations in advance. Here we explain the way to make the special module for semclathrates.

## Output formats

| Name                     | Application                                                                                                           | extension    | water            | solute           | HB   | remarks                                                                                                                      |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------ | ---------------- | ---------------- | ---- | ---------------------------------------------------------------------------------------------------------------------------- |
| `cif`, `cif2`            | CIF                                                                                                                   | `.cif`       | Atomic positions | Atomic positions | none | Experimental                                                                                                                 |
| `g`, `gromacs`           | [Gromacs](http://www.gromacs.org)                                                                                     | `.gro`       | Atomic positions | Atomic positions | none | Default format.                                                                                                              |
| `m`, `mdview`            | MDView                                                                                                                | `.mdv`       | Atomic positions | Atomic positions | auto |
| `mdv_au`                 | MDView                                                                                                                | `.mdv`       | Atomic positions | Atomic positions | auto | In atomic unit.                                                                                                              |
| `o`, `openscad`          | [OpenSCAD](http://www.openscad.org)                                                                                   | `.scad`      | Center of mass   | none             | o    | See tests/art/openscad for usage.                                                                                            |
| `povray`                 | Povray                                                                                                                | `.pov`       | Atomic positions | Atomic Positions | o    |
| `towhee`                 | TowHee                                                                                                                | `.coords`(?) | Atomic positions | Atomic positions | none |
| `xyz`                    | XYZ                                                                                                                   | `.xyz`       | Atomic positions | Atomic positions | none | Experimental                                                                                                                 |
| `exyz`                   | [extended XYZ](http://open-babel.readthedocs.io/en/latest/FileFormats/Extended_XYZ_cartesian_coordinates_format.html) | `.xyz`       | Atomic positions | Atomic positions | none | Extended XYZ format defined in Open Babel                                                                                    |
| `exyz2`                  | [extended XYZ](http://libatoms.github.io/QUIP/io.html#extendedxyz)                                                    | `.xyz`       | Atomic positions | Atomic positions | none | Extended XYZ format defined in QUIP                                                                                          |
| `y`, `yaplot`            | [Yaplot](https://github.com/vitroid/Yaplot)                                                                           | `.yap`       | Atomic positions | Atomic positions | o    | It renders molecular configurations and the HB network.                                                                      |
| `e`, `euler`             | Euler angles                                                                                                          | `.nx3a`      | Rigid rotor      | none             | none |
| `q`, `quaternion`        | Quaternions                                                                                                           | `.nx4a`      | Rigid rotor      | none             | none |
| `d`, `digraph`           | Digraph                                                                                                               | `.ngph`      | none             | none             | o    |
| `graph`                  | Graph                                                                                                                 | `.ngph`      | none             | none             | o    | Experimental.                                                                                                                |
| `c`, `com`               | CenterOfMass                                                                                                          | `.ar3a`      | Center of mass   | none             | none |
| `r`, `rcom`              | Relative CoM                                                                                                          | `.ar3r`      | Center of mass   | none             | none | In fractional coordinate system.                                                                                             |
| `p`, `python`, `reshape` | Python module                                                                                                         | `.py`        | Center of mass   | none             | none | Under development.                                                                                                           |
| `_ringstat`              | Ring phase statistics                                                                                                 |              |                  |                  |      | Statistical test suite 1: Check the appearance frequencies of the ring phases as a test for the intermediate-range disorder. |
| `rings`                  | [Yaplot](https://github.com/vitroid/Yaplot)                                                                           | `.yap`       | center of mass   | none             | o    | It renders HB rings.                                                                                                         |
| `_KG`                    | Kirkwood G(r)                                                                                                         |              |                  |                  |      | Statistical test suite 2: Calculate G(r) for checking long-range disorder in molecular orientations.                         |

By installing the [`genice2-mdanalysis`](https://github.com/vitroid/genice-mdanalysis) package separately, you can generate files in many formats for a large number of molecular dynamics package softwares. E.g.

```shell
% pip install genice2-mdanalysis
% genice2 1c -f 'mdanalysis[1c.pdb]'
% genice2 1h -f 'mdanalysis[1h.xtc]'
```

All the supported file types are listed in the [MDAnalysis web page](https://docs.mdanalysis.org/stable/documentation_pages/coordinates/init.html#supported-coordinate-formats).

You can prepare your file formats. Create a folder named `formats` in the current working directory and put the plugins in it.

Internally, there are seven stages to generate an ice structure.

1. Cell repetition.
2. Random graph generation and replication.
3. Apply ice rule.
4. Depolarize.
5. Determine orientations of the water molecules.
6. Place atoms in water molecules.
7. Place atoms in guests.

In the format plugin, you define the hook functions that are invoked after processing each stage.

## Ice structures

| Symbol | <div style='width:300px'>Description</div> |
| ------ | ------------------------------------------ |
0, ice0 | Metastable ice "0". [Russo 2014]
11, XI, ice11 | A candidate for an antiferroelectric Ice XI #19. [Jackson 1997, Fan 2010]
115_2_114, 12_1_11, 144_2_7301, 151_2_4949650, 153_2_155471, 176_2_5256, 207_1_4435, 2_2_623457, ACO, CS4, DDR, IWV, LTA, MAR, NON, PCOD8007225, PCOD8036144, PCOD8204698, PCOD8301974, PCOD8321499, PCOD8324623, SGT, SOD, engel01, engel03, engel04, engel17, engel20, engel23, engel24, engel26, engel29, engel30, engel31, engel34, sVII | Hypothetical zeolitic ice [Jeffrey 1984, Kosyakov 1999, Engel 2018, IZA Database]
11alt | A layered ferroelectric Ice XI.
11i | Sixteen candidates for Ice XI. [Hirsch 2004]
12, XII, ice12 | Metastable high-pressure ice XII. [Lobban 1998, Koza 2000]
13, XIII, ice13 | Ice XIII, a hydrogen-ordered counterpart of ice V. [Salzmann 2006]
14, ice14 | Ice XIV, a partially hydrogen-ordered counterpart of ice XII. Note that it does not reproduce the occupancies (probability of occupation) of the possible hydrogen sites. [Salzmann 2006]
16, CS2, MTN, XVI, ice16, sII | Ultralow-density Ice XVI. [Jeffrey 1984, Kosyakov 1999, Sikiric 2010, Falenty 2014, IZA Database]
17, XVII, ice17 | Ultralow-density Ice XVII. [Smirnov 2013, Rosso 2016, Strobel 2016]
1c, Ic, ice1c | Cubic type of ice I. [Vos 1993]
1h, Ih, ice1h | Most popular Ice I (hexagonal). NOTE: Due to a historical reason, the crystal axes of hexagonal ice are exchanged. If you want the basal plane to be Z axis, please use 'one[hh]' instead.
2, II, ice2 | Hydrogen-ordered ice II. [Kamb 1964, Londono 1988, Kamb 2003]
2D3 | Trilayer honeycomb ice.
2d, ice2d, ice2rect | A hydrogen-disordered counterpart of ice II. [Nakamura 2015]
3, III, ice3 | Ice III. [Petrenko 1999]
4, IV, ice4 | Ice IV. [Avogadro]
4R | Orthogonalized ice IV. [Avogadro]
5, V, ice5 | Monoclinic ice V (testing).
5R | Ice V with orthogonal unit cell. (testing)
6, VI, ice6 | Conventional high-pressure ice VI. [Petrenko 1999]
6h | Half lattice of ice VI.
7, VII, ice7 | Conventional high-pressure ice VII.
8, VIII, ice8 | Ice VIII, a hydrogen-ordered counterpart of ice VII. [Kuhs 1998]
9, IX, ice9 | Ice IX, a hydrogen-ordered counterpart of ice III. [Londono 1993]
A, iceA | Hypothetical ice A. [Baez 1998]
A15, Struct33 | Cubic Structure I of clathrate hydrate. [Sikiric 2010]
B, iceB | Hypothetical ice B. [Baez 1998]
BSV, engel05 | Hypothetical zeolitic ice of the gyroid structure. [Engel 2018, IZA Database]
C14, C15, C36, FK6layers, FK9layers, HS2, Hcomp, Struct01, Struct03, Struct04, Struct05, Struct06, Struct07, Struct08, Struct09, Struct10, Struct11, Struct12, Struct13, Struct14, Struct15, Struct16, Struct17, Struct18, Struct19, Struct20, Struct21, Struct22, Struct23, Struct24, Struct25, Struct26, Struct27, Struct28, Struct29, Struct30, Struct31, Struct32, Struct34, Struct35, Struct36, Struct37, Struct38, Struct39, Struct40, Struct41, Struct42, Struct43, Struct44, Struct45, Struct46, Struct47, Struct48, Struct49, Struct50, Struct51, Struct52, Struct53, Struct54, Struct55, Struct56, Struct57, Struct58, Struct59, Struct60, Struct61, Struct62, Struct63, Struct64, Struct65, Struct66, Struct67, Struct68, Struct69, Struct70, Struct71, Struct72, Struct73, Struct74, Struct75, Struct76, Struct77, Struct78, Struct79, Struct80, Struct81, Struct82, Struct83, Struct84, Z, delta, mu, psigma, sV, sigma, zra-d | A space fullerene. [Sikiric 2010]
CRN1, CRN2, CRN3 | A continuous random network of Sillium. [Mousseau 2001]
CS1, MEP, sI | Clathrate hydrates sI. [Frank 1959, Jeffrey 1984, Kosyakov 1999, IZA Database]
DOH, HS3, sH | Clathrate type H.
EMT | Hypothetical ice with a large cavity. [Liu 2019, IZA Database]
FAU | Hypothetical ice at negative pressure ice 'sIV'. [Huang 2017, IZA Database]
HS1, sIV | Hydrogen-disordered ice Ih. [Kosyakov and Polyanskaya 1999]
M, iceM | A hypothetical hydrogen-ordered high-density ice. [Mochizuki 2024]
RHO | Hypothetical ice at negative pressure ice 'sIII'. [Huang 2016, IZA Database]
Struct02 | A space fullerene. (I phase?) [Sikiric 2010]
T | Hypothetical clathrate type T. [Sikiric 2010, Karttunen 2011]
XIc-a | A candidate for the proton-ordered counterpart of ice Ic. The structure 'a' in Figure 1. [Geiger 2014]
YKD | Ice in a d-surface (testing). [Kawano 2024]
bilayer | A Bilayer Honeycomb Ice Phase in Hydrophobic Nanopores. [Koga 1997]
c0te | Filled ice C0 by Teeratchanan (Hydrogen-disordered.) (Positions of guests are supplied.) [Teeratchanan 2015]
c1te | Hydrogen-ordered hydrogen hydrate C1 by Teeratchanan. (Positions of guests are supplied.) [Teeratchanan 2015]
c2te | Filled ice C2 (cubic ice) by Teeratchanan (Hydrogen disordered). (Positions of guests are supplied.) [Teeratchanan 2015]
eleven | Ice XI w/ stacking faults.
i | Hypothetical ice "i". [Fennell 2005]
ice1hte | Filled ice Ih by Teeratchanan (Hydrogen disordered). (Positions of guests are supplied.) [Teeratchanan 2015]
iceL | The hypothetical Ice L [Lei 2025]
iceMd | A hydrogen-disordered counterpart of ice M. [Mochizuki 2024]
iceR | Hypothetical ice R. [Maynard-Casely 2010, Mochizuki 2014]
iceT | Hypothetical ice T. [Hirata 2017]
iceT2 | Hypothetical ice T2. [Yagasaki 2018]
one | Ice I w/ stacking disorder.
oprism | Hydrogen-ordered ice nanotubes. [Koga 2001]
sTprime | Filled ice sT'. [Smirnov 2013]
xFAU | Aeroice xFAU. [Matsui 2017]
xdtc | A porous ice with cylindrical channels. [Matsumoto 2021]
1h_unit, TS1, dtc, ice1h_unit, sIII | (Undocumented)


Ice names with double quotations are not experimentally verified.

You can prepare your own ice structures. Create a folder named `lattices` in the current working directory and put the plugins in it.

[cif2ice](https://github.com/vitroid/cif2ice) is a t