pysoftk.torsional package

Submodules

pysoftk.torsional.mol_conformer module

class pysoftk.torsional.mol_conformer.ConformerGenerator(num_conformers: int = 10, forcefield: str = 'mmff94', make3D_steps: int = 50, convergence: int = 5)

Bases: object

A class to generate and save molecular conformers using Open Babel. Includes methods for genetic algorithm (GA) based conformer generation (modified from the original ‘generate_conformers’), diversity-based conformer generation (confab), and saving conformers to separate files.

confab_generate_conformers(molecule_input: str, output_dir: str, output_format: str = 'xyz', base_filename: str | None = None, forcefield: str | None = None, nconfs: int = 10000, rmsd: float = 0.5, energy_gap: float = 50.0, initial_opt_steps: int = 50, verbose: bool = False) → int

Generates diverse conformers using a method similar to Confab.

Parameters:

• molecule_input – A SMILES string representing the molecule.

• output_dir – The directory to save the generated conformers.

• output_format – The file format for saving (default: ‘xyz’).

• base_filename – The base name for the output files.

• forcefield – The force field to use for initial 3D generation (default: initialized value).

• nconfs – The maximum number of diverse conformers to generate (default: 10000).

• rmsd – The RMSD threshold for considering conformers as distinct (default: 0.5).

• energy_gap – The energy window (in kJ/mol) to consider for diverse conformers (default: 50.0).

• initial_opt_steps – The number of optimization steps for the initial 3D structure (default: 50).

• verbose – A boolean to control the verbosity (default: False).

Returns:

The number of conformers successfully generated and saved.

ga_generate_conformers(input_file: str | None = None, smiles: str | None = None, output_dir: str | None = None, output_format: str = 'xyz', base_filename: str | None = None, num_conformers: int | None = None, forcefield: str | None = None, make3D_steps: int | None = None, mutability: int = 5, convergence: int | None = None, num_children: int | None = None) → int

Generates conformers using Open Babel’s weighted rotor search (GA). Saves conformers to separate files in a specified directory. Returns the number of generated conformers.

save_conformers_to_separate_files(molecule_with_conformers: Molecule, base_name: str, output_dir: str | None = None, file_format: str = 'xyz')

Splits a pybel.Molecule object containing multiple conformers into separate files, one for each conformer.

Parameters:

• molecule_with_conformers – A pybel.Molecule object that contains multiple conformers (e.g., the output from generate_conformers()).

• base_name – The base name to use for the output filenames (e.g., “propanol”).

• output_dir – The directory where the individual conformer files will be saved. If None, a directory named “{base_name}_conformers” will be created in the current working directory (default: None).

• file_format – The file format to use for saving the conformers (default: “xyz”). Common options include “mol”, “pdb”, “xyz”.

class pysoftk.torsional.mol_conformer.Mcon(mol, num_conf)

Bases: object

A class designed to generate and manage molecular conformers for a given RDKit molecule.

This class provides functionality to compute a specified number of 3D conformers (different spatial arrangements) for a molecule, leveraging RDKit’s conformer generation algorithms. The generated conformers, along with their calculated energies, can then be saved to a common chemical file format (SDF).

Example

>>> from rdkit import Chem
>>> from pysoftk.conformer.conformer import Mcon
>>>
>>> # Create an RDKit molecule from a SMILES string
>>> mol = Chem.MolFromSmiles("CCCC")
>>> mol = Chem.AddHs(mol) # Add hydrogens for more realistic conformers
>>>
>>> # Initialize the Mcon class to compute 10 conformers
>>> conformer_generator = Mcon(mol=mol, num_conf=10)
>>>
>>> # Generate and save the conformers to an SDF file
>>> conformer_generator.conformer(output_name="butane_conformers")
Number of conformers created: 10

Note

This class requires the RDKit package to be installed in your Python environment. The quality and diversity of the generated conformers depend on the underlying RDKit algorithms and the complexity of the molecule.

conformer(output_name)

Generates molecular conformers for the initialized molecule using RDKit’s ETKDGv3 algorithm and saves them to an SDF (Structure-Data File) file.

This method orchestrates the conformer generation process, including the calculation of energies for each conformer. It then writes all generated conformers into a single SDF file, making them accessible for further analysis or visualization. By default, it returns all generated conformers, including the highest-energy ones, allowing for a comprehensive conformational analysis.

Parameters:

output_name (str) – The base name for the output SDF file. The file will be saved as <output_name>.sdf in the current working directory.

Returns:

This function doesn’t explicitly return a list of molecules directly. Instead, it writes the conformers to an SDF file. The SDF file contains all generated conformers as separate entries, each representing an rdkit.Chem.Mol object with 3D coordinates. A message indicating the number of created conformers is printed to the console.

Return type:

list of rdkit.Chem.Mol objects

mol

num_conf

pysoftk.torsional.torsional module

class pysoftk.torsional.torsional.Torsional(mol)

Bases: object

A class dedicated to detecting and visualizing torsional angles within molecular structures, particularly useful for understanding the conformational flexibility of linear conjugated polymers.

This class provides tools to: 1. Validate RDKit molecular objects. 2. Convert RDKit molecules into NetworkX graphs for topological analysis. 3. Identify and list atoms involved in rotatable bonds, which contribute to

torsional angles.

4. Handle complex ring systems to accurately identify relevant torsional angles.

5. Visualize the molecule with highlighted torsional angles by generating PNG images.

Examples

>>> from rdkit import Chem
>>> from pysoftk.torsional.torsional import Torsional
>>>
>>> # Create a simple molecule (e.g., a short polymer segment)
>>> mol = Chem.MolFromSmiles("c1ccccc1-c2ccccc2-c3ccccc3") # Biphenyl trimer
>>> mol = Chem.AddHs(mol) # Add hydrogens for correct atom degrees
>>>
>>> # Initialize the Torsional class
>>> torsional_analyzer = Torsional(mol=mol)
>>>
>>> # Get the list of atoms involved in torsional angles
>>> torsional_atoms = torsional_analyzer.seek_angles()
>>> print(f"Identified torsional angles (atom indices): {torsional_atoms}")
>>>
>>> # Plot and save images highlighting these torsional angles
>>> torsional_analyzer.plot_trs_ang(name="biphenyl_trimer_torsions")
3 figures have been printed (example output)

Note

This class requires the RDKit and NetworkX packages to be installed in your Python environment. It is particularly designed for linear-like polymer structures where the concept of “torsional angles” between repeating units or significant backbone bonds is relevant.

draw_molecule(mol, name_pic, atoms_idx)

Generates and saves a PNG image of the RDKit molecule, with specific atoms highlighted and atom numbers displayed.

This function provides a visual representation of the molecule, emphasizing the atoms involved in the detected torsional angles.

Parameters:

• mol (rdkit.Chem.rdchem.Mol) – The RDKit Mol object to be drawn.

• name_pic (str) – The base name for the output PNG file. The file will be saved as <name_pic>.png in the current working directory.

• atoms_idx (List[int] or List[Tuple[int, ...]]) – A list of atom indices to be highlighted in the generated image. This list can contain individual atom indices or tuples of atom indices (e.g., representing the four atoms of a dihedral).

Returns:

This function does not return any value; it generates a PNG file as a side effect.

Return type:

None

list_dhdl_atoms()

Computes and returns the final list of valid torsional angles (defined by four atom indices) by excluding those that are part of ring systems.

This method combines the results from __prbm_cases and __comb_dihedral_atoms to provide the definitive list of rotatable torsional angles in the molecule.

Returns:

List – A sorted list of lists, where each inner list contains four integer atom indices representing a distinct rotatable torsional angle. These angles are typically associated with bonds that can undergo conformational changes.

Return type:

List[List[int]]

mol_graph()

Converts the RDKit molecule into a NetworkX graph representation.

This method facilitates graph-based algorithms for analyzing molecular topology, such as finding paths and atom degrees, which are essential for identifying dihedral angles. Atom and bond properties from RDKit are stored as node and edge attributes in the NetworkX graph.

Returns:

G – A NetworkX graph object where nodes represent atoms (with attributes like atomic number, formal charge, etc.) and edges represent bonds (with attributes like bond type).

Return type:

networkx.Graph

mol_graph_neigh(mol)

Computes the adjacency matrix (with atomic numbers on the diagonal) from an RDKit Mol object and converts it into a NetworkX graph.

This function creates a graph representation where nodes are atoms and edges represent bonds, useful for various graph-based analyses, including those involving connectivity and neighborhoods.

Parameters:

mol (rdkit.Chem.rdchem.Mol) – The RDKit Mol object for which the adjacency matrix and graph are to be computed.

Returns:

G – A NetworkX graph object representing the molecular connectivity. Node attributes include atomic numbers (on the diagonal of the adjacency matrix used to construct the graph).

Return type:

networkx.Graph

plot_trs_ang(name)

Plots and saves PNG images for each detected torsional angle in the molecule, highlighting the atoms involved in each angle.

This method iterates through all identified torsional angles and generates a separate image for each, providing a detailed visualization of the conformational points of interest.

Parameters:

name (str) – The base name for the output PNG files. Each file will be named as <name>_mol_<index>.png, where <index> corresponds to the sequence of the torsional angle.

Returns:

This function does not return any value; it generates multiple PNG files as a side effect. A message indicating the number of generated figures is printed to the console.

Return type:

None

seek_angles()

Identifies and returns a list of atom indices that define the torsional angles within the molecule, specifically focusing on rotatable bonds in a planar or linear polymer context.

This is the primary public method to obtain the identified torsional angles. It orchestrates several internal methods to first identify potential dihedral atoms, then filter out those involved in problematic (e.g., ring) environments, to provide a clean list of relevant torsional angles.

Returns:

List – A list of lists, where each inner list contains four integer atom indices [i, j, k, l] that define a torsional angle. The torsional angle is the angle between the planes defined by atoms (i, j, k) and (j, k, l).

Return type:

List[int]

show_atom_number(mol, label)

Adds atom index labels as a property to each atom in an RDKit molecule, making them visible when drawing the molecule.

This utility function is essential for visualizing the atom indices on the molecular diagram, which is crucial for interpreting the results of torsional angle detection.

Parameters:

• mol (rdkit.Chem.rdchem.Mol) – The RDKit Mol object to which atom index labels will be added.

• label (str) – The name of the atomic property to set for displaying atom numbers (e.g., ‘molAtomMapNumber’ is commonly used by RDKit drawing functions). The value of this property will be the string representation of the atom’s index.

Returns:

mol – The modified RDKit Mol object with the atom map numbers set as an atomic property.

Return type:

rdkit.Chem.rdchem.Mol

validate_mol(mol)

Validates whether the input object is a valid RDKit Mol object.

This internal helper function ensures that subsequent operations are performed on a proper RDKit molecular structure, preventing potential errors.

Parameters:

mol (rdkit.Chem.rdchem.Mol) – The object to be validated as an RDKit Mol object.

Returns:

mol – The validated RDKit Mol object if the input is valid.

Return type:

rdkit.Chem.rdchem.Mol

Raises:

TypeError – If the input mol is not an instance of rdkit.Chem.rdchem.Mol.

Module contents