API reference

class interface_builder.interface_builder.Silica(lx=None, ly=None, lz=None, output_folder=None, input_folder=None, vacuum=None, sio2_potential=None, sio2_h2o_potential=None, h2o_potential=None, filename='silica_quartz.data')

A class for generating and manipulating silica substrates.

This class provides functionality for creating silica substrates with customizable dimensions and properties. It supports various operations such as adjusting positioning, adding vacuum layers, passivation, thermalization, annealing, and introducing water molecules. Both amorphous and quartz silica structures can be constructed.

Parameters:

lx (float) – Length of the substrate in the x-direction.
ly (float) – Length of the substrate in the y-direction.
lz (float) – Length of the substrate in the z-direction.
output_folder (str) – Path to the output folder where generated data will be saved.
input_folder (str) – Path to the input folder containing necessary files.
vacuum (float) – Size of the vacuum layer to be added around the substrate.
sio2_potential (str) – Potential used for silica interactions.
sio2_h2o_potential (str) – Potential used for interactions between silica and water.
h2o_potential (str) – Potential used for water interactions.
filename (str) – Name of the file to save the silica substrate data.

Example:

Create a silica substrate with dimensions 10x10x5 Angstroms, using Vashishta potential for silica interactions, and save the data to the ‘output’ folder.

>>> substrate = Silica(lx=10, ly=10, lz=5, output_folder='output',
...                              sio2_potential='SiO2.mod')

add_vacuum(datafile, output_filename=None, which=None, overwrite=False, run=True)

Add vacuum space to the z-dimension of the system in the input data file. This method adds vacuum space to the z-dimension of the system in the input data file, effectively increasing its size along the z-axis.

Parameters:

datafile (str) – The filename of the input data file containing the system.
vacuum (float) – The amount of vacuum space to add to the z-dimension of the system.
output_filename (str or None) – (Optional) The filename for the output data file with the added vacuum space. If not provided, the input data file is overwritten. Default is None.
overwrite (bool) – (Optional) Whether to overwrite the input data file with the system containing added vacuum space. If False, a new output file with the added vacuum space is created. Default is False.
run (bool) – (Optional) Whether to perform the operation of adding vacuum space. Default is True.

Returns:

The filename of the data file containing the system with added vacuum space.

Return type:

str

add_water(datafile, dimensions, center=None, num_mol=None, output_filename='water-silica_system-new.data', thermalized_h2o=None, geometry='rectangle', mpirun_n=4, lmp_exec='lmp', run=True)

Add a water slab on top of a silica system. This method adds a water slab on top of a silica system and runs a thermalization simulation if specified.

Parameters:

datafile (str) – The filename of the input data file containing the silica system.
dimensions (tuple) – The dimensions of the silica system in the format (lx, ly, lz).
num_molecules (int or None) – (Optional) The number of water molecules to add. Default is None.
thermalized_water (float or None) – (Optional) The temperature for thermalization of water molecules. Default is None.
geometry (str) – (Optional) The geometry of the water slab. Default is “rectangle”.
mpirun_n (int) – (Optional) The number of MPI processes to use for the simulation. Default is 4.
lmp_exec (str) – (Optional) The LAMMPS executable path or command. Default is “lmp”.
run (bool) – (Optional) Whether to run the simulation. Default is True.

Returns:

The filename of the output data file containing the silica-water system.

Return type:

str

anneal(datafile, anneal_time=None, mpirun_n=4, lmp_exec='lmp', run=True)

Run a basic annealing procedure on the system.

Parameters:

datafile (str) – The filename of the input data file containing the system configuration.
anneal_time (float) – The duration of the annealing procedure.
run (bool) – (Optional) Whether to run the annealing procedure. Default is True.
mpirun_n (int) – (Optional) The number of MPI processes to use for the annealing simulation. Default is 4.
lmp_exec (str) – (Optional) The LAMMPS executable path or command. Default is ‘lmp’.

Returns:

The filename of the output data file containing the annealed system configuration.

Return type:

str

build_amorphous(mpirun_n=None, lmp_exec='lmp', cristobalite=None, seed=None, cluster=None, run=True, partition=None)

Build an amorphous system using molecular dynamics simulation. This method constructs an amorphous system by annealing the beta cristobalite structure using molecular dynamics simulation.

Parameters:

mpirun_n (int or None) – (Optional) The number of MPI processes to use for the simulation.
lmp_exec (str) – (Optional) The LAMMPS executable path or command. Default is “lmp”.
cristobalite (str or None) – (Optional) The filename of the beta cristobalite structure data file. If not provided, it will be generated.
cluster (str or None) – (Optional) Cluster information for parallel execution. Default is None.
run (bool) – (Optional) Whether to run the simulation. Default is True.
partition (str or None) – (Optional) The partition information for parallel execution. Default is None.

Returns:

The filename of the output amorphous system data file.

Return type:

str

build_quartz()

Create a quartz silica slab. Process the quartz crystal structure and write it to a file in LAMMPS data format. see: https://henriasv.github.io/molecular-builder for more info.

Returns:: The filename of the output LAMMPS data file.
Return type:: str

build_water(dimension=None, num_mol=None, output_file=None, buffer=0.5, mpirun_n=1, lmp_exec='lmp', run=False)

Builds a water system with the specified dimensions and number of water molecules.

Constructs a water system with the specified dimensions and number of water molecules. If dimensions are not provided, the method uses the number of molecules to determine the system size. The generated water system is saved to a data file.

Parameters:

dimension (tuple[float, float, float], optional) – The dimensions (lx, ly, lz) of the water system in Angstroms. If None, the system size is determined by the number of molecules. Default is None.
num_mol (int, optional) – The number of water molecules to include in the water system. Default is None.
output_file (str, optional) – The filename for the output data file containing the water system. Default is None.
buffer (float, optional) – The buffer distance (in Angstroms) between the water system and the boundaries of the simulation box. Default is 0.5.
mpirun_n (int, optional) – Number of MPI processes to use. Default is 1.
lmp_exec (str, optional) – The executable name or path for LAMMPS. Default is “lmp”.
run (bool, optional) – Indicates whether to execute the LAMMPS simulation. Default is False.

Returns:

The filename of the output data file containing the water system.

Return type:

str

Example:

>>> substrate = Silica(lx=10, ly=10, lz=5, output_folder='output')
>>> water_system_file = substrate.build_water(dimension=(10, 10, 5), num_mol=100)
'water.data'

execute_lammps(lmps_args, mpirun_n=4, lmp_exec='lmp', script=None, slurm=False)

Execute a LAMMPS simulation with the given arguments. This method executes a LAMMPS simulation using the specified LAMMPS executable and input script, along with additional arguments provided in the lmps_args dictionary.

Parameters:

lmps_args (dict) – A dictionary containing the LAMMPS variables and their corresponding values.
mpirun_n (int) – (Optional) The number of MPI processes to use for the simulation. Default is 4.
lmp_exec (str) – (Optional) The path to the LAMMPS executable. Default is ‘lmp’.
script (str or None) – (Optional) The path to the input script for LAMMPS. If provided, this takes precedence over the slurm parameter. Default is None.
slurm (bool) – (Optional) If True, run the simulation using Slurm on a HPC cluster. Default is False.

Returns:

None

get_coordination(filename)

Analyzes the coordination of atoms in the substrate based on a given data file.

Reads the atomic configuration data from the specified filename, replaces ‘H’ atoms with ‘O’ atoms (silica and water respectively), calculates the coordination of each atom, and identifies defects in the substrate based on coordination count.

Parameters:: filename (str) – The filename of the input data file containing atomic configuration.
Returns:: A tuple containing the number of defects for ‘O’ atoms (with less than 2 neighbors) and ‘Si’ atoms (with less than 4 neighbors).
Return type:: tuple[int, int]

Example:

>>> substrate = Silica(lx=10, ly=10, lz=5, output_folder='output')
>>> substrate.get_coordination(filename='amorphous.data')
(10, 5)

get_heat_of_immersion(datafile, num_h2o=None, h2o_therm_time=50, sio2_therm_time=50, output_filename='water_silica_system.data', buffer=0.5, surface_dist=1, mpirun_n=16, lmp_exec_h2o='lmp', lmp_exec_interface='lmp_usc', run=True)

Simulates the heat of immersion of a water-silica system.

This method constructs a water-silica system, simulates its equilibration, calculates the heat of immersion based on the energy difference between the hydrated silica slab and the passivated silica slab, and returns the calculated heat of immersion.

Parameters:

datafile (str) – The filename of the input data file containing the atomic configuration of the silica system.
num_h2o (int, optional) – The number of water molecules to include in the water-silica system. Default is None.
h2o_therm_time (float, optional) – The thermalization time (in ps) for the water system. Default is 50.
sio2_therm_time (float, optional) – The thermalization time (in ps) for the silica system. Default is 50.
output_filename (str, optional) – The filename for the output data file containing the water-silica system. Default is “water_silica_system.data”.
buffer (float, optional) – The buffer distance (in Angstroms) between the water and silica surfaces. Default is 0.5.
surface_dist (float, optional) – The distance (in Angstroms) between the silica surface and the water surface. Default is 1.
mpirun_n (int, optional) – Number of MPI processes to use. Default is 16.
lmp_exec_h2o (str, optional) – The executable name or path for LAMMPS used for the water system simulation. Default is “lmp”.
lmp_exec_interface (str, optional) – The executable name or path for LAMMPS used for the interface simulation. Default is “lmp_usc”.
run (bool, optional) – Indicates whether to execute the LAMMPS simulations. Default is True.

Returns:

The heat of immersion in Joules per square meter (J/m^2).

Return type:

float

Notes:

This method requires the existence of certain log files in the output folder:
- log_silica-thermalized.lammps
- log_watersilica-thermalized.lammps
- log_water.lammps
The calculated heat of immersion is printed to the console.
The method utilizes several other internal methods such as _calculate_heat_of_immersion.

Example:

>>> substrate = Silica(lx=10, ly=10, lz=5, output_folder='output')
>>> heat_of_immersion = substrate.get_heat_of_immersion(datafile='silica.data', num_h2o=100)
0.5181940280748683

get_silanol(datafile)

Calculate the density of silanol groups in the silica system.

This method calculates the density of silanol groups in the silica system described by the provided datafile. Silanol groups are hydroxyl (-OH) functional groups attached to the silica surface.

Parameters:: datafile (str) – The filename of the input data file containing the silica system.
Returns:: The density of silanol groups in the silica system, measured in silanol groups per square nanometer (nm^-2).
Return type:: float

minimize_sio2(datafile, output_filename=None, mpirun_n=4, lmp_exec='lmp', run=True)

Run a minimization procedure to optimize the structure of silica.

Parameters:

datafile (str) – The filename of the input data file containing the initial structure of silica.
mpirun_n (int) – (Optional) The number of MPI processes to use for the minimization simulation. Default is 4.
lmp_exec (str) – (Optional) The LAMMPS executable path or command. Default is ‘lmp’.
run (bool) – (Optional) Whether to run the minimization simulation. Default is True.

Returns:

The filename of the output data file containing the minimized silica structure.

Return type:

str

passivate(datafile, passivation_time, output_file, water_thickness=10, run=True, mpirun_n=4, lmp_exec='lmp_mpi')

Run a passivation simulation.

Parameters:

datafile (str) – The filename of the input data file.
passivation_time (float) – The duration of the passivation simulation.
output_file (str) – The filename for the output data file.
thickness (int) – (Optional) The thickness of the water slab to be immersed in the silica surface. Default is 10.
run (bool) – (Optional) Whether to run the passivation simulation. Default is True.
mpirun_n (int) – (Optional) The number of MPI processes to use for the passivation simulation. Default is 4.
lmp_exec (str) – (Optional) The LAMMPS executable path or command. Default is ‘lmp_mpi’.

Returns:

The filename of the output data file.

Return type:

str

replicate(dimension, input_filename, output_filename, mpirun_n=1, lmp_exec='lmp', run=True)

Replicates the atomic configuration of the substrate in all dimensions.

Replicates the atomic configuration specified by the input data file along the x, y, and z dimensions to create a larger substrate. The replicated configuration is saved to a new file with the specified output filename.

Parameters:

dimension (tuple[float, float, float]) – The dimensions (lx, ly, lz) of the replication in Angstroms.
input_filename (str) – The filename of the input data file containing the atomic configuration to be replicated.
output_filename (str) – The filename for the output data file with the replicated configuration.
mpirun_n (int, optional) – Number of MPI processes to use. Default is 1.
lmp_exec (str, optional) – The executable name or path for LAMMPS. Default is “lmp”.
run (bool, optional) – Indicates whether to execute the LAMMPS simulation after replication. Default is True.

Returns:

The filename of the output data file with the replicated configuration.

Return type:

str

Example:

>>> substrate = Silica(lx=10, ly=10, lz=5, output_folder='output')
>>> substrate.replicate(dimension=(20, 20, 10), input_filename='data.lmp', output_filename='replicated_data.lmp')
'replicated_data.lmp'

resize_z(datafile, z_value, output_filename=None, overwrite=False, run=True)

Resize the z-dimension of the system in the input data file. This method resizes the z-dimension of the system in the input data file to the specified value.

Parameters:

datafile (str) – The filename of the input data file containing the system.
z_value (float) – The new value for the z-dimension of the system.
output_filename (str or None) – (Optional) The filename for the output data file with the resized system. If not provided, the input data file is overwritten. Default is None.
overwrite (bool) – (Optional) Whether to overwrite the input data file with the resized system. If False, a new output file with the resized system is created. Default is False.
run (bool) – (Optional) Whether to perform the resizing operation. Default is True.

Returns:

The filename of the data file containing the resized system.

Return type:

str

set_silanol(silanol_concentration, input_filename, output_filename=None, delete_oxygen=True, run=True)

Set the concentration of silanol groups in the silica structure.

Parameters:

silanol_concentration (float) – The concentration of silanol groups to set in the structure.
input_filename (str) – The filename of the input structure file.
output_filename (str) – The filename for the output structure file with modified silanol concentration.
lmp_exec (str) – (Optional) The LAMMPS executable path or command. Default is “lmp”.
delete_oxygen (bool) – (Optional) Whether to delete oxygen atoms. Default is True.
run (bool) – (Optional) Whether to run the simulation. Default is True.

Returns:

The filename of the output structure file with modified silanol concentration.

Return type:

str

shift_z_origin(filename, z_shift=0, output_filename='silica_shifted_z.data')

Shifts the origin of the substrate in the z-direction by a specified amount.

Reads the atomic configuration data from the specified filename, shifts the positions of all atoms in the z-direction by the specified amount, and writes the modified configuration data to a new file with the specified output filename.

Parameters:

filename (str) – The filename of the input data file containing atomic configuration.
z_shift (float, optional) – The amount by which to shift the origin in the z-direction. Default is 0.
output_filename (str, optional) – The filename for the output data file with the shifted origin. Default is “silica_shifted_z.data”.

Returns:

The filename of the output data file with the shifted origin.

Return type:

str

Example:

>>> substrate = Silica(lx=10, ly=10, lz=5, output_folder='output')
>>> substrate.shift_z_origin('silica_passivated.data', z_shift=2.0)
"silica_shifted_z.data"

thermalize(datafile, time, temp, press=1, ensemble='NVT', output_filename='silica-thermalize.data', mpirun_n=4, lmp_exec='lmp', run=True)

Run a thermalization procedure on the system.

Parameters:

datafile (str) – The filename of the input data file.
time (float) – The time duration for thermalization.
temp (float) – The temperature for thermalization.
output_filename (str or None) – (Optional) The filename for the output data file.Default is silica_thermaliz.data.
mpirun_n (int) – (Optional) The number of MPI processes to use for the thermalization simulation. Default is 4.
lmp_exec (str) – (Optional) The LAMMPS executable path or command. Default is ‘lmp’.
run (bool) – (Optional) Whether to run the thermalization simulation. Default is True.

Returns :return: The filename of the output data file, if provided. :rtype: str or None

thermalize_passivated(datafile, time, temp, output_filename='silica_passivated-thermalize.data', mpirun_n=4, lmp_exec='lmp', run=True)

Run a thermalization procedure on the system.

Parameters:

datafile (str) – The filename of the input data file.
time (float) – The time duration for thermalization.
temp (float) – The temperature for thermalization.
output_filename (str or None) – (Optional) The filename for the output data file. Default is silica_passivated-thermalize.data.
mpirun_n (int) – (Optional) The number of MPI processes to use for the thermalization simulation. Default is 4.
lmp_exec (str) – (Optional) The LAMMPS executable path or command. Default is ‘lmp’.
run (bool) – (Optional) Whether to run the thermalization simulation. Default is True.

Returns:

The filename of the output data file, if provided.

Return type:

str or None