mdsuite.experiment.experiment module

MDSuite: A Zincwarecode package.

License

This program and the accompanying materials are made available under the terms of the Eclipse Public License v2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-v20.html

SPDX-License-Identifier: EPL-2.0

Copyright Contributors to the Zincwarecode Project.

Contact Information

email: zincwarecode@gmail.com github: https://github.com/zincware web: https://zincwarecode.com/

Citation

If you use this module please cite us with:

Summary

class mdsuite.experiment.experiment.Experiment(project, name, time_step=None, temperature=None, units: Optional[Union[str, Units]] = None, cluster_mode=False)

Bases: ExperimentDatabase

The central experiment class fundamental to all analysis.

project = mdsuite.Project()
project.add_experiment(
    name="NaCl",
    timestep=0.002,
    temperature=1400.0,
    units="metal",
    simulation_data="NaCl_gk_i_q.lammpstraj"
    )
project.experiments.NaCl.run.RadialDistributionFunction(
    number_of_configurations=500
)

name

The name of the analysis being performed e.g. NaCl_1400K

Type:

str

storage_path

Path to where the tensor_values should be stored (best to have drive capable of storing large files)

Type:

str

temperature

The temperature of the simulation that should be used in some analysis. Necessary as it cannot be easily read in from the simulation tensor_values.

Type:

float

time_step

Time step of the simulation e.g 0.002. Necessary as it cannot be easily read in from the trajectory.

Type:

float

volume

Volume of the simulation box

Type:

float

species

A dictionary of the species in the experiment and their properties. Their properties includes index location in the trajectory file, mass of the species as taken from the PubChem database_path, and the charge taken from the same database_path. When using these properties, it is best that users confirm this information, with exception to the indices as they are read from the file and will be correct.

Type:

dict

number_of_atoms

The total number of atoms in the simulation

Type:

int

add_data(simulation_data: Union[str, Path, FileProcessor, list], force: bool = False, update_with_pubchempy: bool = True)

Add data to experiment. This method takes a filename, file path or a file reader (or a list thereof). If given a filename, it will try to instantiate the appropriate file reader with its default arguments. If you have a custom data format with its own reader or want to use non-default arguments for your reader, instantiate the reader and pass it to this method. TODO reference online documentation of data loading in the error messages :param simulation_data: or list thereof

if str or pathlib.Path: path to the file that contains the simulation_data if mdsuite.file_io.file_read.FileProcessor: An already instantiated file reader from mdsuite.file_io if list : must be list of any of the above (can be mixed).

Parameters:

• force (bool) – If true, a file will be read regardless of if it has already been seen. Default: False

• update_with_pubchempy (bool) – Whether or not to look for the masses of the species in pubchempy. Default: True.

cls_transformation_run(transformation: Transformations, *args, **kwargs)

Run the transformation.

The Transformation class is updated with this experiment and afterwards performs the transformation. Preliminary work in accordance to https://github.com/zincware/MDSuite/issues/404

Parameters:

transformation (Transformations) –

load_matrix(property_name: str = None, species: ~typing.Iterable[str] = None, select_slice: <numpy.lib.index_tricks.IndexExpression object at 0x7f811e5ba760> = None, path: ~typing.Iterable[str] = None)

Load a desired property matrix.

Parameters:

• property_name (str) – Name of the matrix to be loaded, e.g. ‘Unwrapped_Positions’, ‘Velocities’

• species (Iterable[str]) – List of species to be loaded

• select_slice (np.slice) – A slice to select from the database_path.

• path (str) – optional path to the database_path.

Returns:

property_matrix – Tensor of the property to be studied. Format depends on kwargs.

Return type:

np.array, tf.Tensor

property run: RunComputation

Method to access the available calculators.

Returns:

class that has all available calculators as properties

Return type:

RunComputation

run_visualization(species: Optional[list] = None, molecules: bool = False, unwrapped: bool = False)

Perform a trajectory visualization.

Parameters:

• species (list) – A list of species of molecules to study.

• molecules (bool) – If true, molecule groups will be used.

• unwrapped (bool) – If true, unwrapped coordinates will be visualized.

Return type:

Displays a visualization app.

set_charge(element: str, charge: float)

Set the charge/s of an element.

Parameters:

• element (str) – Name of the element whose charge you want to change

• charge (list) – New charge/s of the element

set_mass(element: str, mass: float)

Set the mass/es of an element.

Parameters:

• element (str) – Name of the element whose mass you want to change

• mass (list) – New mass/es of the element

static units_to_si(units_system) → Units

Returns a dictionary with equivalences from the unit experiment given by a string to SI. Along with some constants in the unit experiment provided (boltzmann, or other conversions). Instead, the user may provide a dictionary. In that case, the dictionary will be used as the unit experiment.

Parameters:

• experiment (units_system (str) -- current unit) –

• change (dimension (str) -- dimension you would like to) –

Returns:

units – dataclass that contains the conversion factors to SI

Return type:

Units

mdsuite.experiment.experiment.update_species_attributes_with_pubchempy(species_list: List[SpeciesInfo])

Add information to the species dictionary.

A fundamental part of this package is species specific analysis. Therefore, the Pubchempy package is used to add important species specific information to the class. This will include the charge of the ions which will be used in conductivity calculations.