Skip to content

cds2.scientific

Physical constants and classical/modern physics formula helpers.

Physical constants and formulas — CDS-native, not a wrapper (CODATA).

speed_of_light()

Speed of light in vacuum, m/s.

Source code in src/cds2/scientific.py 
46
47
48
def speed_of_light() -> float:
    """Speed of light in vacuum, m/s."""
    return CONSTANTS["c"]

planck_constant()

Planck constant, J*s.

Source code in src/cds2/scientific.py 
51
52
53
def planck_constant() -> float:
    """Planck constant, J*s."""
    return CONSTANTS["h"]

boltzmann_constant()

Boltzmann constant, J/K.

Source code in src/cds2/scientific.py 
56
57
58
def boltzmann_constant() -> float:
    """Boltzmann constant, J/K."""
    return CONSTANTS["k_B"]

gravitational_constant()

Newtonian constant of gravitation.

Source code in src/cds2/scientific.py 
61
62
63
def gravitational_constant() -> float:
    """Newtonian constant of gravitation."""
    return CONSTANTS["G"]

elementary_charge()

Elementary charge, C.

Source code in src/cds2/scientific.py 
66
67
68
def elementary_charge() -> float:
    """Elementary charge, C."""
    return CONSTANTS["e"]

avogadro_number()

Avogadro constant, 1/mol.

Source code in src/cds2/scientific.py 
71
72
73
def avogadro_number() -> float:
    """Avogadro constant, 1/mol."""
    return CONSTANTS["N_A"]

vacuum_permittivity()

Vacuum electric permittivity, F/m.

Source code in src/cds2/scientific.py 
76
77
78
def vacuum_permittivity() -> float:
    """Vacuum electric permittivity, F/m."""
    return CONSTANTS["epsilon_0"]

vacuum_permeability()

Vacuum magnetic permeability, H/m.

Source code in src/cds2/scientific.py 
81
82
83
def vacuum_permeability() -> float:
    """Vacuum magnetic permeability, H/m."""
    return CONSTANTS["mu_0"]

standard_gravity()

Standard Earth gravity, m/s^2.

Source code in src/cds2/scientific.py 
86
87
88
def standard_gravity() -> float:
    """Standard Earth gravity, m/s^2."""
    return CONSTANTS["g"]

kinetic_energy(mass, velocity)

Classical kinetic energy, J.

Source code in src/cds2/scientific.py 
91
92
93
94
95
96
def kinetic_energy(mass: float, velocity: float) -> float:
    """Classical kinetic energy, J."""
    if mass < 0:
        msg = "mass cannot be negative"
        raise ValueError(msg)
    return 0.5 * mass * velocity**2

gravitational_force(mass_a, mass_b, distance)

Newtonian gravitational attraction between two point masses, N.

Source code in src/cds2/scientific.py 
 99
100
101
102
103
104
def gravitational_force(mass_a: float, mass_b: float, distance: float) -> float:
    """Newtonian gravitational attraction between two point masses, N."""
    if distance <= 0:
        msg = "distance must be positive"
        raise ValueError(msg)
    return CONSTANTS["G"] * mass_a * mass_b / distance**2

coulomb_force(charge_a, charge_b, distance)

Electrostatic force between two point charges, N (signed).

Source code in src/cds2/scientific.py 
107
108
109
110
111
112
def coulomb_force(charge_a: float, charge_b: float, distance: float) -> float:
    """Electrostatic force between two point charges, N (signed)."""
    if distance <= 0:
        msg = "distance must be positive"
        raise ValueError(msg)
    return charge_a * charge_b / (4.0 * math.pi * CONSTANTS["epsilon_0"] * distance**2)

photon_energy(wavelength_m)

Energy of a photon from its vacuum wavelength, J.

Source code in src/cds2/scientific.py 
115
116
117
118
119
120
def photon_energy(wavelength_m: float) -> float:
    """Energy of a photon from its vacuum wavelength, J."""
    if wavelength_m <= 0:
        msg = "wavelength must be positive"
        raise ValueError(msg)
    return CONSTANTS["h"] * CONSTANTS["c"] / wavelength_m

de_broglie_wavelength(mass, velocity)

Matter wavelength of a moving particle, m.

Source code in src/cds2/scientific.py 
123
124
125
126
127
128
def de_broglie_wavelength(mass: float, velocity: float) -> float:
    """Matter wavelength of a moving particle, m."""
    if mass <= 0:
        msg = "mass must be positive"
        raise ValueError(msg)
    return CONSTANTS["h"] / (mass * abs(velocity))

lorentz_factor(velocity)

Special-relativistic gamma for a speed in m/s.

Source code in src/cds2/scientific.py 
131
132
133
134
135
136
137
def lorentz_factor(velocity: float) -> float:
    """Special-relativistic gamma for a speed in m/s."""
    ratio = abs(velocity) / CONSTANTS["c"]
    if ratio >= 1.0:
        msg = "speed must be below the speed of light"
        raise ValueError(msg)
    return 1.0 / math.sqrt(1.0 - ratio * ratio)

ideal_gas_pressure(moles, temperature_k, volume_m3)

Ideal gas law pressure, Pa (moles in mol, converted via Avogadro).

Source code in src/cds2/scientific.py 
140
141
142
143
144
145
146
147
148
149
def ideal_gas_pressure(moles: float, temperature_k: float, volume_m3: float) -> float:
    """Ideal gas law pressure, Pa (``moles`` in mol, converted via Avogadro)."""
    if volume_m3 <= 0:
        msg = "volume must be positive"
        raise ValueError(msg)
    if temperature_k <= 0:
        msg = "temperature must be positive"
        raise ValueError(msg)
    molecule_count = moles * CONSTANTS["N_A"]
    return molecule_count * CONSTANTS["k_B"] * temperature_k / volume_m3

escape_velocity(mass_kg, radius_m)

Escape velocity from a spherical body, m/s.

Source code in src/cds2/scientific.py 
152
153
154
155
156
157
def escape_velocity(mass_kg: float, radius_m: float) -> float:
    """Escape velocity from a spherical body, m/s."""
    if mass_kg <= 0 or radius_m <= 0:
        msg = "mass and radius must be positive"
        raise ValueError(msg)
    return math.sqrt(2.0 * CONSTANTS["G"] * mass_kg / radius_m)

list_units()

All supported unit symbols, including the three temperatures.

Source code in src/cds2/scientific.py 
217
218
219
def list_units() -> list[str]:
    """All supported unit symbols, including the three temperatures."""
    return sorted([*UNIT_FACTORS.keys(), *TEMPERATURE_UNITS])

convert_units(value, from_unit, to_unit)

Convert value between supported units of one physical dimension.

Covers length, mass, time, energy, pressure and angle via UNIT_FACTORS plus temperatures in C/F/K. Mixing dimensions raises ValueError.

Source code in src/cds2/scientific.py 
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
def convert_units(value: float, from_unit: str, to_unit: str) -> float:
    """Convert ``value`` between supported units of one physical dimension.

    Covers length, mass, time, energy, pressure and angle via ``UNIT_FACTORS``
    plus temperatures in C/F/K. Mixing dimensions raises ``ValueError``.
    """
    source = from_unit.strip()
    target = to_unit.strip()
    source_is_temp = source in TEMPERATURE_UNITS
    target_is_temp = target in TEMPERATURE_UNITS
    if source not in UNIT_FACTORS and not source_is_temp:
        msg = f"unknown unit: {source!r}"
        raise ValueError(msg)
    if target not in UNIT_FACTORS and not target_is_temp:
        msg = f"unknown unit: {target!r}"
        raise ValueError(msg)
    if source_is_temp != target_is_temp:
        msg = (
            f"cannot convert between temperature and non-temperature units ({source!r}, {target!r})"
        )
        raise ValueError(msg)
    if source_is_temp:
        return _from_kelvin(_to_kelvin(value, source), target)
    if UNIT_DIMENSIONS[source] != UNIT_DIMENSIONS[target]:
        msg = (
            f"cannot convert {UNIT_DIMENSIONS[source]} ({source!r}) to "
            f"{UNIT_DIMENSIONS[target]} ({target!r})"
        )
        raise ValueError(msg)
    base_value = value * UNIT_FACTORS[source]
    return base_value / UNIT_FACTORS[target]