add_molecule

A module containing functions and classes to add a molecule/AtomicSystem to a restart file.

Summary

Classes:

AddMolecule

A class for adding a molecule to a restart file.

Functions:

add_molecule

Add a molecule to a restart file.

Reference

class AddMolecule(
restart_file: str,
molecule_file: str,
output_file: str | None = None,
mode: FileWritingMode | str = 'w',
molecule_file_type: OutputFileFormat | str = OutputFileFormat.AUTO,
restart_moldescriptor_file: str | None = None,
molecule_moldescriptor_file: str | None = None,
number_of_additions: PositiveInt = 1,
max_iterations: PositiveInt = 100,
distance_cutoff: PositiveReal = 1.0,
max_displacement: PositiveReal | Np1DNumberArray = 0.1,
rotation_angle_step: PositiveInt = 10,
md_engine_format: MDEngineFormat | str = MDEngineFormat.PQ,
)[source]

Bases: object

A class for adding a molecule to a restart file.

The class reads a restart file and a molecule file and adds the molecule to the restart file. The molecule is added by fitting t he molecule to the restart file. The fitting is done randomly by rotating the molecule and translating it to a random position. After the fitting, the molecule is added to the restart file. The class can add multiple molecules to the restart file. The class can also add a moldescriptor file to the restart file to keep track of the fitting.

Parameters:

  • restart_file (str) – The filename of the restart file.

  • molecule_file (str) – The filename of the molecule file.

  • output_file (str | None, optional) – The filename of the output file, by default None

  • mode (FileWritingMode | str, optional) – The writing mode, by default “w” The following modes are available: - “w”: write - “a”: append - “o”: overwrite

  • molecule_file_type (OutputFileFormat | str, optional) – The type of the molecule file, by default OutputFileFormat.AUTO. If the type is AUTO, the type will be inferred from the file extension. If the type is RESTART, a moldescriptor file can be specified.

  • restart_moldescriptor_file (str | None, optional) – The filename of the moldescriptor file of the restart file, by default None.

  • molecule_moldescriptor_file (str | None, optional) – The filename of the moldescriptor file of the molecule file, by default None. A moldescriptor file can only be specified for restart file types.

  • number_of_additions (PositiveInt, optional) – The number of times the molecule should be added to the restart file, by default 1

  • max_iterations (PositiveInt, optional) – The maximum number of iterations to try to fit the molecule into the restart file, by default 100

  • distance_cutoff (PositiveReal, optional) – The distance cutoff for the fitting, by default 1.0

  • max_displacement (PositiveReal | Np1DNumberArray, optional) – The maximum displacement for the fitting, by default 0.1

  • rotation_angle_step (PositiveInt, optional) – The angle step for the fitting, by default 10

  • md_engine_format (MDEngineFormat | str, optional) – The format of the restart file, by default MDEngineFormat.PQ

Raises:

  • PQValueError – If the molecule file type is not RESTART and a moldescriptor file is specified.

  • PQValueError – If the molecule file type is not RESTART or XYZ.

add_molecules() → list[AtomicSystem][source]

Calculates all newly fitted atomic systems

Returns:

The fitted atomic systems.

Return type:

List[AtomicSystem]

extend_topology_file(
original_shake_file: str,
extension_shake_file: str,
output: str | None = None,
) → None[source]

Extend the topology file with the shake bonds of the extension topology file.

Parameters:

  • original_shake_file (str) – The filename of the original topology file.

  • extension_shake_file (str) – The filename of the extension topology file.

  • output (str | None, optional) – The filename of the output topology file, by default None (stdout).

Raises:

PQValueError – If the restart system or the molecule is not read before extending the topology file.

write_restart_file() → None[source]

Write the restart file with the added molecule.

logger = <CustomLogger PQAnalysis.AddMolecule (INFO)>
add_molecule(
restart_file: str,
molecule_file: str,
output_file: str | None = None,
mode: FileWritingMode | str = 'w',
molecule_file_type: OutputFileFormat | str = OutputFileFormat.AUTO,
restart_moldescriptor_file: str | None = None,
molecule_moldescriptor_file: str | None = None,
number_of_additions: PositiveInt = 1,
max_iterations: PositiveInt = 100,
distance_cutoff: PositiveReal = 1.0,
max_displacement: PositiveReal | Np1DNumberArray = 0.1,
rotation_angle_step: PositiveInt = 10,
md_engine_format: MDEngineFormat | str = MDEngineFormat.PQ,
topology_file: str | None = None,
topology_file_to_add: str | None = None,
topology_file_output: str | None = None,
) → None[source]

Add a molecule to a restart file.

The function reads a restart file and a molecule file and adds the molecule to the restart file. The molecule is added by fitting the molecule to the restart file. The fitting is done randomly by rotating the molecule and translating it to a random position. After the fitting, the molecule is added to the restart file. The function can add multiple molecules to the restart file. The function can also add a moldescriptor file to the restart file to keep track of the fitting.

Parameters:

  • restart_file (str) – The filename of the restart file.

  • molecule_file (str) – The filename of the molecule file.

  • output_file (str | None, optional) – The filename of the output file, by default None

  • mode (FileWritingMode | str, optional) – The writing mode, by default “w” The following modes are available: - “w”: write - “a”: append - “o”: overwrite

  • molecule_file_type (OutputFileFormat | str, optional) – The type of the molecule file, by default OutputFileFormat.AUTO. If the type is AUTO, the type will be inferred from the file extension. If the type is RESTART, a moldescriptor file can be specified.

  • restart_moldescriptor_file (str | None, optional) – The filename of the moldescriptor file of the restart file, by default None.

  • molecule_moldescriptor_file (str | None, optional) – The filename of the moldescriptor file of the molecule file, by default None. A moldescriptor file can only be specified for restart file types.

  • number_of_additions (PositiveInt, optional) – The number of times the molecule should be added to the restart file, by default 1

  • max_iterations (PositiveInt, optional) – The maximum number of iterations to try to fit the molecule into the restart file, by default 100

  • distance_cutoff (PositiveReal, optional) – The distance cutoff for the fitting, by default 1.0

  • max_displacement (PositiveReal | Np1DNumberArray, optional) – The maximum displacement for the fitting, by default 0.1

  • rotation_angle_step (PositiveInt, optional) – The angle step for the fitting, by default 10

  • md_engine_format (MDEngineFormat | str, optional) – The format of the restart file, by default MDEngineFormat.PQ

  • topology_file (str | None, optional) – The filename of the topology file, by default None

  • topology_file_to_add (str | None, optional) – The filename of the topology file to add, by default None

  • topology_file_output (str | None, optional) – The filename of the output topology file, by default None

Raises:

PQValueError – If the molecule file type is not RESTART and a moldescriptor file is specified.