formal_charges

Formal charge assignment for molecular graphs.

Assigns formal charges based on valence analysis and recognition of common charged functional groups (nitro, carboxylate, ammonium, etc.).

assign_formal_charges(graph)

Return a new MolecularGraph with formal charges assigned.

Parameters:

Name	Type	Description	Default
graph	MolecularGraph	Input MolecularGraph.	required

Returns:

Type	Description
MolecularGraph	New MolecularGraph with formal_charges populated.

Source code in chmpy/graph/formal_charges.py

def assign_formal_charges(graph: "MolecularGraph") -> "MolecularGraph":
    """
    Return a new MolecularGraph with formal charges assigned.

    Args:
        graph: Input MolecularGraph.

    Returns:
        New MolecularGraph with formal_charges populated.
    """
    charges = guess_formal_charges(graph)

    # Create new graph with charges
    from .adjacency import MolecularGraph as MG
    return MG(
        graph.atomic_numbers,
        graph.positions,
        graph.adjacency,
        bond_orders=graph.bond_orders,
        bond_distances=graph.bond_distances,
        formal_charges=charges,
    )

guess_formal_charges(graph)

Guess formal charges for atoms in a molecular graph.

Uses valence analysis and pattern recognition to identify charged atoms. Handles common functional groups like: - Nitro groups: N+[O-] - Carboxylates: C(=O)[O-] - Ammonium: [NH4+], [NR4+] - Sulfonates, phosphates, etc.

Parameters:

Name	Type	Description	Default
graph	MolecularGraph	A MolecularGraph instance.	required

Returns:

Type	Description
ndarray	Array of formal charges (integers) for each atom.

Source code in chmpy/graph/formal_charges.py

def guess_formal_charges(graph: "MolecularGraph") -> np.ndarray:
    """
    Guess formal charges for atoms in a molecular graph.

    Uses valence analysis and pattern recognition to identify charged
    atoms. Handles common functional groups like:
    - Nitro groups: [N+](=O)[O-]
    - Carboxylates: C(=O)[O-]
    - Ammonium: [NH4+], [NR4+]
    - Sulfonates, phosphates, etc.

    Args:
        graph: A MolecularGraph instance.

    Returns:
        Array of formal charges (integers) for each atom.
    """
    n = graph.n_atoms
    charges = np.zeros(n, dtype=np.int32)

    # Track which atoms have been assigned charges
    assigned = set()

    # First pass: identify specific functional groups
    _assign_nitro_charges(graph, charges, assigned)
    _assign_carboxylate_charges(graph, charges, assigned)
    _assign_noxide_charges(graph, charges, assigned)

    # Second pass: check for atoms with unusual valence
    _assign_valence_based_charges(graph, charges, assigned)

    return charges