Package API
This package contains classes and functions to discover possible stereomers and generate 3D atomic coordinates for mononuclear octahedral and square-planar metal complexes.
Concept
The mace.Complex class contains all required functionality for stereomer
search and 3D embedding. The corresponding object can be initialized using the
mace.Complex constructor, or mace.ComplexFromMol(), mace.ComplexFromLigands(),
and mace.ComplexFromXYZFile() functions.
An initialized complex object may not have defined stereochemestry of the central atom (non-empty
mace.Complex.err_init). In this case, the mace.Complex.GetStereomers() method
should be used to get possible stereomers. 3D atomic coordinates can be generated using
mace.Complex.AddConformer() and mace.Complex.AddConformers() methods.
For other features of the MACE package see the tutorial.
Classes & Functions
- class mace.Complex(smiles, geom, maxResonanceStructures=1)
The Complex class, describing mononuclear square-planar and octahedral metal complexes. Complex objects contain Chem.Mol objects to describe a molecular connectivity, as well as additional symmetric and geometric data required for stereomer generation and 3D embedding.
- Parameters
smiles (str) – RDKit/ChemAxon SMILES of the complex;
geom (str) – molecular geometry, “OH” for octahedral and “SP” for square-planar;
maxResonanceStructures (int) – maximal number of resonance structures to consider during generation of Complex._ID and Complex._eID attributes.
- smiles_init
SMILES string used for Complex initialization;
- Type
str
- geom
molecular geometry used for Complex initialization;
- Type
str
- maxResonanceStructures
number of resonance structures used for Complex initialization;
- Type
int
- err_init
message error corresponding for the incorrect values of DAs’ atomic map numbers. If not None, the complex can not be used for 3D embedding, and stereomer search is required;
- Type
Optional[str]
- mol
RDKit Molecule describing complex without hydrogens. It is used for chemoinformatical operations (substructure search, generation of unique SMILES);
- Type
Type[Chem.Mol]
- mol3D
RDKit Molecule describing complex with hydrogens. It is used for the generation of XYZ-files;
- Type
Type[Chem.Mol]
- mol3Dx
RDKit Molecule describing complex with hydrogens and dummies describing missing donor atoms. It is used for the MM computations and is available after the first embedding attempt.
- Type
Type[Chem.Mol]
- IsEqual(X)
Compares two complexes are identical
- Parameters
X (Type[Complex]) – complex which is used for pairwise comparison
- Returns
True if complexes are identical, False otherwise
- Return type
bool
- IsEnantiomeric()
Checks if the complex is chiral
- Returns
True if complex is chiral, False otherwise
- Return type
bool
- IsEnantiomer(X)
Checks if two complexes are enantiomers
- Parameters
X (Type[Complex]) – complex which is used for pairwise comparison
- Returns
True if complexes are enantiomers, False otherwise
- Return type
bool
- GetStereomers(regime='all', dropEnantiomers=True, minTransCycle=None, merRule=True)
Generates stereomers of the complex saving stereochemistry of defined stereocenters of ligands
- Parameters
regime (str) –
which stereocenters are considered:
”CA”: changes stereochemistry of center atom only;
”ligands”: changes stereochemistry of undefined stereocenters in ligands only;
”all”: changes both stereochemistry of CA and ligands;
dropEnantiomers (bool) – if True, leaves only one enantiomer out of two in the output;
minTransCycle (Optional[int]) – minimal size of the chelate cycle required to form trans DA-CA-DA fragment. If None, trans- DA-CA-DA arrangements is banned;
merRule (bool) – if True, applies the empiric rule restricting rigid X-Y-Z fragments (for which fac- geometry is “impossible”)
- Returns
list of found stereomers prepared for 3D embedding
- Return type
List[Type[Complex]]
- Optimize(confId=0, maxIts=1000)
Optimizes geometry of the given conformer
- Parameters
confId (int) – index of the conformer;
maxIts (int) – maximal number of optimization steps
- Returns
0 if the minimization succeeded
- Return type
int
- AddConformer(clearConfs=True, useRandomCoords=True, maxAttempts=10)
Generates a new conformer
- Parameters
clearConfs (bool) – if True, removes earlier generated conformers;
useRandomCoords (bool) – use random coordinated during embedding (using False is not recommended);
maxAttempts (int) – maximal number of attempts to generate a conformer
- Returns
index of generated conformer, and -1 if generation fails
- Return type
int
- AddConstrainedConformer(core, confId=0, clearConfs=True, useRandomCoords=True, maxAttempts=10, engine='coordMap', deltaR=0.01)
Generates a new conformer where part of the complex is constrained to have particular coordinates
- Parameters
core (Type[Complex]) – complex which is a substructure of the initial one. It should have at least one conformer
confId (int) – index of the core complex’s conformer, its geometry will be used for constraining geometry of the main complex
clearConfs (bool) – if True, removes earlier generated conformers;
useRandomCoords (bool) – use random coordinated during embedding (using False is not recommended);
maxAttempts (int) – maximal number of attempts to generate a conformer;
engine (str) – an algorithm usef to build a constraint: - “coordMap”: preferable choice, uses additional MM constraints; - “boundsMatrix”: pure BoundsMatrix modification
deltaR (float) – distances in boundsMatrix are set as d_core +/- deltaR
- Returns
index of generated conformer, and -1 if generation fails
- Return type
int
- GetNumConformers()
Returns number of conformers
- Returns
number of conformers
- Return type
int
- RemoveConformer(confId)
Removes conformer with the given index
- Parameters
confId (int) – index of the conformer
- RemoveAllConformers()
Removes all conformers
- GetConfEnergy(confId)
Returns MM energy of the conformer
- Parameters
confId (int) – index of the conformer;
- Returns
MM energy of the conformer
- Return type
float
- GetMinEnergyConfId(i)
Returns index of the conformer with the i-th smallest energy
- Parameters
i (int) – conformer number when ordering them by energy in ascending order
- Returns
index of the conformer
- Return type
int
- OrderConfsByEnergy()
Orders conformers by their MM energy
- GetRepresentativeConfs(numConfs=5, dE=25.0, dropCloseEnergy=True)
Returns IDs of approximately most distant conformers (greedy approach)
- Parameters
numConfs (int) – maximal number of conformers to select;
dE (float) – maximal allowed relative energy of conformer;
dropCloseEnergy (bool) – drops conformers with close energy (delta-E < 0.1).
- Returns
list of conformers’ IDs
- Return type
List[int]
- AddConformers(numConfs=10, clearConfs=True, useRandomCoords=True, maxAttempts=10, rmsThresh=-1)
Generates several new conformers
- Parameters
numConfs (int) – if True, removes earlier generated conformers;
clearConfs (bool) – if True, removes earlier generated conformers;
useRandomCoords (bool) – use random coordinated during embedding (using False is not recommended);
maxAttempts (int) – maximal number of attempts to generate a conformer;
rmsThresh (float) – if RMSD between two conformers is lower than this value, one of two conformers is dropped from output. If -1, no RMDS filtration is applied.
- Returns
list of indexes of generated conformer, empty list if generation fails
- Return type
int
- AddConstrainedConformers(core, confId=0, numConfs=10, clearConfs=True, useRandomCoords=True, maxAttempts=10, engine='coordMap', deltaR=0.01, rmsThresh=-1)
Generates several new conformers where part of the complex is constrained to have particular coordinates
- Parameters
core (Type[Complex]) – complex which is a substructure of the initial one. It should have at least one conformer
confId (int) – index of the core complex’s conformer, its geometry will be used for constraining geometry of the main complex
numConfs (int) – if True, removes earlier generated conformers;
clearConfs (bool) – if True, removes earlier generated conformers;
useRandomCoords (bool) – use random coordinated during embedding (using False is not recommended);
maxAttempts (int) – maximal number of attempts to generate a conformer;
engine (str) – an algorithm usef to build a constraint: - “coordMap”: preferable choice, uses additional MM constraints; - “boundsMatrix”: pure BoundsMatrix modification
deltaR (float) – distances in boundsMatrix are set as d_core +/- deltaR
rmsThresh (float) – if RMSD between two conformers is lower than this value, one of two conformers is dropped from output. If -1, no RMDS filtration is applied.
- Returns
list of indexes of generated conformer, empty list if generation fails
- Return type
int
- GetBondedLigand(num)
Extracts ligand with the same geometry as in the original complex
- Parameters
num (int) – atomic map number corresponding to the desired ligand’s DA
- Returns
extracted ligand
- Return type
Type[Chem.Mol]
- ToXYZBlock(confId=None)
Generates text block of XYZ file
- Parameters
confId (Optional[int]) – conformer Id; if None, 0-th conformer is saved
- Returns
text block of the XYZ file
- Return type
str
- ToMultipleXYZBlock(confIds=None)
Generates text block of multiple XYZ file
- Parameters
confIds (Optional[List[int]]) – ordered list of conformer Ids to include in XYZ-block. If None, all conformers are saved
- Returns
text block of the multiple XYZ file
- Return type
str
- ToXYZ(path, confId=None)
Saves complex as XYZ file
- Parameters
path (str) – file path;
confIds (Optional[int]) – conformer Id; if None, 0-th conformer is saved
- ToMultipleXYZ(path, confIds=None)
Saves complex as multiple XYZ file
- Parameters
path (str) – file path;
confIds (Optional[List[int]]) – ordered list of conformer Ids to include in XYZ-block. If None, all conformers are saved
- mace.ComplexFromMol(mol, geom, maxResonanceStructures=1)
Generates Complex from RDKit Mol object
- Parameters
mol (Type[Chem.Mol]) – molecule corresponding to the mononuclear octahedral/square-planar metal complex;
geom (str) – molecular geometry, “OH” for octahedral and “SP” for square-planar;
maxResonanceStructures (int) – maximal number of resonance structures to consider during generation of Complex._ID and Complex._eID attributes.
- Returns
complex object
- Return type
Type[Complex]
- mace.ComplexFromLigands(ligands, CA, geom, maxResonanceStructures=1)
Generates complex from the ligands and the central atom
- Parameters
ligands (List[str]) – the list of ligands’ SMILES, donor atoms must have non-zero atomic map numbers;
CA (str) – SMILES of the central atom;
geom (str) – molecular geometry, “OH” for octahedral and “SP” for square-planar;
maxResonanceStructures (int) – maximal number of resonance structures to consider during generation of Complex._ID and Complex._eID attributes.
- Returns
complex object
- Return type
Type[Complex]
- mace.ComplexFromXYZFile(path)
Reads MACE-generated XYZ-file and initializes the corresponding Complex object
- Parameters
path (str) – path to MACE-generated XYZ file
- Returns
complex object
- Return type
Type[Complex]
- mace.MolFromSmiles(smiles)
Generates RDKit molecule from RDKit or ChemAxon SMILES; fixes the bond index bug
- Parameters
smiles (str) – ChemAxon SMILES
- Returns
RDKit molecule
- Return type
Type[Chem.Mol]
- mace.MolToSmiles(mol)
Generates SMILES from RDKit molecule (so that one does not need to import rdkit in addition to mace)
- Parameters
mol (Type[Chem.Mol]) – RDKit molecule
- Returns
SMILES of the molecule
- Return type
str
- mace.AddSubsToMol(mol, Rs)
Adds susbtituents to the molecule
- Parameters
mol (Type[Chem.Mol]) – RDKit molecule object, containing dummy atoms with non-zero isotopic labels corresponding to substituents numbers ([1*] <=> R1, [2*] <=> R2, etc.)
Rs (dict) – substituent name => RDKit molecule. Substituents names are “R1”, “R2”, etc. RDKit molecule must contain one single-bonded dummy atom, e.g. Chem.MolFromSmiles(‘[*]OC’) for the methoxy group
- Returns
RDKit molecule
- Return type
Type[Chem.Mol]