pysoftk.topologies package

Submodules

pysoftk.topologies.branched module

class pysoftk.topologies.branched.Bd(core, arm, atom)

Bases: object

A class designed for the automated construction of branched polymers from user-defined molecular building blocks (a core and arm molecules).

This class provides functionalities to attach multiple ‘arm’ molecules to a ‘core’ molecule, forming a branched structure. It handles the bonding using a placeholder atom strategy and includes options for 3D embedding and force field optimization of the final branched polymer.

Examples

>>> from rdkit import Chem
>>> from pysoftk.branched_polymers.branched_polymer import Bd
>>> # Define a core molecule with placeholder atoms (e.g., [Au])
>>> core_smiles = "C([Au])C([Au])C"
>>> core_mol = Chem.MolFromSmiles(core_smiles)
>>> # Define an arm molecule with a placeholder atom
>>> arm_smiles = "CC([Au])"
>>> arm_mol = Chem.MolFromSmiles(arm_smiles)
>>> # Initialize the Bd class
>>> branched_poly_builder = Bd(core=core_mol, arm=arm_mol, atom="Au")
>>> # Build the branched polymer
>>> polymer_mol = branched_poly_builder.branched_polymer(force_field="MMFF", relax_iterations=200)
>>> print(f"Branched polymer atoms: {polymer_mol.GetNumAtoms()}")
>>> print(f"Branched polymer bonds: {polymer_mol.GetNumBonds()}")

Note

The RDKit package must be installed in your Python environment for this class to function. Ensure that the placeholder atom specified (e.g., “Au”) is consistent across your core and arm molecules and is a valid RDKit atom.

arm

atom

branched_polymer(relax_iterations=100, force_field='MMFF', swap_H=True)

Constructs a complete branched polymer by iteratively attaching arm molecules to the core molecule, followed by 3D structure optimization.

This is the main function for generating the final branched polymer. It first merges the initial arm to the core. Then, it repeatedly attaches additional arms to any remaining placeholder atoms on the growing structure. Finally, it performs a geometry optimization using the specified force field, with an option to replace the placeholder atoms with hydrogen atoms.

Parameters:

• relax_iterations (int, optional) – The maximum number of iterations to use for the force field relaxation process. A higher number generally leads to more thorough minimization but increases computation time. Defaults to 100.

• force_field (str, optional) – The name of the force field to employ for geometry optimization. Currently supported options are “MMFF” (which defaults to MMFF94) and “UFF”. Defaults to “MMFF”.

• swap_H (bool, optional) –

  A flag indicating whether the placeholder atoms remaining in the final branched polymer structure should be replaced with hydrogen atoms. * If True (default), placeholder atoms will be substituted by hydrogens,

  and the molecule will be optimized.

  • If False, the placeholder atoms will remain in the structure, and the molecule will be optimized without this substitution.

Returns:

newMol_H – An RDKit Mol object representing the fully constructed and geometry-optimized branched polymer. The structure will have either hydrogen atoms or the original placeholder atoms at the terminal points, depending on the swap_H parameter.

Return type:

rdkit.Chem.rdchem.Mol

core

merge_arms(core, arm, atom)

Attaches a single arm molecule to a core molecule by identifying and forming a bond between their respective placeholder atoms, then removing these placeholders.

This function performs the fundamental operation of merging a branch onto the growing polymer structure. It combines the molecules, embeds them in 3D space, identifies the placeholder atoms, creates a new bond between their connected atoms, and finally removes the placeholder atoms.

Parameters:

• core (rdkit.Chem.rdchem.Mol) – The RDKit Mol object representing the current core structure (which could be the initial core or a partially built branched polymer) to which an arm molecule will be attached. It must contain at least one placeholder atom.

• arm (rdkit.Chem.rdchem.Mol) – The RDKit Mol object representing the arm molecule to be attached. It must contain a placeholder atom.

• atom (str) – The atomic symbol of the placeholder atom used in both the core and arm molecules that will be involved in the bonding.

Returns:

mol – A new RDKit Mol object representing the combined structure after the arm molecule has been successfully attached to the core, with the placeholder atoms removed and a new bond formed.

Return type:

rdkit.Chem.rdchem.Mol

pysoftk.topologies.dend module

class pysoftk.topologies.dend.CustomMonomer(id: int, generation: int, smiles: str, parent_attachment_map_num: int | None, child_attachment_map_nums: List[int])

Bases: Monomer

A specialized Monomer for dendrimer branching units.

This class distinguishes between a single parent attachment point and multiple child attachment points, which is essential for building the directed graph of a dendrimer.

class pysoftk.topologies.dend.DendrimerBuilder(core_data: dict, branch_data: dict, generations: int, surface_data: dict | None = None)

Bases: object

A class to construct, optimize, and manage dendrimer molecules.

This class orchestrates the entire workflow, from processing monomer definitions to building the connectivity graph, constructing the 2D molecule, and finally optimizing the 3D structure using external libraries (pysoftk/Open Babel).

build(force_field: str = 'UFF', steps: int = 1000, ff_thr: float = 0.1)

Orchestrates the full dendrimer construction and optimization process.

This is the main method to run the workflow. It calls internal methods to generate the graph, build the 2D molecule, and run the 3D optimization.

Parameters:

• force_field (str, optional) – The Open Babel force field to use for optimization (e.g., “UFF”, “MMFF94”). Defaults to “UFF”.

• steps (int, optional) – The maximum number of optimization steps. Defaults to 1000.

• ff_thr (float, optional) – The energy convergence threshold for the force field optimization. Defaults to 0.1.

get_optimized_mol() → Molecule | None

Returns the final, optimized molecule as a Pybel object.

Returns:

The 3D optimized Pybel molecule,

or None if the build process failed.

Return type:

Optional[pb.Molecule]

plot_topology(output_filename: str = 'dendrimer_topology.png')

Plots the abstract topological graph of the dendrimer using NetworkX.

This visualization shows the monomer connectivity and generation, not the chemical structure.

Parameters:

output_filename (str, optional) – The file path to save the plot image. Defaults to “dendrimer_topology.png”.

class pysoftk.topologies.dend.Monomer(id: int, generation: int, smiles: str, attachment_map_numbers: List[int])

Bases: object

Base class for a monomer unit.

Represents a single molecular building block, holding its RDKit molecule object and information about its connection points.

class pysoftk.topologies.dend.SurfaceMonomer(id: int, generation: int, smiles: str, parent_attachment_map_num: int)

Bases: Monomer

A specialized Monomer for terminal surface (capping) groups.

This monomer only has a single parent connection and no child connections, effectively terminating a branch.

pysoftk.topologies.diblock module

class pysoftk.topologies.diblock.Db(ma, mb, atom)

Bases: object

A class specifically designed for the computational construction of diblock copolymers from two distinct RDKit molecular monomers (Block A and Block B).

This class provides a streamlined workflow to: 1. Generate individual polymer blocks (Block A and Block B) of specified lengths. 2. Concatenate these two blocks to form a single diblock copolymer structure. 3. Perform subsequent 3D embedding and force field optimization to obtain a stable

and chemically sensible molecular geometry.

Examples

>>> from rdkit import Chem
>>> from pysoftk.linear_polymer.linear_polymer import Lp
>>> from pysoftk.block_copolymers.diblock import Db
>>> # Define monomer A and monomer B with placeholder atoms (e.g., [Pt])
>>> monomer_A = Chem.MolFromSmiles("C([Pt])C")
>>> monomer_B = Chem.MolFromSmiles("CC([Pt])C")
>>>
>>> # Initialize the Db class with the two monomers and the placeholder atom
>>> diblock_builder = Db(ma=monomer_A, mb=monomer_B, atom="Pt")
>>>
>>> # Create a diblock copolymer with 5 units of Block A and 3 units of Block B
>>> final_diblock_mol = diblock_builder.diblock_copolymer(
...     len_block_A=5, len_block_B=3, force_field="MMFF"
... )
>>> print(f"Diblock copolymer atoms: {final_diblock_mol.GetNumAtoms()}")

Note

The RDKit package must be installed in your Python environment for this class to function correctly. Ensure that the placeholder atom specified (e.g., “Pt”) is consistently used in both monomer A and monomer B. This class relies on functionalities from pysoftk.linear_polymer and pysoftk.tools.

atom

diblock_copolymer(len_block_A, len_block_B, force_field='MMFF', relax_iterations=100, rot_steps=1)

Constructs a complete diblock copolymer by first synthesizing Block A and Block B independently to specified lengths, and then covalently linking them. The final copolymer undergoes 3D embedding and force field optimization to generate a stable conformation.

This function orchestrates the entire diblock copolymer synthesis process, from individual block formation to the final optimized structure.

Parameters:

• len_block_A (int) – The desired number of monomer A units that will comprise the first block (Block A) of the diblock copolymer.

• len_block_B (int) – The desired number of monomer B units that will comprise the second block (Block B) of the diblock copolymer.

• force_field (str, optional) – The name of the force field to apply during the geometry optimization steps for both individual blocks and the final diblock copolymer. Common choices include “MMFF” (which defaults to MMFF94) or “UFF”. Defaults to “MMFF”.

• relax_iterations (int, optional) – The maximum number of iterations for the force field relaxation algorithm. A higher value generally leads to better energy minimization but increases computation time. This value is applied to the optimization of both blocks and the final copolymer. Defaults to 100.

• rot_steps (int, optional) – The number of rotational steps to perform during conformational searching. This helps in exploring different low-energy conformers of the polymer. Defaults to 1.

Returns:

diblock – An OpenBabel Pybel Molecule object representing the fully constructed and geometry-optimized diblock copolymer. This object contains the 3D coordinates and bonding information of the final polymer.

Return type:

openbabel.pybel.Molecule

ma

mb

class pysoftk.topologies.diblock.Pt(pattern, mols, atom)

Bases: object

A versatile class for creating patterned polymers based on a user-defined sequence of RDKit molecular building blocks.

This class enables the construction of complex copolymers by allowing a specific sequence (pattern) of different monomers to be arranged into a linear chain. It supports 3D embedding and force field optimization of the resulting polymer.

Examples

>>> from rdkit import Chem
>>> from pysoftk.block_copolymers.diblock import Pt
>>> # Define two distinct monomers (e.g., A and B) with a placeholder atom
>>> monomer_A = Chem.MolFromSmiles("C([Pt])C")
>>> monomer_B = Chem.MolFromSmiles("N([Pt])N")
>>>
>>> # Define a repeating pattern
>>> pattern = "ABABAB"
>>> # List of molecules corresponding to the pattern's unique characters
>>> molecules = [monomer_A, monomer_B]
>>>
>>> # Initialize the Pt class
>>> patterned_poly_builder = Pt(pattern=pattern, mols=molecules, atom="Pt")
>>>
>>> # Build the patterned polymer
>>> final_patterned_mol = patterned_poly_builder.pattern_block_poly(
...     relax_iterations=200, force_field="UFF", swap_H=True
... )
>>> print(f"Patterned polymer atoms: {final_patterned_mol.GetNumAtoms()}")

Note

The RDKit package must be installed in your Python environment. The pattern string should consist of characters that correspond to the order of molecules in the mols list (e.g., ‘A’ maps to mols[0], ‘B’ maps to mols[1], etc.). Ensure consistency in the atom placeholder.

atom

mols

pattern

pattern_block_poly(relax_iterations=100, force_field='MMFF', swap_H=True, rot_steps=1, more_iter=10)

Constructs a linear polymer according to a defined alphabetical pattern of molecular building blocks, followed by geometry optimization.

This function assembles the polymer by sequentially combining the specified monomers based on the input pattern string. It handles the creation of bonds between units, and then performs comprehensive 3D structure optimization using a force field, with options for replacing placeholder atoms and further refinement.

Parameters:

• relax_iterations (int, optional) – The maximum number of iterations for the force field relaxation procedure. A higher number typically leads to better convergence of the molecular geometry. Defaults to 100.

• force_field (str, optional) – The name of the force field to be used for molecular mechanics optimization. Supported options generally include “MMFF” (which maps to MMFF94) or “UFF”. Defaults to “MMFF”.

• swap_H (bool, optional) –

  A flag indicating whether the placeholder atoms (specified by self.atom) at the termini of the constructed polymer should be replaced with hydrogen atoms. * If True (default), placeholder atoms are converted to hydrogens

  before the final optimization.

  • If False, the placeholder atoms remain in the structure.

• rot_steps (int, optional) – The number of rotational steps to explore during conformational optimization. This parameter helps in finding different low-energy arrangements of the polymer chain by rotating around rotatable bonds. Defaults to 1.

• more_iter (int, optional) – A multiplier for additional optimization iterations. The relax_iterations value will be multiplied by this number to perform a more extensive final geometry optimization, potentially leading to a more stable conformation. Defaults to 10.

Returns:

mol – A PySoftK molecular object (which wraps an OpenBabel Pybel Molecule) representing the fully constructed and geometry-optimized patterned polymer. This object contains the 3D coordinates and bonding information of the final structure.

Return type:

openbabel.pybel.Molecule

pysoftk.topologies.ranpol module

Optimized Polymer Builder Module.

This module provides the Rnp class for the computational synthesis of ultra-large random copolymers. It utilizes a highly efficient binary tree assembly algorithm for topology construction and integrates OpenBabel for realistic 3D spatial geometry optimization.

class pysoftk.topologies.ranpol.Rnp(ma: Mol, mb: Mol, atom: str)

Bases: object

Optimized Polymer Builder for Ultra-Large Molecules.

This class constructs A-B and A-B-C random copolymers. It prevents the typical O(N^2) scaling bottlenecks of linear polymer growth by using a binary tree assembly approach. It also delegates 3D coordinate generation to OpenBabel for physically realistic spatial accommodation.

ma

RDKit Mol object representing monomer A.

Type:

rdkit.Chem.rdchem.Mol

mb

RDKit Mol object representing monomer B.

Type:

rdkit.Chem.rdchem.Mol

atom

The placeholder atomic symbol (e.g., ‘Br’, ‘At’) used as the connection point between monomers.

Type:

str

atom

ma

mb

random_ab_copolymer(len_polymer: int, pA: float, relax_iterations: int = 100, force_field: str = 'MMFF94', swap_H: bool = True, rot_steps: int = 125, ff_thr: float = 1e-06) → Mol

Constructs a randomly sequenced two-component (A-B) copolymer.

Parameters:

• len_polymer (int) – The total number of monomer units in the desired polymer chain.

• pA (float) – The probability (0.0 to 1.0) of selecting monomer A at any position.

• relax_iterations (int, optional) – Number of iterations for geometry relaxation. Defaults to 100.

• force_field (str, optional) – The force field for 3D optimization. Defaults to ‘MMFF94’.

• swap_H (bool, optional) – If True, caps terminal placeholders with Hydrogen. Defaults to True.

• rot_steps (int, optional) – Thoroughness of the OpenBabel rotor search. Defaults to 125.

• ff_thr (float, optional) – Convergence threshold for optimization. Defaults to 1.0e-6.

Returns:

The synthesized and 3D-optimized A-B copolymer.

Return type:

rdkit.Chem.rdchem.Mol

random_abc_copolymer(mc: Mol, len_polymer: int, pA: float, pB: float, relax_iterations: int = 100, force_field: str = 'MMFF94', swap_H: bool = True, rot_steps: int = 125, ff_thr: float = 1e-06) → Mol

Constructs a randomly sequenced three-component (A-B-C) terpolymer.

Parameters:

• mc (rdkit.Chem.rdchem.Mol) – RDKit Mol object representing the third monomer, C.

• len_polymer (int) – The total number of monomer units in the desired polymer chain.

• pA (float) – The probability (0.0 to 1.0) of selecting monomer A.

• pB (float) – The probability (0.0 to 1.0) of selecting monomer B. (Note: Probability of C is calculated as 1.0 - pA - pB).

• relax_iterations (int, optional) – Number of iterations for geometry relaxation. Defaults to 100.

• force_field (str, optional) – The force field for 3D optimization. Defaults to ‘MMFF94’.

• swap_H (bool, optional) – If True, caps terminal placeholders with Hydrogen. Defaults to True.

• rot_steps (int, optional) – Thoroughness of the OpenBabel rotor search. Defaults to 125.

• ff_thr (float, optional) – Convergence threshold for optimization. Defaults to 1.0e-6.

Returns:

The synthesized and 3D-optimized A-B-C terpolymer.

Return type:

rdkit.Chem.rdchem.Mol

pysoftk.topologies.ring module

class pysoftk.topologies.ring.Rn(mol, atom)

Bases: object

A class dedicated to the computational synthesis of circular (ring-shaped) polymers from a given RDKit monomer molecule.

This class provides a robust method to: 1. Construct a linear polymer chain of a specified length from a monomer. 2. Identify the terminal placeholder atoms of this linear chain. 3. Form a new bond between these terminal atoms to cyclize the polymer,

thereby creating a ring structure.

4. Perform subsequent 3D embedding and force field optimization to obtain a stable and chemically sensible cyclic molecular geometry.

Examples

>>> from rdkit import Chem
>>> from pysoftk.topologies.ring import Rn
>>> # Define a monomer with placeholder atoms (e.g., [Pt])
>>> monomer_smiles = "C([Pt])C([Pt])"
>>> monomer = Chem.MolFromSmiles(monomer_smiles)
>>>
>>> # Initialize the Rn class with the monomer and the placeholder atom
>>> ring_builder = Rn(mol=monomer, atom="Pt")
>>>
>>> # Create a ring polymer with 5 monomer units
>>> final_ring_mol = ring_builder.pol_ring(len_polymer=5, force_field="MMFF", relax_iterations=200)
>>> print(f"Ring polymer atoms: {final_ring_mol.GetNumAtoms()}")
>>> print(f"Ring polymer bonds: {final_ring_mol.GetNumBonds()}")

Note

The RDKit package must be installed in your Python environment for this class to function correctly. Ensure that the placeholder atom specified (e.g., “Pt”) is present at both ends of the monomer unit to allow for linear chain formation and subsequent cyclization. This class relies on functionalities from pysoftk.linear_polymer and pysoftk.tools.

atom

mol

pol_ring(len_polymer=2, force_field='MMFF', relax_iterations=100, shift=1.25, more_iter=10)

Constructs a circular (ring-shaped) polymer from the specified monomer by first creating a linear chain and then closing it into a ring. The resulting cyclic polymer undergoes comprehensive 3D embedding and force field optimization to achieve a stable conformation.

This function orchestrates the entire ring polymer synthesis process, from linear chain formation to the final optimized cyclic structure.

Parameters:

• len_polymer (int, optional) – The number of monomer units that will comprise the linear chain before cyclization. This directly determines the size of the resulting ring polymer. Defaults to 2.

• force_field (str, optional) – The name of the force field to apply during the geometry optimization steps. Valid options are “MMFF” (which defaults to MMFF94) or “UFF”. Defaults to “MMFF”.

• relax_iterations (int, optional) – The maximum number of iterations for the force field relaxation algorithm during the initial linear polymer formation and the final ring optimization. A higher value generally leads to better energy minimization. Defaults to 100.

• shift (float, optional) – The X-axis translation distance (in Ångstroms) applied to each subsequent monomer copy during the initial linear polymer formation. This value influences the initial spacing between monomer units. Defaults to 1.25.

• more_iter (int, optional) – A multiplier for additional optimization iterations during the final force field relaxation of the ring polymer. The relax_iterations value will be multiplied by this number to perform a more extensive final geometry optimization, potentially leading to a more stable conformation. Defaults to 10.

Returns:

pol_ring – An OpenBabel Pybel Molecule object representing the fully constructed and geometry-optimized circular (ring) polymer. This object contains the 3D coordinates and bonding information of the final cyclic structure.

Return type:

openbabel.pybel.Molecule

Raises:

ValueError – If an invalid force_field is provided (i.e., not “MMFF” or “UFF”).

pysoftk.topologies.ring.apply_force_field(molecule: Mol, force_field: str, relax_iterations: int) → None

Applies the specified force field (MMFF or UFF) to an RDKit molecule to perform geometry relaxation.

This helper function is used internally to minimize the energy of a molecular conformation.

Parameters:

• molecule (rdkit.Chem.Mol) – The RDKit Mol object whose geometry needs to be optimized.

• force_field (str) – The name of the force field to apply (“MMFF” or “UFF”).

• relax_iterations (int) – The maximum number of iterations for the force field minimization algorithm.

Returns:

This function modifies the input molecule in place by updating its conformer with the optimized coordinates.

Return type:

None

pysoftk.topologies.ring.check_proto(mol, force_field='MMFF', relax_iterations=100, rot_steps=1, ff_thr=1e-06)

Performs a final, comprehensive geometry optimization and conformational search on a proto-polymer or any RDKit molecule using OpenBabel’s force field capabilities.

This function is crucial for refining the 3D structure of the generated polymer, ensuring it reaches a stable, low-energy conformation. It converts the RDKit molecule to an OpenBabel object, applies the chosen force field, and can perform a global optimization to explore multiple conformers.

Parameters:

• mol (rdkit.Chem.rdchem.Mol) – The RDKit Mol object representing the proto-polymer or molecule to be optimized.

• force_field (str, optional) – The name of the force field to use for relaxation. Accepted values are “MMFF” (which maps to MMFF94 in OpenBabel) or “UFF”. Defaults to “MMFF”.

• relax_iterations (int, optional) – The maximum number of iterations for the force field relaxation algorithm. Defaults to 100.

• rot_steps (int, optional) – The number of rotational steps to explore during global optimization to find different low-energy conformers. Defaults to 1.

• ff_thr (float, optional) – The force field convergence threshold. The optimization will stop when the forces on atoms fall below this value. Defaults to 1.0e-6.

Returns:

newMol_H – An OpenBabel Pybel Molecule object representing the geometry-optimized molecule.

Return type:

openbabel.pybel.Molecule

Module contents