Threads, errors, elements and units¶

Threads and indices¶

get_num_threads ¶

get_num_threads()

Number of threads used by compiled kernels.

Returns:

Type	Description
`int64`	The current setting. Defaults to the number of logical CPUs this process may use, or to the `MDAPY_NUM_THREADS` environment variable if it was set when MDAPY was imported.

set_num_threads ¶

set_num_threads(n)

Set the number of threads used by compiled kernels.

The setting is global to the process and takes effect at the next computation.

Parameters:

Name	Type	Description	Default
`n`	`int32`	Number of threads, at least 1.	required

Raises:

Type	Description
`InvalidParameter`	If `n` is not a positive integer.

num_threads ¶

num_threads(n)

Use n threads inside a with block.

The previous setting is restored when the block exits, also on error. Like set_num_threads, the setting is global to the process.

Parameters:

Name	Type	Description	Default
`n`	`int32`	Number of threads, at least 1.	required

Raises:

Type	Description
`InvalidParameter`	If `n` is not a positive integer.

CancelToken ¶

CancelToken()

Flag for stopping a running computation from another thread.

Pass the token to a computation that accepts cancel=. Calling cancel from any thread makes that computation stop at the next chunk of work and raise mdapy.errors.Cancelled.

cancelled `property` ¶

cancelled

Whether cancellation has been requested.

cancel ¶

cancel()

Request cancellation.

reset ¶

reset()

Clear the request so the token can be used again.

index_dtype `module-attribute` ¶

index_dtype = np.dtype(f'int{_core.index_bits}')

numpy.dtype of atom indices in results such as neighbor lists: int32, or int64 when MDAPY was built with -Ccmake.define.MDAPY_INDEX64=ON.

Results¶

Result `dataclass` ¶

Result()

Results of an analysis: immutable, with read-only arrays.

System.with_columns(result) adds the per-atom values of columns to a system.

columns ¶

columns()

Per-atom values by column name; empty for results of a whole system.

Versions¶

show_versions ¶

show_versions(file=None)

Print the versions of MDAPY, Python and the packages MDAPY depends on, and the processor, memory and GPU of this machine, to paste into an issue.

Parameters:

Name	Type	Description	Default
`file`	`text stream`	Where to print them; the standard output by default.	`None`

Errors¶

errors ¶

Exception types raised by mdapy.

MdapyError ¶

Bases: Exception

Base class of every exception raised by mdapy.

InvalidParameter ¶

Bases: MdapyError, ValueError

A parameter has a value that MDAPY cannot accept.

The message names the parameter and the accepted values.

MissingProperty ¶

Bases: MdapyError, LookupError

A required per-atom or global property is not present.

UnsupportedFormat ¶

Bases: MdapyError, ValueError

A file format is unknown, or an operation is not supported for it.

FileFormatError ¶

FileFormatError(message, path=None, line=None)

Bases: MdapyError, ValueError

A file does not follow its format.

The message starts with the file name and, when known, the line number.

Attributes:

Name	Type	Description
`path`	`str or None`	Name of the file.
`line`	`int32 or None`	Line number, counting from 1.

Cancelled ¶

Bases: MdapyError

A computation was stopped through a mdapy.CancelToken.

CalculationFailed ¶

Bases: MdapyError, RuntimeError

An external program behind a calculator, such as VASP, did not finish a calculation.

The message holds the end of what the program wrote.

Elements¶

elements ¶

Chemical elements: symbols, atomic numbers, standard atomic weights and radii.

Atomic weights are the IUPAC 2016 standard atomic weights; for elements without stable isotopes they are the mass number of the longest-lived isotope. Covalent radii are those of Cordero et al. (2008), van der Waals radii those of Alvarez (2013).

ATOMIC_MASSES `module-attribute` ¶

ATOMIC_MASSES = np.array(_ATOMIC_MASSES, dtype=np.float64)

Standard atomic weights in amu, indexed by atomic number (index 0 is 0.0).

COVALENT_RADII `module-attribute` ¶

COVALENT_RADII = np.array(_COVALENT_RADII, dtype=np.float64)

Covalent radii in Å (Cordero et al. 2008), indexed by atomic number; NaN where there is none.

VDW_RADII `module-attribute` ¶

VDW_RADII = np.array(_VDW_RADII, dtype=np.float64)

Van der Waals radii in Å (Alvarez 2013), indexed by atomic number; NaN where there is none.

ELEMENT_DTYPE `module-attribute` ¶

ELEMENT_DTYPE = pl.Enum(SYMBOLS)

polars dtype of the element column. Its physical value is the atomic number.

atomic_numbers ¶

atomic_numbers(symbols)

Atomic numbers of chemical symbols.

Parameters:

Name	Type	Description	Default
`symbols`	`iterable of str`	Chemical symbols, case-sensitive (`"Cu"`, not `"CU"`). `"X"` stands for an unknown element and maps to 0.	required

Returns:

Type	Description
`ndarray`	(N,) int64, the atomic numbers, one per symbol.

Raises:

Type	Description
`InvalidParameter`	If a symbol is not a chemical symbol.

atomic_masses ¶

atomic_masses(elements)

Standard atomic weights of elements.

Parameters:

Name	Type	Description	Default
`elements`	`iterable of str or int32`	Chemical symbols or atomic numbers (1-118).	required

Returns:

Type	Description
`ndarray`	(N,) float64, atomic weights in amu, one per element.

Raises:

Type	Description
`InvalidParameter`	If an element is unknown, including `"X"` and 0, which have no mass.

covalent_radii ¶

covalent_radii(elements)

Covalent radii of elements (Cordero et al. 2008).

Parameters:

Name	Type	Description	Default
`elements`	`iterable of str or int32`	Chemical symbols or atomic numbers.	required

Returns:

Type	Description
`ndarray`	(N,) float64, radii in Å, one per element.

Raises:

Type	Description
`InvalidParameter`	If an element is unknown or has no covalent radius, as `"X"`.

vdw_radii ¶

vdw_radii(elements)

Van der Waals radii of elements (Alvarez 2013).

Parameters:

Name	Type	Description	Default
`elements`	`iterable of str or int32`	Chemical symbols or atomic numbers.	required

Returns:

Type	Description
`ndarray`	(N,) float64, radii in Å, one per element.

Raises:

Type	Description
`InvalidParameter`	If an element is unknown or has no van der Waals radius.

element_from_mass ¶

element_from_mass(mass, tolerance=0.01, candidates=None)

The element whose standard atomic weight matches a mass.

Parameters:

Name	Type	Description	Default
`mass`	`float64`	Mass in amu.	required
`tolerance`	`float64`	Largest accepted difference in amu between `mass` and the atomic weight. Default 0.01.	`0.01`
`candidates`	`iterable of str`	Chemical symbols to choose from. Default: the elements with at least one stable isotope (H to Bi, without Tc and Pm). Radioactive elements such as Po, whose atomic weights can lie within 0.01 amu of another element's, are only matched when listed here.	`None`

Returns:

Type	Description
`str`	Chemical symbol of the matching element.

Raises:

Type	Description
`InvalidParameter`	If no candidate, or more than one, lies within `tolerance`.

Units¶

units ¶

Physical constants and unit conversion factors.

MDAPY works in one unit system: length in Å, energy in eV, time in ps, mass in amu, temperature in K, charge in e, force in eV/Å, stress and pressure in GPa. Every conversion in the package uses the factors defined here.

A factor named A_TO_B converts a value expressed in unit A into unit B by multiplication.

ELEMENTARY_CHARGE `module-attribute` ¶

ELEMENTARY_CHARGE = 1.602176634e-19

Elementary charge in C (exact, 2019 SI).

BOLTZMANN_SI `module-attribute` ¶

BOLTZMANN_SI = 1.380649e-23

Boltzmann constant in J/K (exact, 2019 SI).

PLANCK_SI `module-attribute` ¶

PLANCK_SI = 6.62607015e-34

Planck constant in J·s (exact, 2019 SI).

AVOGADRO `module-attribute` ¶

AVOGADRO = 6.02214076e+23

Avogadro constant in 1/mol (exact, 2019 SI).

ATOMIC_MASS_UNIT_SI `module-attribute` ¶

ATOMIC_MASS_UNIT_SI = 1.66053906892e-27

Atomic mass constant in kg (CODATA 2022).

BOLTZMANN `module-attribute` ¶

BOLTZMANN = BOLTZMANN_SI / ELEMENTARY_CHARGE

Boltzmann constant in eV/K.

PLANCK `module-attribute` ¶

PLANCK = PLANCK_SI / ELEMENTARY_CHARGE * 1000000000000.0

Planck constant in eV·ps: the energy in eV of a quantum of 1 THz.

EV_PER_A3_TO_GPA `module-attribute` ¶

EV_PER_A3_TO_GPA = ELEMENTARY_CHARGE * 1e+30 / 1000000000.0

Stress: eV/Å³ to GPa.

GPA_TO_EV_PER_A3 `module-attribute` ¶

GPA_TO_EV_PER_A3 = 1.0 / EV_PER_A3_TO_GPA

Stress: GPa to eV/Å³.

BAR_TO_GPA `module-attribute` ¶

BAR_TO_GPA = 0.0001

Pressure: bar to GPa (exact).

GPA_TO_BAR `module-attribute` ¶

GPA_TO_BAR = 10000.0

Pressure: GPa to bar (exact).

EV_PER_A2_TO_J_PER_M2 `module-attribute` ¶

EV_PER_A2_TO_J_PER_M2 = ELEMENTARY_CHARGE * 1e+20

Energy per area: eV/Å² to J/m² (equal to N/m).

GPA_A_TO_N_PER_M `module-attribute` ¶

GPA_A_TO_N_PER_M = 0.1

Two-dimensional stress: GPa·Å to N/m (exact).

FS_TO_PS `module-attribute` ¶

FS_TO_PS = 0.001

Time: fs to ps (exact).

PS_TO_FS `module-attribute` ¶

PS_TO_FS = 1000.0

Time: ps to fs (exact).

AMU_A2_PER_PS2_TO_EV `module-attribute` ¶

AMU_A2_PER_PS2_TO_EV = ATOMIC_MASS_UNIT_SI * 10000.0 / ELEMENTARY_CHARGE

Kinetic energy: amu·Å²/ps² to eV (mass times velocity squared).

KJ_PER_MOL_TO_EV `module-attribute` ¶

KJ_PER_MOL_TO_EV = 1000.0 / (AVOGADRO * ELEMENTARY_CHARGE)

Energy: kJ/mol to eV.

KCAL_PER_MOL_TO_EV `module-attribute` ¶

KCAL_PER_MOL_TO_EV = 4.184 * KJ_PER_MOL_TO_EV

Energy: kcal/mol (thermochemical calorie, 4.184 J) to eV.

Threads, errors, elements and units¶

Threads and indices¶

get_num_threads ¶

set_num_threads ¶

num_threads ¶

CancelToken ¶

cancelled property ¶

cancel ¶

reset ¶

index_dtype module-attribute ¶

Results¶

Result dataclass ¶

columns ¶

Versions¶

show_versions ¶

Errors¶

errors ¶

MdapyError ¶

InvalidParameter ¶

MissingProperty ¶

UnsupportedFormat ¶

FileFormatError ¶

Cancelled ¶

CalculationFailed ¶

Elements¶

elements ¶

ATOMIC_MASSES module-attribute ¶

COVALENT_RADII module-attribute ¶

VDW_RADII module-attribute ¶

ELEMENT_DTYPE module-attribute ¶

atomic_numbers ¶

atomic_masses ¶

covalent_radii ¶

vdw_radii ¶

element_from_mass ¶

Units¶

units ¶

ELEMENTARY_CHARGE module-attribute ¶

BOLTZMANN_SI module-attribute ¶

PLANCK_SI module-attribute ¶

AVOGADRO module-attribute ¶

ATOMIC_MASS_UNIT_SI module-attribute ¶

BOLTZMANN module-attribute ¶

PLANCK module-attribute ¶

EV_PER_A3_TO_GPA module-attribute ¶

GPA_TO_EV_PER_A3 module-attribute ¶

BAR_TO_GPA module-attribute ¶

GPA_TO_BAR module-attribute ¶

EV_PER_A2_TO_J_PER_M2 module-attribute ¶

GPA_A_TO_N_PER_M module-attribute ¶

FS_TO_PS module-attribute ¶

PS_TO_FS module-attribute ¶

AMU_A2_PER_PS2_TO_EV module-attribute ¶

KJ_PER_MOL_TO_EV module-attribute ¶

KCAL_PER_MOL_TO_EV module-attribute ¶

cancelled `property` ¶

index_dtype `module-attribute` ¶

Result `dataclass` ¶

ATOMIC_MASSES `module-attribute` ¶

COVALENT_RADII `module-attribute` ¶

VDW_RADII `module-attribute` ¶

ELEMENT_DTYPE `module-attribute` ¶

ELEMENTARY_CHARGE `module-attribute` ¶

BOLTZMANN_SI `module-attribute` ¶

PLANCK_SI `module-attribute` ¶

AVOGADRO `module-attribute` ¶

ATOMIC_MASS_UNIT_SI `module-attribute` ¶

BOLTZMANN `module-attribute` ¶

PLANCK `module-attribute` ¶

EV_PER_A3_TO_GPA `module-attribute` ¶

GPA_TO_EV_PER_A3 `module-attribute` ¶

BAR_TO_GPA `module-attribute` ¶

GPA_TO_BAR `module-attribute` ¶

EV_PER_A2_TO_J_PER_M2 `module-attribute` ¶

GPA_A_TO_N_PER_M `module-attribute` ¶

FS_TO_PS `module-attribute` ¶

PS_TO_FS `module-attribute` ¶

AMU_A2_PER_PS2_TO_EV `module-attribute` ¶

KJ_PER_MOL_TO_EV `module-attribute` ¶

KCAL_PER_MOL_TO_EV `module-attribute` ¶