YAML file
For the .yaml file to be read by ClayCode.builder, the relative path must be specified when calling the function.
Multiple YAML files are supplied with ClayCode within the Tutorial directory. The files are named by their corresponding clay system (e.g. NAu1.yaml), and can be used as examples.
Required Parameters
The required input parameters are general directives for model construction.
OUTPUT: /path/to/directory [ str ]Path to directory in which the output folder is created
CLAY_COMP: /path/to/file.csv [ str ]Path to input .csv file
SYSNAME: clay_name [ str ]Name of the clay system. It must match a column header in the CSV file. The created output folder will also have this name.
CLAY_TYPE: unit_cell [ str ]Clay unit cell type. Must match a directory in
data/UCS/ (see data files). For example, a Dioctahedral 2:1 unit cell is D21.Note: Only D11, D21 and T21 are supplied with the current release.
Optional Parameters
There are a number of optional parameters. If no directives are given by the user, ClayCode.builder will use the default values.
Clay Sheet Size
X_CELLS: x_unit_cells [ int ] (Default = 5)Number of unit cells in the x-direction
Y_CELLS: y_unit_cells [ int ] (Default = 5)Number of unit cells in the y-direction
N_SHEETS: sheet_number [ int ] (Default = 5)Number of sheets of 1 unit cell thickness to be stacked in the z direction
Clay Composition
ClayCode.builder uses the supplied .csv file to calculate the number and type of unit cells necessary to match the desired composition. The way in which ClayCode will match this target composition can be specified.
OCC_TOL: occupation_tolerance [ float ] (Default = 0.1)The maximum occupancy/charge deviation for a unit cell that is adjusted without querying to match the expected values.
E.g. with an expected
csv:T total unit cell occupancy of 4 and OCC_TOL of 0.1, any composition with tetrahedral occupancies between 3.9 and 4.1 will be automatically adjusted to match the expected value.ZERO_THRESHOLD: threshold [ float ] (Default = 0.05)The occupancy threshold below which the matched composition will be set to 0 if the element is not found in the force field or in the unit cell database.
SEL_PRIORITY: charge_correction [ str ] (Default = charges)The priority to use when correcting charges and substitution occupancies.
E.g. An octahedral charge of -0.3 and a “mgo” occupancy of 0.4 is not possible, and one needs to be adjusted.
There are two possible options:
1.
charges: Conserve specified charges and adjust substitution occupancies. E.g. mgo: 0.4 -> 0.32.
occupancies: Conserve occupancies and adjust charges. E.g. -0.3 e -> -0.4 eCHARGE_PRIORITY: charge_correction [ str ] (Default = total_charge)The priority to use when individual sheet and total charge do not match.
E.g. total charge = -1.00 but tetrahedral charge = -0.70 and octahedral charge = -0.40
There are two possible options:
1.
total_charge: Conserve the total charge and adjust tetrahedral and octahedral occupancies. E.g. tetrahedral charge: -0.70 -> -0 .65 and octahedral charge: -0.40 -> -0.352.
sheet_charges: Conserve the sheet charges and adjust total charge. E.g. total charge: -1.00 -> 1.10MATCH_TOLERANCE: tolerance [ float ] (Default = 0.02)The maximum total occupancy deviation from the corrected target stoichiometry.
No CSV File
The clay composition can also be supplied manually in the .yaml file using the following parameters. See the Pyrophyllite tutorial for an example.
UC_INDEX_LIST: unit_cells [ list ]List of unit cells to be used for building the model. These must have corresponding
.gro and .itp files in the data/UCS/CLAY_TYPE directory.UC_RATIOS_LIST: cell_probabilities [ list ]List of probabilities for the above unit cells. The total probability must equal 1.
IL_ION_RATIOS: ions_and_ratios [ dict[str: int] ] (Default = Ca: 1 Cl: 1)The interlayer ions to be used and the ratio between them. The sum of all cation/anion contributions should be 1. Only ion species of the opposite sign to the layer charge will be considered.
Interlayer Solvent and Ions
IL_SOLV: solvent_presence [ bool ] (Default = True)If false a non-hydrated clay will be created. If true the interlayer space will be solvated, and one further option is needed on how to handle it. The default option is
UC_WATERS: 20.1.
ION_WATERS: waters_per_ion [ int, dict[str: int] ]The number of water molecules that should be added per interlayer ion. If a single integer is given, all ions will be hydrated by the same number of water molecules. To specify the number of waters per ion-type a dictionary should be given.
2.
UC_WATERS: waters_per_uc [ int ] (Default = 20)The number of water molecules to add per unit cell. The total number of water added is the number specified multiplied by the number of unit cells used to create the model.
3.
SPACING_WATERS: hydrated_spacing [ float ]The target hydrated interlayer spacing, in angstroms (Å). The final value may vary due to the water rearrangement when in contact with clay surface and packing around ions.
Simulation Box
BOX_HEIGHT: z_box_length [ float ] (Default = 15.0)The size of the final simulation box along the z-axis, in nanometers (nm).
Note: The clay layers are positioned in the xy-plane.
BULK_SOLV: solvent_presence [ bool ] (Default = True)If true the box space will be solvated. If false the box will be empty. This is useful if the further plan is to add other species, such as oil.
BULK_IONS: ion_type_conc [ dict[str: int] ] (Default = ‘Na’: 0.0 ‘Cl’: 0.0)The type and concentration (in mol/L) of ions to to be added into the bulk space.
Note: GROMACS will raise a warning if the system isn’t neutral.
GROMACS version
GMX: bash_alias [ str ]Allows the user to specify which version of GROMACS to use if they have multiple installed.