Assembled Complexes & Isomers API

class DARTassembler.src.assembler.isomer.AssembledIsomer(atomic_props, graph, metal_idc, donor_idc, ligand_idc, ligand_info=None, global_props=None, validity_check=False, target_vectors=None, ligand_origins=None, warning='', isomer_name=None)

Bases: BaseMolecule

Represent an assembled transition-metal complex isomer.

This class wraps the assembled ASE Atoms object together with connectivity graph, ligand/metal indices and metadata for downstream filtering and output.

Parameters:

• atomic_props (Union[ase.Atoms, dict[str, Any]]) – ASE Atoms object or dict of atomic properties describing the complex.

• graph (nx.Graph) – NetworkX graph representing atomic connectivity and node labels.

• metal_idc (list[int]) – Indices of metal center atoms in the ASE Atoms object.

• donor_idc (list[list[int]]) – Flattened indices of donor atoms in the merged graph.

• ligand_idc (list[list[int]]) – Indices of atoms belonging to each ligand in the merged graph.

• ligand_info (dict[str, Any] | None) – Dictionary containing ligand metadata required to reconstruct Ligand objects.

• global_props (dict[str, Any] | None) – Global properties for the molecule.

• validity_check (bool) – If True, run transition-metal-complex specific validity checks.

• target_vectors (list[list[list[float]]] | None) – Target donor vectors used to assemble the isomer (one list per ligand).

• ligand_origins (list[list[float]] | None) – Origin coordinates (shape (3,)) used to translate each ligand to its metal center.

• warning (str) – Warning string (e.g., ‘clashing’ or ‘duplicate(…)’) to annotate the isomer.

• isomer_name (str | None) – Unique name assigned to the isomer for identification.

Initialize a BaseMolecule instance, which represents a molecule with molecular graph (atomic connectivity) and atomic properties such as 3D coordinates.

Parameters:

• graph (nx.Graph) – NetworkX Graph describing connectivity. Nodes should correspond to atomic_props ordering.

• atomic_props (dict | ase.Atoms) –

  ASE Atoms object or atomic properties dictionary. Example format:

  {
      'atoms': ['C','H','O',...],
      'x': [x1, x2, ...],
      'y': [y1, y2, ...],
      'z': [z1, z2, ...],
      ... (optional per-atom arrays)
  }
  

• global_props (dict | None) –

  Optional flat dictionary of global properties (charge, stoichiometry, etc.). Example format:

  {
      'charge': -1,
      'stoichiometry': 'C6H6O',
      ...
  }
  

• validity_check (bool) – If True, perform internal consistency checks comparing graph and coordinates.

• node_label (str) – Node attribute key used for element symbols in graphs.

• bond_label (str) – Edge attribute key used for bond type information in graphs.

Raises:

AssertionError – If graph and atomic_props are inconsistent when validity_check is True.

update_positions(newatoms)

Update the atomic positions of the isomer and its ligands. Ensures atom symbols match. Should be used instead of manually updating atoms/atomic_props. :param newatoms: ASE Atoms object with updated positions. :return: None :rtype: None

round_positions(decimals=6)

Round the atomic positions of the isomer to a specified number of decimal places. Useful to avoid tiny numerical differences in tests. :param decimals: Number of decimal places to round to. :return: None :rtype: None

get_metal_symbols()

Return the chemical symbols of the metal center atoms.

Returns:

Chemical symbols of metals in the same order as metal_idc.

Return type:

list[str]

to_dict()

Convert the AssembledIsomer to a serializable dictionary.

The returned dictionary includes atomic properties, connectivity graph (handled by the base class), and assembly-specific metadata such as metal/donor/ligand indices.

Returns:

Dictionary representation suitable for JSON or other serialization.

Return type:

dict[str, Any]

class DARTassembler.src.assembler.isomer.AssembledComplex(ligands, target_vectors, metal_centers, ligand_origins=None)

Bases: object

Assemble transition-metal complex isomers from Ligand objects, target vectors and metal centers.

The class stores the input ligands, their target donor vectors and metal center definitions and provides methods to generate assembled isomers, perform mono-axial optimization and filter duplicates.

The assembler will align and translate each ligand such that its donor atoms point along the provided target_vectors and place metal center atoms at the specified coordinates. If metal_centers is a string (element symbol), a single metal center at the origin is assumed for each ligand (mono-metallic complex).

Parameters:

• ligands (list[ Ligand ]) – Sequence of Ligand objects to assemble.

• target_vectors (list[list[list[float]]] # shape: (n_ligands, n_donors_per_ligand, 3)) – For each ligand, a list of donor target vectors (each vector length 3).

• metal_centers (Union[str, list[list[ Union[str, list[float]] ]]]) – Either a symbol string for a single metal at origin, or a list where each entry corresponds to the metal center(s) the ligand binds to. For the latter, each metal is a tuple [element_symbol, [x,y,z]].

• ligand_origins (list[list[float]] | None) – Optional list of origin coordinates (3 floats) for each ligand; if None, defaults to the corresponding metal center positions (or the mean for bridging ligands).

• ligand_origins – Optional list of origin coordinates (3 floats) for each ligand; if None, defaults to the corresponding metal center positions (or the mean for bridging ligands).

Example usage for assembling a mono-metallic square-planar Pd complex with 2 cis bidentate ligands in the xy-plane:

factory = AssembledComplex(
            ligands=... # (list of two 2-cis Ligand() objects from the MetaLig)
            metal_centers='Pd',
            target_vectors=[
                            [[1, 0, 0], [0, 1, 0]],     # the donor atoms of the first bidentate ligand are oriented in (+x,+y) direction
                            [[-1, 0, 0], [0, -1, 0]],   # the donor atoms of the second bidentate ligand are oriented in (-x,-y) direction
                            ],
            )

Example usage for assembling a bi-metallic complex with three monodentate ligands, each one at either end and the third one bridging:

ligands = ... # (list of three 1-mono Ligand() objects from the MetaLig)
ru = ['Ru', [1, 0, 0]]
fe = ['Fe', [-1, 0, 0]]
metal_centers = [
                    [ru],       # metal center for the first ligand
                    [fe]        # metal center for the second ligand
                    [ru, fe],   # metal centers for the third, bridging ligand. By default, the ligand will be placed at the center between both metals.
                ]
target_vectors = [
                    [[1, 0, 0]],    # bound to Ru, pointing away from center
                    [[-1, 0, 0]],   # bound to Fe, pointing away from center
                    [[0, 0, 1]],    # bridging between Ru and Fe, pointing up
                 ]
factory = AssembledComplex(
                            ligands=ligands,
                            target_vectors=target_vectors,
                            metal_centers=metal_centers
                            )
isomers = factory.generate_isomers()

generate_isomers(permutable_ligands=None, monoaxial_optimization=True, force_all_isomers=False, clashing_tolerance=-0.3, clashing_metal=False, duplicate_tolerance=0.5, complex_name_length=8, complex_name_suffix='', avoid_names=None)

Generate assembled isomers from the provided ligands and metal centers.

The method constructs all geometric combinations by assigning rotated ligand instances to metal centers, applies optional mono-axial optimization, filters clashing isomers, and groups duplicates via fingerprint or alignment-based comparison.

Parameters:

• permutable_ligands (list[int] | None) – Indices of ligands allowed to be permuted when generating isomers.

• monoaxial_optimization (bool) – Whether to perform mono-axial rotation optimization for mono-coordinating ligands.

• force_all_isomers (bool) – If True, generate all geometrical isomers for each ligand archetype.

• clashing_tolerance (float | None) – Distance buffer below covalent radii sum allowed before flagging a clash (Å).

• clashing_metal (bool) – If True, also check ligand-metal and metal-metal clashes.

• duplicate_tolerance (float) – Cutoff used by duplicate grouping (fingerprint threshold).

• complex_name_length (int) – Length of the generated complex name seed.

• complex_name_suffix (str) – Optional suffix appended to generated complex names.

• avoid_names (Iterable[str] | None) – Iterable of names to avoid when generating unique complex names.

Returns:

None. Results are stored on the AssembledComplex instance as isomers, successful_isomers, unsuccessful_isomers and success boolean.

Return type:

None

to_dict()

Convert the AssembledComplex factory state to a dictionary.

The resulting dictionary contains the generated isomers (by name), the merged connectivity graph, graph hash, index mappings and the input parameters used to assemble.

Returns:

Dictionary containing assembly metadata and serialized isomer entries.

Return type:

dict[str, Any]