Skip to content

core

Utility functions for dealing with Atoms.

logger module-attribute 

logger = getLogger(__name__)

check_charge_and_spin 

check_charge_and_spin(
    atoms: Atoms,
    charge: int | None = None,
    spin_multiplicity: int | None = None,
) -> tuple[int, int]

Check the validity of a given charge and multiplicity. If they are None, then set the charge and/or spin multiplicity of a molecule using the following routine, raising a ValueError if there is an incompatibility.

Charges:

  1. If charge is specified, that is the charge.

  2. If atoms.charge is present, that is the charge.

  3. If atoms.has("initial_charges"), then atoms.get_initial_charges.sum() is the charge.

  4. If spin_multiplicity is set, set the charge to the smallest physically possible value.

  5. Otherwise, set to 0.

Spin multiplicity:

  1. If spin_multiplicity is specified, that is the spin multiplicity.

  2. If atoms.spin_multiplicity is present, that is the spin multiplicity.

  3. If atoms.has("initial_magmoms"), then np.abs(atoms.get_initial_magnetic_moments().sum())+1 is the spin multiplicity.

  4. If none of the above, use Pymatgen to identify the lowest physically possible spin multiplicity given the number of electrons and the charge, if set.

Parameters:

  • atoms (Atoms) –

    Atoms object

  • charge (int | None, default: None ) –

    Molecular charge

  • spin_multiplicity (int | None, default: None ) –

    Molecular multiplicity

Returns:

  • (charge, multiplicity) –
Source code in quacc/atoms/core.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
def check_charge_and_spin(
    atoms: Atoms, charge: int | None = None, spin_multiplicity: int | None = None
) -> tuple[int, int]:
    """
    Check the validity of a given `charge` and `multiplicity`. If they are `None`, then
    set the charge and/or spin multiplicity of a molecule using the following routine,
    raising a `ValueError` if there is an incompatibility.

    Charges:

    1. If `charge` is specified, that is the charge.

    2. If `atoms.charge` is present, that is the charge.

    3. If `atoms.has("initial_charges")`, then
    `atoms.get_initial_charges.sum()` is the charge.

    4. If `spin_multiplicity` is set, set the charge to the smallest physically
    possible value.

    5. Otherwise, set to 0.

    Spin multiplicity:

    1. If `spin_multiplicity` is specified, that is the spin multiplicity.

    2. If `atoms.spin_multiplicity` is present, that is the spin multiplicity.

    3. If `atoms.has("initial_magmoms")`, then
    `np.abs(atoms.get_initial_magnetic_moments().sum())+1` is the spin
    multiplicity.

    4. If none of the above, use Pymatgen to identify the lowest physically
    possible spin multiplicity given the number of electrons and the charge, if
    set.

    Parameters
    ----------
    atoms
        Atoms object
    charge
        Molecular charge
    spin_multiplicity
        Molecular multiplicity

    Returns
    -------
    charge, multiplicity
    """
    charge = charge if charge is not None else get_charge_attribute(atoms)
    spin_multiplicity = (
        spin_multiplicity
        if spin_multiplicity is not None
        else get_spin_multiplicity_attribute(atoms)
    )

    if charge is None and spin_multiplicity is not None:
        charge = 0

    try:
        mol = AseAtomsAdaptor.get_molecule(atoms)
        if charge is not None:
            if spin_multiplicity is not None:
                mol.set_charge_and_spin(charge, spin_multiplicity)
            else:
                mol.set_charge_and_spin(charge)
    except ValueError:
        mol = AseAtomsAdaptor.get_molecule(atoms, charge_spin_check=False)
        nelectrons = mol.nelectrons - charge if charge else mol.nelectrons
        default_spin_multiplicity = 1 if nelectrons % 2 == 0 else 2
        mol.set_charge_and_spin(
            charge if charge is not None else mol.charge,
            (
                spin_multiplicity
                if spin_multiplicity is not None
                else default_spin_multiplicity
            ),
        )
    if (mol.nelectrons + mol.spin_multiplicity) % 2 != 1:
        raise ValueError(
            f"Charge of {mol.charge} and spin multiplicity of {mol.spin_multiplicity} is"
            " not possible for this molecule."
        )
    logger.debug(
        f"Setting charge to {mol.charge} and spin multiplicity to {mol.spin_multiplicity}"
    )

    return mol.charge, mol.spin_multiplicity

check_is_metal 

check_is_metal(atoms: Atoms) -> bool

Checks if a structure is a likely metal.

Parameters:

  • atoms (Atoms) –

    Atoms object

Returns:

  • bool –

    True if the structure is likely a metal; False otherwise

Source code in quacc/atoms/core.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
def check_is_metal(atoms: Atoms) -> bool:
    """
    Checks if a structure is a likely metal.

    Parameters
    ----------
    atoms
        Atoms object

    Returns
    -------
    bool
        True if the structure is likely a metal; False otherwise
    """
    if atoms.pbc.any():
        struct = AseAtomsAdaptor.get_structure(atoms)
    else:
        struct = AseAtomsAdaptor.get_molecule(atoms, charge_spin_check=False)

    return all(k.is_metal for k in struct.composition)

copy_atoms 

copy_atoms(atoms: Atoms) -> Atoms

Simple function to copy an atoms object to prevent mutability.

Parameters:

  • atoms (Atoms) –

    Atoms object

Returns:

  • atoms –

    Atoms object

Source code in quacc/atoms/core.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
def copy_atoms(atoms: Atoms) -> Atoms:
    """
    Simple function to copy an atoms object to prevent mutability.

    Parameters
    ----------
    atoms
        Atoms object

    Returns
    -------
    atoms
        Atoms object
    """
    try:
        atoms = deepcopy(atoms)
    except Exception:
        # Needed because of ASE issue #1084
        calc = atoms.calc
        atoms = atoms.copy()
        atoms.calc = calc

    return atoms

get_atoms_id 

get_atoms_id(atoms: Atoms) -> str

Returns a unique ID for the Atoms object. Note: The .info dict and calculator is excluded from the hash generation.

Parameters:

  • atoms (Atoms) –

    Atoms object

Returns:

  • str –

    MD5 hash of the Atoms object

Source code in quacc/atoms/core.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def get_atoms_id(atoms: Atoms) -> str:
    """
    Returns a unique ID for the Atoms object. Note: The .info dict and calculator is
    excluded from the hash generation.

    Parameters
    ----------
    atoms
        Atoms object

    Returns
    -------
    str
        MD5 hash of the Atoms object
    """
    atoms = copy_atoms(atoms)
    atoms.info = {}
    atoms.calc = None
    encoded_atoms = encode(atoms)
    # This is a hack to avoid int32/int64 and float32/float64 differences
    # between machines.
    encoded_atoms = (
        encoded_atoms.replace("int64", "int")
        .replace("int32", "int")
        .replace("float64", "float")
        .replace("float32", "float")
    )

    return hashlib.md5(encoded_atoms.encode("utf-8")).hexdigest()

get_charge_attribute 

get_charge_attribute(atoms: Atoms) -> int | None

Get the charge of an Atoms object.

Parameters:

  • atoms (Atoms) –

    Atoms object

Returns:

  • int | None –

    Charge of the Atoms object

Source code in quacc/atoms/core.py 
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
def get_charge_attribute(atoms: Atoms) -> int | None:
    """
    Get the charge of an Atoms object.

    Parameters
    ----------
    atoms
        Atoms object

    Returns
    -------
    int | None
        Charge of the Atoms object
    """
    return (
        atoms.charge
        if getattr(atoms, "charge", None)
        else (
            round(atoms.get_initial_charges().sum())
            if atoms.has("initial_charges")
            else None
        )
    )

get_final_atoms_from_dynamics 

get_final_atoms_from_dynamics(dynamics: Dynamics) -> Atoms

Get the final atoms object from a dynamics run.

Parameters:

  • dynamics (Dynamics) –

    ASE dynamics object

Returns:

Source code in quacc/atoms/core.py 
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
def get_final_atoms_from_dynamics(dynamics: Dynamics) -> Atoms:
    """
    Get the final atoms object from a dynamics run.

    Parameters
    ----------
    dynamics
        ASE dynamics object

    Returns
    -------
    Atoms
        Atoms object
    """
    return (
        dynamics.atoms.atoms if isinstance(dynamics.atoms, Filter) else dynamics.atoms
    )

get_spin_multiplicity_attribute 

get_spin_multiplicity_attribute(atoms: Atoms) -> int | None

Get the spin multiplicity of an Atoms object.

Parameters:

  • atoms (Atoms) –

    Atoms object

Returns:

  • int | None –

    Spin multiplicity of the Atoms object

Source code in quacc/atoms/core.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
def get_spin_multiplicity_attribute(atoms: Atoms) -> int | None:
    """
    Get the spin multiplicity of an Atoms object.

    Parameters
    ----------
    atoms
        Atoms object

    Returns
    -------
    int | None
        Spin multiplicity of the Atoms object
    """
    return (
        atoms.spin_multiplicity
        if getattr(atoms, "spin_multiplicity", None)
        else (
            round(np.abs(atoms.get_initial_magnetic_moments().sum()) + 1)
            if atoms.has("initial_magmoms")
            else None
        )
    )

perturb 

perturb(
    mol: Atoms,
    matrix: list[list[float]] | NDArray,
    scale: float,
) -> Atoms

Perturb each atom in a molecule by a (scaled) 1x3 vector, reflecting e.g. a vibrational normal mode.

Parameters:

  • mol (Atoms) –

    ASE Atoms object representing a molecule

  • matrix (list[list[float]] | NDArray) –

    Nx3 matrix, where N is the numebr of atoms. This means that there is potentially a different translation vector for each atom in the molecule.

  • scale (float) –

    Scaling factor for perturbation

Returns:

  • Atoms –

    The input molecule after perturbation

Source code in quacc/atoms/core.py 
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
def perturb(mol: Atoms, matrix: list[list[float]] | NDArray, scale: float) -> Atoms:
    """
    Perturb each atom in a molecule by a (scaled) 1x3 vector, reflecting e.g. a vibrational normal mode.

    Parameters
    ----------
    mol
        ASE Atoms object representing a molecule
    matrix
        Nx3 matrix, where N is the numebr of atoms. This means that there is potentially a different translation
        vector for each atom in the molecule.
    scale
        Scaling factor for perturbation

    Returns
    -------
    Atoms
        The input molecule after perturbation
    """

    mol_copy = copy_atoms(mol)
    mode = np.asarray(matrix)

    orig_pos = mol_copy.get_positions()

    pos = orig_pos + mode * scale
    mol_copy.set_positions(pos)

    return mol_copy