peritheos 0.1.0__tar.gz

peritheos-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clemens Prescher
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

peritheos-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: peritheos
+Version: 0.1.0
+Summary: A library for thermodynamic equations of state calculations
+Author-email: Clemens Prescher <clemens.prescher@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/cprescher/peritheos
+Project-URL: Bug Tracker, https://github.com/cprescher/peritheos/issues
+Keywords: equation-of-state,high-pressure,thermodynamics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: scipy>=1.7.0
+Dynamic: license-file
+
+# Peritheos
+
+A Python library for thermodynamic equations of state calculations for solid materials.
+
+## Features
+
+- Room temperature equations of state (EOS) implementations
+  - Birch-Murnaghan
+  - Vinet
+  - Holzapfel
+- Thermal equations of state (EOS) implementations
+  - Sokolova 2016
+
+## Unit conventions
+
+- Public pressure and bulk-modulus values are in GPa.
+- Temperatures are in K.
+- Birch-Murnaghan and Vinet accept any consistent volume unit.
+- Holzapfel and Sokolova 2016 require molar volume in J bar^-1, which is
+  equivalent to cm^3/mol divided by 10.
+
+## Installation
+
+```bash
+pip install peritheos
+```
+
+The latest development version can instead be installed directly from GitHub:
+
+```bash
+pip install git+https://github.com/CPrescher/peritheos.git
+```
+
+## Usage
+
+### Room-temperature equations of state
+
+Third-order Birch-Murnaghan equation of state:
+
+```python
+from peritheos.eos.rt import BM3
+
+# V0 may use any volume unit for a room-temperature EOS; K0 is in GPa here.
+eos = BM3(V0=50, K0=130, K0_prime=4.3)
+
+# Calculate pressure and bulk modulus at a given volume.
+pressure = eos.pressure(V=40)
+bulk_modulus = eos.bulk_modulus(V=40)
+
+# Invert the EOS to calculate volume at a given pressure.
+volume = eos.volume(P=pressure)
+
+print(f"Pressure: {pressure} GPa")
+print(f"Bulk modulus: {bulk_modulus} GPa")
+print(f"Recovered volume: {volume}")
+```
+
+### Thermal equations of state
+
+Diamond thermal equation of state from sokolova et al. 2016
+
+```python
+from peritheos.eos.rt.holzapfel import Holzapfel
+from peritheos.eos.thermal.sokolova2016 import Sokolova2016
+
+# Diamond parameters from Sokolova et al. 2016.
+# The thermal model requires molar volume in J bar^-1 (= [cm^3/mol] / 10),
+# pressure parameters in GPa, and temperatures in K.
+V0 = 0.3414
+K0 = 441.5
+K0_prime = 3.9  # pressure derivative of bulk modulus at reference volume
+QE1o = 684  # first Einstein characteristic temperature
+mE1 = 0.564  # first Einstein number
+QE2o = 1561  # second Einstein characteristic temperature
+mE2 = 2.436  # second Einstein number
+delta = -0.506  # additive normalizing constant for the Gruneisen parameter
+t = 1.085  # generalized Gruneisen parameter
+a_0 = 0  # intrinsic anharmonicity parameter
+m = 0  # anharmonic analogue of the Grüneisen parameter
+e_0 = 0  # free electrons parameter
+g = 0  # electronic analogue of the Grüneisen parameter
+
+n = 1  # number of atoms in the formula unit
+z = 6  # atomic number of the formula unit
+Tr = 298.15  # in K - Reference temperature
+
+# Initialize the Holzapfel EOS
+holzapfel = Holzapfel(V0=V0, K0=K0, K0_prime=K0_prime, n=n, Z=z)
+
+# Initialize the Sokolova 2016 EOS
+sokolova = Sokolova2016(
+    rt_eos=holzapfel,
+    Tr=Tr,
+    QE1o=QE1o,
+    mE1=mE1,
+    QE2o=QE2o,
+    mE2=mE2,
+    delta=delta,
+    t=t,
+    a_0=a_0,
+    m=m,
+    g=g,
+    e_0=e_0,
+)
+
+# Calculate the thermal pressure at a given volume and temperature
+V = V0 * 0.8
+T = 3000  # in K
+thermal_pressure = sokolova.thermal_pressure(V, T)
+rt_pressure = holzapfel.pressure(V)
+pressure = sokolova.pressure(V, T)
+recovered_volume = sokolova.volume(pressure, T)
+
+print(f"Thermal pressure: {thermal_pressure} GPa")
+print(f"RT pressure: {rt_pressure} GPa")
+print(f"Total pressure: {pressure} GPa")
+print(f"Recovered volume: {recovered_volume} J bar^-1")
+```

peritheos-0.1.0/README.md

@@ -0,0 +1,118 @@
+# Peritheos
+
+A Python library for thermodynamic equations of state calculations for solid materials.
+
+## Features
+
+- Room temperature equations of state (EOS) implementations
+  - Birch-Murnaghan
+  - Vinet
+  - Holzapfel
+- Thermal equations of state (EOS) implementations
+  - Sokolova 2016
+
+## Unit conventions
+
+- Public pressure and bulk-modulus values are in GPa.
+- Temperatures are in K.
+- Birch-Murnaghan and Vinet accept any consistent volume unit.
+- Holzapfel and Sokolova 2016 require molar volume in J bar^-1, which is
+  equivalent to cm^3/mol divided by 10.
+
+## Installation
+
+```bash
+pip install peritheos
+```
+
+The latest development version can instead be installed directly from GitHub:
+
+```bash
+pip install git+https://github.com/CPrescher/peritheos.git
+```
+
+## Usage
+
+### Room-temperature equations of state
+
+Third-order Birch-Murnaghan equation of state:
+
+```python
+from peritheos.eos.rt import BM3
+
+# V0 may use any volume unit for a room-temperature EOS; K0 is in GPa here.
+eos = BM3(V0=50, K0=130, K0_prime=4.3)
+
+# Calculate pressure and bulk modulus at a given volume.
+pressure = eos.pressure(V=40)
+bulk_modulus = eos.bulk_modulus(V=40)
+
+# Invert the EOS to calculate volume at a given pressure.
+volume = eos.volume(P=pressure)
+
+print(f"Pressure: {pressure} GPa")
+print(f"Bulk modulus: {bulk_modulus} GPa")
+print(f"Recovered volume: {volume}")
+```
+
+### Thermal equations of state
+
+Diamond thermal equation of state from sokolova et al. 2016
+
+```python
+from peritheos.eos.rt.holzapfel import Holzapfel
+from peritheos.eos.thermal.sokolova2016 import Sokolova2016
+
+# Diamond parameters from Sokolova et al. 2016.
+# The thermal model requires molar volume in J bar^-1 (= [cm^3/mol] / 10),
+# pressure parameters in GPa, and temperatures in K.
+V0 = 0.3414
+K0 = 441.5
+K0_prime = 3.9  # pressure derivative of bulk modulus at reference volume
+QE1o = 684  # first Einstein characteristic temperature
+mE1 = 0.564  # first Einstein number
+QE2o = 1561  # second Einstein characteristic temperature
+mE2 = 2.436  # second Einstein number
+delta = -0.506  # additive normalizing constant for the Gruneisen parameter
+t = 1.085  # generalized Gruneisen parameter
+a_0 = 0  # intrinsic anharmonicity parameter
+m = 0  # anharmonic analogue of the Grüneisen parameter
+e_0 = 0  # free electrons parameter
+g = 0  # electronic analogue of the Grüneisen parameter
+
+n = 1  # number of atoms in the formula unit
+z = 6  # atomic number of the formula unit
+Tr = 298.15  # in K - Reference temperature
+
+# Initialize the Holzapfel EOS
+holzapfel = Holzapfel(V0=V0, K0=K0, K0_prime=K0_prime, n=n, Z=z)
+
+# Initialize the Sokolova 2016 EOS
+sokolova = Sokolova2016(
+    rt_eos=holzapfel,
+    Tr=Tr,
+    QE1o=QE1o,
+    mE1=mE1,
+    QE2o=QE2o,
+    mE2=mE2,
+    delta=delta,
+    t=t,
+    a_0=a_0,
+    m=m,
+    g=g,
+    e_0=e_0,
+)
+
+# Calculate the thermal pressure at a given volume and temperature
+V = V0 * 0.8
+T = 3000  # in K
+thermal_pressure = sokolova.thermal_pressure(V, T)
+rt_pressure = holzapfel.pressure(V)
+pressure = sokolova.pressure(V, T)
+recovered_volume = sokolova.volume(pressure, T)
+
+print(f"Thermal pressure: {thermal_pressure} GPa")
+print(f"RT pressure: {rt_pressure} GPa")
+print(f"Total pressure: {pressure} GPa")
+print(f"Recovered volume: {recovered_volume} J bar^-1")
+```

peritheos-0.1.0/peritheos/__init__.py

@@ -0,0 +1,3 @@
+"""Peritheos: thermodynamic equations of state calculations."""
+
+__version__ = "0.1.0"

peritheos-0.1.0/peritheos/constants.py

@@ -0,0 +1,22 @@
+"""
+Physical constants used in thermodynamic calculations
+"""
+
+from scipy import constants
+
+# Universal gas constant (J/(mol·K))
+R = constants.R
+
+# Boltzmann constant (J/K)
+k_B = constants.Boltzmann
+
+# Avogadro's number (1/mol)
+N_A = constants.Avogadro
+
+# Standard temperature and pressure
+STP_TEMPERATURE = constants.zero_Celsius  # K (273.15)
+STP_PRESSURE = constants.atm  # Pa (101325.0)
+
+# Other useful constants
+STANDARD_GRAVITY = constants.g  # m/s²
+STEFAN_BOLTZMANN = constants.Stefan_Boltzmann  # W/(m²·K⁴) 

peritheos-0.1.0/peritheos/eos/__init__.py

@@ -0,0 +1,234 @@
+"""
+Equations of state module for Peritheos
+"""
+
+from typing import Callable, Union
+import numpy as np
+from numpy.typing import NDArray
+from scipy import optimize
+
+# Type alias for numeric values (scalar or array)
+NumericType = Union[float, NDArray[np.float64]]
+
+
+def validate_finite_scalar(value: float, name: str) -> float:
+    """Return *value* as a finite float or raise a descriptive error."""
+    value = float(value)
+    if not np.isfinite(value):
+        raise ValueError(f"{name} must be finite")
+    return value
+
+
+def validate_positive_scalar(value: float, name: str) -> float:
+    """Return *value* as a positive finite float."""
+    value = validate_finite_scalar(value, name)
+    if value <= 0:
+        raise ValueError(f"{name} must be greater than zero")
+    return value
+
+
+def validate_volume(V: NumericType) -> NumericType:
+    """Validate volume input while preserving scalar or array behaviour."""
+    values = np.asarray(V, dtype=float)
+    if not np.all(np.isfinite(values)):
+        raise ValueError("Volume must be finite")
+    if np.any(values <= 0):
+        raise ValueError("Volume must be greater than zero")
+    if values.ndim == 0:
+        return float(values)
+    return values
+
+
+def _scalar_pressure(pressure_function: Callable[[float], NumericType], V: float) -> float:
+    """Evaluate a pressure callable and require a finite scalar result."""
+    pressure = np.asarray(pressure_function(V), dtype=float)
+    if pressure.ndim != 0:
+        raise TypeError("The pressure function must return a scalar for scalar volume")
+    result = float(pressure)
+    if not np.isfinite(result):
+        raise ArithmeticError(f"EOS returned a non-finite pressure at V={V}")
+    return result
+
+
+def solve_volume(
+    pressure_function: Callable[[float], NumericType],
+    pressure: float,
+    reference_volume: float,
+) -> float:
+    """Solve ``pressure_function(V) == pressure`` on the branch nearest V0.
+
+    The EOS is assumed to be locally monotonic around its reference volume:
+    pressure increases on compression and decreases on expansion. Starting at
+    ``V0``, the search geometrically decreases volume for a higher target
+    pressure or increases it for a lower target pressure until the pressure
+    residual changes sign. ``scipy.optimize.brentq`` then solves inside that
+    positive-volume bracket. If no sign change is found, the requested state is
+    reported as outside the model's invertible range.
+    """
+    target = validate_finite_scalar(pressure, "Pressure")
+    V0 = validate_positive_scalar(reference_volume, "Reference volume")
+    p0 = _scalar_pressure(pressure_function, V0)
+    f0 = p0 - target
+    pressure_tolerance = 1e-10 * max(1.0, abs(target), abs(p0))
+    if abs(f0) <= pressure_tolerance:
+        return V0
+
+    if f0 < 0:
+        # The target is above P(V0), so search towards compression.
+        upper, f_upper = V0, f0
+        lower = V0
+        f_lower = f0
+        for _ in range(160):
+            lower *= 0.8
+            if lower <= V0 * 1e-14:
+                break
+            f_lower = _scalar_pressure(pressure_function, lower) - target
+            if f_lower >= 0:
+                break
+        else:
+            f_lower = np.nan
+        if not np.isfinite(f_lower) or f_lower < 0:
+            raise ValueError(
+                f"Could not bracket a positive volume for pressure {target}"
+            )
+    else:
+        # The target is below P(V0), so search along the first expansion branch.
+        lower, f_lower = V0, f0
+        upper = V0
+        f_upper = f0
+        for _ in range(160):
+            upper *= 1.05
+            if upper >= V0 * 1e4:
+                break
+            f_upper = _scalar_pressure(pressure_function, upper) - target
+            if f_upper <= 0:
+                break
+        else:
+            f_upper = np.nan
+        if not np.isfinite(f_upper) or f_upper > 0:
+            raise ValueError(
+                f"Pressure {target} is outside the invertible expansion range"
+            )
+
+    result = optimize.brentq(
+        lambda volume: _scalar_pressure(pressure_function, volume) - target,
+        lower,
+        upper,
+        xtol=max(np.finfo(float).eps * V0, 1e-14),
+        rtol=1e-12,
+    )
+    residual = abs(_scalar_pressure(pressure_function, result) - target)
+    if residual > 1e-8 * max(1.0, abs(target)):
+        raise ArithmeticError(
+            f"Volume inversion did not converge to the requested pressure; residual={residual}"
+        )
+    return float(result)
+
+
+class EosBase:
+    """
+    Base class for equation of state implementations.
+
+    This abstract class defines the interface that all equation of state
+    implementations should follow.
+    """
+
+    def pressure(self, V: NumericType) -> NumericType:
+        """
+        Calculate pressure at a given volume.
+
+        Parameters
+        ----------
+        V : float or numpy.ndarray
+            Volume (in cubic angstroms or any consistent unit)
+
+        Returns
+        -------
+        float or numpy.ndarray
+            Pressure (in the same units as K0)
+        """
+        raise NotImplementedError("Subclasses must implement the pressure method.")
+
+    def bulk_modulus(self, V: NumericType) -> NumericType:
+        """
+        Calculate the bulk modulus.
+
+        Parameters
+        ----------
+        V : float or numpy.ndarray
+            Volume (in cubic angstroms or any consistent unit)
+
+        Returns
+        -------
+        float or numpy.ndarray
+            Bulk modulus (in the same units as K0)
+        """
+        raise NotImplementedError("Subclasses must implement the bulk_modulus method.")
+
+    def calculate_volume(self, P: NumericType) -> NumericType:
+        """
+        Calculate volume at a given pressure using a bracketed root solver.
+
+        Parameters
+        ----------
+        P : float or numpy.ndarray
+            Pressure (in the same units as K0)
+
+        Returns
+        -------
+        float or numpy.ndarray
+            Volume (in the same units as V0)
+        """
+        pressures = np.asarray(P, dtype=float)
+        if not np.all(np.isfinite(pressures)):
+            raise ValueError("Pressure must be finite")
+        if pressures.ndim == 0:
+            return solve_volume(self.pressure, float(pressures), self.V0)
+        return np.array(
+            [solve_volume(self.pressure, value, self.V0) for value in pressures.flat]
+        ).reshape(pressures.shape)
+
+    def volume(self, P: NumericType) -> NumericType:
+        """Alias for :meth:`calculate_volume` using the P-to-V terminology."""
+        return self.calculate_volume(P)
+
+
+class ThermalEOS(EosBase):
+    def __init__(self, rt_eos: EosBase):
+        self.rt_eos = rt_eos
+
+    def thermal_pressure(self, V: NumericType, T: NumericType) -> NumericType:
+        raise NotImplementedError("This method should be implemented by the subclass")
+
+    def pressure(self, V: NumericType, T: NumericType) -> NumericType:
+        return self.thermal_pressure(V, T) + self.rt_eos.pressure(V)
+
+    def calculate_volume(self, P: NumericType, T: NumericType) -> NumericType:
+        """Calculate volume at pressure and temperature using bracketed roots."""
+        pressures, temperatures = np.broadcast_arrays(
+            np.asarray(P, dtype=float), np.asarray(T, dtype=float)
+        )
+        if not np.all(np.isfinite(pressures)):
+            raise ValueError("Pressure must be finite")
+        if not np.all(np.isfinite(temperatures)) or np.any(temperatures <= 0):
+            raise ValueError("Temperature must be finite and greater than zero")
+
+        volumes = np.array(
+            [
+                solve_volume(
+                    lambda volume, temperature=float(temperature): self.pressure(
+                        volume, temperature
+                    ),
+                    float(pressure),
+                    self.rt_eos.V0,
+                )
+                for pressure, temperature in zip(pressures.flat, temperatures.flat)
+            ]
+        ).reshape(pressures.shape)
+        if volumes.ndim == 0:
+            return float(volumes)
+        return volumes
+
+    def volume(self, P: NumericType, T: NumericType) -> NumericType:
+        """Alias for :meth:`calculate_volume` for a thermal EOS."""
+        return self.calculate_volume(P, T)