Units and Conventions #

Returns:

float or ndarray – The same quantity in this system’s units.

Examples

>>> u = geometrized_units(mass_kg=const.SOLAR_MASS_KG)
>>> round(u.from_si(const.C, "velocity"), 12)
1.0

is_determined(dimension)[source]#

Whether the anchors fix the SI size of one unit of dimension.

Parameters:: dimension (str | Dimension) – A key of DIMENSIONS or a Dimension.
Return type:: bool
Returns:: bool

Examples

>>> u = statphys_units(energy_j=1.0e-21)
>>> u.is_determined("temperature"), u.is_determined("length")
(True, False)

name: str#

scale(dimension)[source]#

SI value of one unit of dimension in this system.

Parameters:: dimension (str | Dimension) – A key of DIMENSIONS or a Dimension.
Return type:: float
Returns:: float
Raises:: ValueError – If the system’s anchors do not determine this dimension.

Examples

>>> u = quantum_units(mass_kg=const.ELECTRON_MASS, length_m=5.29177210903e-11)
>>> print(f"{u.scale('time'):.4e}")  # atomic unit of time, s
2.4189e-17

scales()[source]#

SI value of one unit for every named dimension this system fixes.

Return type:: dict[str, float]
Returns:: dict of str to float – Keys are the entries of DIMENSIONS that are determined.

Examples

>>> sorted(statphys_units(temperature_k=300.0).scales())
['dimensionless', 'energy', 'entropy', 'temperature']

to_dict()[source]#

Serialize to a JSON-compatible dict (inverse of from_dict()).

Return type:: dict[str, Any]
Returns:: dict

to_si(value, dimension)[source]#

Convert value from this system to SI.

Parameters:

value (ArrayLike) – Quantity expressed in this system’s units.
dimension (str | Dimension) – The quantity’s dimension.

Return type:

Returns:

float or ndarray – The same quantity in SI units.

Examples

>>> u = astro_units(length_m=const.ASTRONOMICAL_UNIT_M, mass_kg=const.SOLAR_MASS_KG)
>>> round(u.to_si(2 * np.pi, "time") / 86400 / 365.25, 4)  # Earth's orbit in years
1.0

physicskit.units.astro_units(*, length_m, mass_kg)[source]#

Gravitational units, \(G = 1\), as used by physicskit.astro.

The time unit follows from \(G_{SI} = L^3/(M T^2)\), i.e. \(T = \sqrt{L^3/(G_{SI} M)}\) (same as physicskit.constants.gravitational_unit_system()).

Parameters:

length_m (float) – SI length of one length unit, in m.
mass_kg (float) – SI mass of one mass unit, in kg.

Return type:

Returns:

UnitSystem

Examples

With 1 pc and 1 solar mass, one time unit is about 14.9 Myr:

>>> u = astro_units(length_m=const.PARSEC_M, mass_kg=const.SOLAR_MASS_KG)
>>> round(u.scale("time") / (1e6 * 365.25 * 86400), 2)
14.91

physicskit.units.from_pint(quantity, system)[source]#

Convert a pint quantity into system’s units.

The dimension is read from the quantity itself. Requires the optional pint dependency (physicskit[units]).

Parameters:

quantity (Any) – Any quantity whose dimensionality is built from length, mass, time and temperature.
system (UnitSystem) – The target unit system.

Return type:

Returns:

float or ndarray – The magnitude in system’s units.

Raises:

ValueError – If quantity involves another base dimension (e.g. current).

Examples

>>> import pint
>>> ureg = pint.UnitRegistry()
>>> from_pint(1476.6 * ureg.meter, geometrized_units(mass_kg=const.SOLAR_MASS_KG))
0.99997...

physicskit.units.from_si(value, dimension, system)[source]#

Convert an SI value into system’s units.

Equivalent to system.from_si(value, dimension).

Parameters:

value (ArrayLike) – Quantity in SI units.
dimension (str | Dimension) – The quantity’s dimension.
system (UnitSystem) – The target unit system.

Return type:

Returns:

float or ndarray

Examples

>>> round(from_si(300.0, "temperature", statphys_units(temperature_k=300.0)), 12)
1.0

physicskit.units.geometrized_units(*, mass_kg=None, length_m=None)[source]#

Geometrized units, \(G = c = 1\), as used by physicskit.relativity.

With a mass scale \(M\), one unit of length is \(GM/c^2\) and one unit of time is \(GM/c^3\) (Misner, Thorne & Wheeler, Gravitation, 1973, Box 1.8).

Parameters:

mass_kg (float | None) – SI mass of one mass unit (conventionally the black-hole or system mass \(M\)).
length_m (float | None) – SI length of one length unit, as an alternative to mass_kg. Supply exactly one of the two.

Return type:

Returns:

UnitSystem

Examples

>>> u = geometrized_units(mass_kg=const.SOLAR_MASS_KG)
>>> print(f"{u.scale('length'):.5g} m, {u.scale('time') * 1e6:.4g} us")
1476.7 m, 4.926 us

physicskit.units.natural_units(*constants, name=None, length_m=None, mass_kg=None, time_s=None, energy_j=None, temperature_k=None)[source]#

Build a unit system with the given constants set to 1 and explicit scales.

Parameters:

*constants (str) – Names from NATURAL_CONSTANTS ("G", "c", "hbar", "k_B") to set equal to 1.
name (str | None) – Label for the system; defaults to e.g. "G=c=1".
length_m (float | None) – SI size of one unit of length, mass, time, energy or temperature.
mass_kg (float | None) – SI size of one unit of length, mass, time, energy or temperature.
time_s (float | None) – SI size of one unit of length, mass, time, energy or temperature.
energy_j (float | None) – SI size of one unit of length, mass, time, energy or temperature.
temperature_k (float | None) – SI size of one unit of length, mass, time, energy or temperature.

Return type:

Returns:

UnitSystem

Raises:

ValueError – For an unknown constant name, or scales that contradict the constants set to 1 (e.g. \(c = 1\) with both a length and a time scale that are not in ratio \(c\)).

Examples

Particle-physics units \(\hbar = c = 1\) with energies in GeV:

>>> gev = natural_units("hbar", "c", energy_j=1e9 * const.ELECTRONVOLT)
>>> round(gev.scale("length") * 1e15, 4)  # hbar*c / GeV, in fm
0.1973

physicskit.units.quantum_units(*, mass_kg, length_m=None, energy_j=None)[source]#

Units with \(\hbar = 1\), as used by physicskit.quantum.

Choosing a mass \(m\) and a length \(a\) fixes the energy unit \(\hbar^2/(m a^2)\) and time unit \(m a^2/\hbar\). With the electron mass and the Bohr radius these are the Hartree atomic units (CODATA: \(E_h = 27.211\) eV, \(t_{au} = 2.4189\times10^{-17}\) s).

Parameters:

mass_kg (float) – SI mass of one mass unit (the particle mass for m = 1 code).
length_m (float | None) – SI length of one length unit.
energy_j (float | None) – SI energy of one energy unit, as an alternative to length_m. Supply exactly one of the two.

Return type:

Returns:

UnitSystem

Examples

>>> au = quantum_units(mass_kg=const.ELECTRON_MASS, length_m=5.29177210903e-11)
>>> round(const.joules_to_ev(au.scale("energy")), 3)  # Hartree, eV
27.211

physicskit.units.statphys_units(*, energy_j=None, temperature_k=None, length_m=None, mass_kg=None)[source]#

Units with \(k_B = 1\), as used by physicskit.statphys.

With \(k_B = 1\) an energy scale \(\epsilon\) and a temperature scale \(\epsilon/k_B\) are the same choice, which is enough for lattice models (e.g. Ising with coupling \(J = 1\)). Molecular dynamics additionally needs a length \(\sigma\) and mass \(m\), giving the Lennard-Jones reduced time unit \(\tau = \sigma\sqrt{m/\epsilon}\) (Allen & Tildesley, Computer Simulation of Liquids, 2nd ed., 2017, Appendix B).

Parameters:

energy_j (float | None) – SI energy of one energy unit (e.g. the coupling \(J\)).
temperature_k (float | None) – SI temperature of one temperature unit, as an alternative to energy_j. Supply exactly one of the two.
length_m (float | None) – Length and mass scales, needed only to convert mechanical quantities such as time or pressure.
mass_kg (float | None) – Length and mass scales, needed only to convert mechanical quantities such as time or pressure.

Return type:

Returns:

UnitSystem

Examples

Lennard-Jones argon (\(\sigma = 3.405\) Å, \(\epsilon/k_B = 119.8\) K, \(m = 39.948\) u) has a time unit of about 2.16 ps:

>>> u = statphys_units(temperature_k=119.8, length_m=3.405e-10, mass_kg=39.948 * 1.66053906660e-27)
>>> round(u.scale("time") * 1e12, 2)
2.16

physicskit.units.to_pint(value, dimension, system, registry=None)[source]#

Convert a natural-unit value into a pint quantity in SI base units.

Requires the optional pint dependency (physicskit[units]).

Parameters:

value (ArrayLike) – Quantity in system’s units.
dimension (str | Dimension) – The quantity’s dimension.
system (UnitSystem) – The unit system value is expressed in.
registry (Any) – Registry to create the quantity in; defaults to pint.get_application_registry().

Return type:

Returns:

pint.Quantity

Examples

>>> q = to_pint(1.0, "length", geometrized_units(mass_kg=const.SOLAR_MASS_KG))
>>> q.to("km")
<Quantity(1.47662..., 'kilometer')>

physicskit.units.to_si(value, dimension, system)[source]#

Convert value from system’s units to SI.

Equivalent to system.to_si(value, dimension).

Parameters:

value (ArrayLike) – Quantity in system’s units.
dimension (str | Dimension) – The quantity’s dimension.
system (UnitSystem) – The unit system value is expressed in.

Return type:

Returns:

float or ndarray

Examples

>>> to_si(1.0, "length", geometrized_units(mass_kg=const.SOLAR_MASS_KG)) > 1476
True

A shared, unit-aware container for simulation output.

Subpackages return results in several shapes: a (times, states) tuple from the shared physicskit.integrators and the chaos flows, a (times, positions, velocities) tuple from the symplectic integrators, the classical SimulationResult, an orbit array from a chaos map, a quantum EigenResult, and an rmt Spectrum. Result is a single container they can all be converted to, which physicskit.io can save and load and which knows its units.

The container is opt-in. Subpackages keep returning their own types, and the from_* adapters below convert them. The adapters read attributes by name and do not import the subpackages.

Examples

>>> import numpy as np
>>> from physicskit.results import Result
>>> from physicskit.units import geometrized_units
>>> sun = geometrized_units(mass_kg=1.98847e30)
>>> r = Result(np.linspace(0.0, 10.0, 11), np.zeros((11, 2)), units={"times": "time"}, unit_system=sun)
>>> round(float(r.to_si().times[-1]) * 1e6, 2)  # 10 M in microseconds
49.26

class physicskit.results.Result(times, states, metadata=<factory>, units=<factory>, unit_system=None, arrays=<factory>)[source]#

Bases: object

Time series or other array output, with metadata and units.

Parameters:

times (NDArray[Any] | None) – Sample times, shape (n,), or None for output with no time axis (an eigenvalue spectrum, say).
states (NDArray[Any]) – The main output array. When times is given, its first axis must have length n.
metadata (dict[str, Any]) – JSON-compatible information such as the integrator name, parameters and provenance. It must be JSON-compatible for physicskit.io.save() to store it.
units (dict[str, str]) – Maps an array name ("times", "states" or a key of arrays) to a dimension name from physicskit.units.DIMENSIONS. Arrays without an entry are treated as dimensionless or of unknown dimension, and convert() leaves them unchanged.
unit_system (UnitSystem | None) – The system the dimensioned arrays are expressed in. None means unspecified; physicskit.units.SI means SI.
arrays (dict[str, NDArray[Any]]) – Further named arrays, such as momenta, energies or a spatial grid.

Raises:

ValueError – If lengths disagree, an array name is reserved or invalid, or a units entry names an unknown array or dimension.

Examples

>>> r = Result([0.0, 0.5, 1.0], [[1.0], [0.5], [0.0]], arrays={"energy": [2.0, 2.0, 2.0]})
>>> r.names
['times', 'states', 'energy']
>>> r["energy"].shape
(3,)

arrays: dict[str, NDArray[Any]]#

convert(system)[source]#

Return a copy with every dimensioned array expressed in system.

Arrays listed in units are converted through SI; all other arrays and the metadata are copied unchanged.

Parameters:: system (UnitSystem) – Target unit system.
Return type:: Result
Returns:: Result
Raises:: ValueError – If units is non-empty but unit_system is None, or either system leaves a needed dimension undetermined.

Examples

>>> from physicskit.units import SI, statphys_units
>>> r = Result(None, [1.0, 2.0], units={"states": "temperature"}, unit_system=statphys_units(temperature_k=300.0))
>>> r.convert(SI).states
array([300., 600.])

metadata: dict[str, Any]#

property names: list[str]#

Names of all arrays held, in the order times, states, extras.

Returns:: list of str

states: NDArray[Any]#

times: NDArray[Any] | None#

to_si()[source]#

Return a copy with every dimensioned array in SI units.

Shorthand for convert(physicskit.units.SI).

Return type:: Result
Returns:: Result

unit_system: UnitSystem | None = None#

units: dict[str, str]#

physicskit.results.from_eigen_result(result, *, metadata=None, units=None, unit_system=None)[source]#

Wrap a quantum EigenResult.

There is no time axis. states holds the wavefunctions, shape (n_states, len(x)), and arrays holds x and energies.

Parameters:

result (Any) – Output of solve().
metadata (Mapping[str, Any] | None) – See from_integrator().
units (Mapping[str, str] | None) – See from_integrator().
unit_system (UnitSystem | None) – See from_integrator().

Return type:

Returns:

Result

Examples

>>> import numpy as np
>>> from physicskit.quantum.core.eigensolvers import NumerovSolver, infinite_well
>>> eig = NumerovSolver(np.linspace(0.0, 1.0, 201), infinite_well()).solve(n_states=3)
>>> r = from_eigen_result(eig)
>>> r.times is None, r.states.shape, r["energies"].shape
(True, (3, 201), (3,))

physicskit.results.from_integrator(output, *, method=None, metadata=None, units=None, unit_system=None)[source]#

Wrap the tuple returned by a physicskit.integrators function.

Accepts (times, states) from rk4_integrate(), dopri5_integrate() and the chaos flows’ trajectory() methods, or (times, positions, velocities) from leapfrog_integrate() and yoshida4_integrate(). For the latter, states is the phase-space trajectory [positions, velocities] stacked along the last axis, and the two halves are also kept as arrays["positions"] and arrays["velocities"].

Parameters:

output (Sequence[ArrayLike]) – The integrator’s return value.
method (str | None) – Integrator name, stored as metadata["method"].
metadata (Mapping[str, Any] | None) – Extra metadata, merged over the adapter’s own.
units (Mapping[str, str] | None) – See Result.
unit_system (UnitSystem | None) – See Result.

Return type:

Returns:

Result

Examples

>>> import numpy as np
>>> r = from_integrator((np.array([0.0, 0.1]), np.ones((2, 1)), np.zeros((2, 1))), method="leapfrog")
>>> r.states.shape, r.metadata["method"]
((2, 2), 'leapfrog')

physicskit.results.from_map_orbit(orbit, *, metadata=None, units=None, unit_system=None)[source]#

Wrap the orbit returned by a chaos map’s trajectory().

Maps are discrete, so times is the iteration index 0, 1, ... and metadata["time_kind"] is "iteration".

Parameters:

orbit (ArrayLike) – The map’s orbit.
metadata (Mapping[str, Any] | None) – See from_integrator().
units (Mapping[str, str] | None) – See from_integrator().
unit_system (UnitSystem | None) – See from_integrator().

Return type:

Returns:

Result

Examples

>>> from physicskit.chaos.systems.maps import LogisticMap
>>> r = from_map_orbit(LogisticMap(r=3.9).trajectory(n_iter=5))
>>> r.times
array([0, 1, 2, 3, 4, 5])

physicskit.results.from_simulation_result(result, *, metadata=None, units=None, unit_system=None)[source]#

Wrap a classical SimulationResult.

t becomes times and y becomes states. q, p and energy, when present, go to arrays. Entries of extra go to arrays if they are arrays and to metadata["extra"] otherwise; values that are not JSON scalars are stored as their repr.

Parameters:

result (Any) – Output of a classical system’s integrate().
metadata (Mapping[str, Any] | None) – See from_integrator().
units (Mapping[str, str] | None) – See from_integrator().
unit_system (UnitSystem | None) – See from_integrator().

Return type:

Returns:

Result

Examples

>>> from physicskit.classical.systems.hamiltonian import HenonHeilesSystem
>>> sim = HenonHeilesSystem(q0=[0.1, 0.0], p0=[0.0, 0.2]).integrate((0.0, 1.0), dt=0.01)
>>> r = from_simulation_result(sim)
>>> r.names, r.metadata["method"]
(['times', 'states', 'q', 'p', 'energy'], 'yoshida4')

physicskit.results.from_spectrum(spectrum, *, metadata=None)[source]#

Wrap an rmt Spectrum.

There is no time axis. states holds the raw eigenvalues, shape (n_samples, n). n, beta, ensemble and scale go to metadata, and eigenvectors (if sampled) to arrays. Random-matrix spectra are dimensionless, so no units are attached.

Parameters:

spectrum (Any) – Output of an ensemble’s sample().
metadata (Mapping[str, Any] | None) – Extra metadata, merged over the adapter’s own.

Return type:

Returns:

Result

Examples

>>> import physicskit.rmt as rmt
>>> r = from_spectrum(rmt.ensembles.GOE(n=4, seed=1).sample(n_samples=3))
>>> r.states.shape, r.metadata["ensemble"], r.metadata["beta"]
((3, 4), 'GOE', 1.0)

Save and load Result objects.

Two formats are supported, chosen by file extension:

.npz (NumPy’s zipped archive), always available. Loading never unpickles anything (allow_pickle=False), so a file from an untrusted source cannot execute code.
.h5 / .hdf5, when h5py is installed (pip install "physicskit[hdf5]"). Arrays become datasets that other HDF5 tools can read directly.

Both store the same thing: the times, states and extra arrays, plus a JSON header with the metadata, units, unit system and a format version. The metadata must therefore be JSON-compatible. NumPy scalars are converted to Python numbers, and tuples come back as lists.

Examples

>>> import numpy as np, tempfile, pathlib
>>> from physicskit.results import Result
>>> from physicskit.io import save, load
>>> r = Result(np.linspace(0, 1, 5), np.eye(5), metadata={"method": "rk4"})
>>> with tempfile.TemporaryDirectory() as d:
...     back = load(save(r, pathlib.Path(d) / "run.npz"))
>>> back.metadata["method"], np.array_equal(back.states, r.states)
('rk4', True)

physicskit.io.FORMAT_VERSION = 1#: Version of the on-disk layout written by save(). load() refuses files written by a newer version.

physicskit.io.load(path, *, format=None)[source]#

Read a Result written by save().

Parameters:

path (str | PathLike[str]) – File to read.
format (str | None) – Explicit format, overriding the extension.

Return type: