Topo

Module defining an abstract base class for topology generators and a function to run topology generation.

TopoGen()

Bases: ABC

Abstract base class defining the standardized interface for topology file generators.

This class serves as a blueprint for creating topology generators for various molecular simulation packages. Subclasses of TopoGen are expected to implement the dry_run and run methods, which handle the preliminary information gathering and the actual topology file generation, respectively. This ensures a consistent and extensible framework for managing different topology generation workflows within Simlify.

Subclasses should be designed to handle the specific requirements and file formats of the target simulation package (e.g., Amber, GROMACS).

dry_run(path_structure, simlify_config, **kwargs)

Perform a preliminary dry run to gather necessary information before topology generation.

This abstract class method is intended to be implemented by subclasses. It should perform a lightweight analysis of the input structure file and the Simlify configuration to determine any parameters or information required for the full topology generation process. This step can include tasks like identifying residue types, counting atoms, or checking for specific force field requirements.

PARAMETER	DESCRIPTION
path_structure	The file path to the molecular structure file (e.g., PDB, GRO) for which the topology will be generated. TYPE: str
simlify_config	An instance of the Simlify configuration object, providing access to global and simulation-specific settings. TYPE: SimlifyConfig

RETURNS	DESCRIPTION
dict[str, Any]	A dictionary containing keyword arguments that should be passed to the run method of the same topology generator class. This dictionary can include any information gathered during the dry run that is needed for the actual topology file generation.

RAISES	DESCRIPTION
NotImplementedError	If this abstract method is called directly. Subclasses must provide their own implementation.

run(path_structure, simlify_config, **kwargs)

Generate the topology file based on the provided structure and configuration.

This abstract class method is intended to be implemented by subclasses. It should perform the main task of generating the topology file for the specified simulation package. This typically involves reading the structure file, applying force field parameters, defining bonds, angles, dihedrals, and other interactions, and writing the output topology file in the appropriate format.

PARAMETER	DESCRIPTION
path_structure	The file path to the molecular structure file. TYPE: str
simlify_config	An instance of the Simlify configuration object. TYPE: SimlifyConfig

RETURNS	DESCRIPTION
dict[str, Any]	A dictionary containing information about the generated topology, such as the path to the generated file or any other relevant metadata. The contents of this dictionary will depend on the specific topology generator.

RAISES	DESCRIPTION
NotImplementedError	If this abstract method is called directly. Subclasses must provide their own implementation.

run_gen_topo(path_structure, import_string, simlify_config)

Driver function to instantiate and run a topology generator.

This function takes the path to a structure file, an import string specifying the topology generator class to use, and the Simlify configuration. It dynamically imports the specified topology generator class, performs a dry run to gather preliminary information, and then executes the full topology generation.

PARAMETER	DESCRIPTION
path_structure	The file path to the molecular structure file for which the topology will be generated. TYPE: str
import_string	A string representing the import path to the topology generator class. This string should be in the format that can be used by simlify.utils.get_obj_from_string (e.g., "module.submodule.ClassName"). For example, to use the Amber topology generator, the import string might be "simlify.simulation.amber.topo.AmberTopoGen". TYPE: str
simlify_config	An instance of the Simlify configuration object. TYPE: SimlifyConfig

RETURNS	DESCRIPTION
dict[str, Any]	A dictionary containing information about the generated topology, as returned by the run method of the instantiated topology generator class. This typically includes the path to the generated topology file and other relevant metadata.

RAISES	DESCRIPTION
ImportError	If the import_string does not point to a valid class.
AttributeError	If the imported class does not have the expected dry_run and run methods.
Exception	Any exception raised by the dry_run or run methods of the topology generator class.

Examples:

To generate an Amber topology for the structure file "input.pdb" using the AmberTopoGen class:

>>> from simlify import SimlifyConfig
>>> config = SimlifyConfig()
>>> topo_info = run_gen_topo(
...     path_structure="input.pdb",
...     import_string="simlify.simulation.amber.topo.AmberTopoGen",
...     simlify_config=config,
... )
>>> print(topo_info)
{'topology_file': '/path/to/input.prmtop', 'coordinate_file': '/path/to/input.inpcrd'}