Metadata-Version: 2.4
Name: peritheos
Version: 0.5.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: Documentation, https://peritheos.readthedocs.io/
Project-URL: Source, https://github.com/cprescher/peritheos
Project-URL: Bug Tracker, https://github.com/cprescher/peritheos/issues
Project-URL: Changelog, https://github.com/cprescher/peritheos/blob/main/CHANGELOG.md
Keywords: equation-of-state,high-pressure,thermodynamics
Classifier: Development Status :: 4 - Beta
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.21.0
Requires-Dist: scipy>=1.9.3
Dynamic: license-file

# Peritheos

A Python library for thermodynamic equations of state calculations for solid materials.

Full model, fitting, units, and development documentation is available at
[peritheos.readthedocs.io](https://peritheos.readthedocs.io/).
Release history is recorded in the [changelog](CHANGELOG.md).

## Features

- Room temperature equations of state (EOS) implementations
  - Birch-Murnaghan
  - Murnaghan
  - Natural strain (orders 2-4)
  - Modified Tait
  - Vinet
  - Holzapfel
- Thermal equations of state (EOS) implementations
  - Mie-Gruneisen-Debye
  - Mie-Gruneisen-Einstein
  - Holland-Powell thermal modified Tait
  - Sokolova 2016, including its complete thermal-pressure parameter set
- P-V and P-V-T parameter fitting with covariance and diagnostics
- Joint reference-isotherm and thermal fitting with cross-covariance
- Correlated observation errors and robust least-squares losses
- Reproducible fit summaries and versioned JSON export
- EOS prediction uncertainty from fitted covariance or published parameter errors
- Thermoelastic derivatives, heat capacities, and vibrational potentials

## Unit conventions

- Public pressure and bulk-modulus values are in GPa.
- Temperatures are in K.
- Birch-Murnaghan, Murnaghan, modified Tait, and Vinet accept any consistent
  volume unit.
- Holzapfel and all thermal EOS implementations require molar volume in
  J bar^-1 mol^-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

Mie-Gruneisen-Debye and Mie-Gruneisen-Einstein models can wrap any of the
room-temperature equations of state:

```python
from peritheos.eos.rt import BM3
from peritheos.eos.thermal import MieGruneisenDebye

# Thermal models require molar volume in J bar^-1 mol^-1.
rt_eos = BM3(V0=1.0, K0=160.0, K0_prime=4.0)
eos = MieGruneisenDebye(
    rt_eos=rt_eos,
    Tr=300.0,
    theta0=800.0,
    gamma0=1.5,
    q=1.0,
    n=2,
)

pressure = eos.pressure(V=0.9, T=2000.0)
volume = eos.volume(P=pressure, T=2000.0)
temperature = eos.temperature(P=pressure, V=0.9)

# Infer temperature from volumes measured before and during DAC heating.
ambient_volume = 0.80000
heated_volume = 0.80001
temperature_with_dac = eos.temperature_from_volumes(
    V_ambient=ambient_volume,
    V_heated=heated_volume,
    f_dac=0.25,
)
ambient_pressure = eos.rt_eos.pressure(ambient_volume)
heated_pressure = ambient_pressure + 0.25 * eos.thermal_pressure(
    heated_volume, temperature_with_dac
)
```

The two-volume method uses the empirical `f_dac * thermal_pressure` confinement
increment and requires `0 <= f_dac < 1`; report and sensitivity-test the assumed
fraction.

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)
recovered_temperature = sokolova.temperature(pressure, V)

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")
print(f"Recovered temperature: {recovered_temperature} K")
```

## Citation and support

Use the repository's `CITATION.cff` to cite Peritheos and cite the original
publication for each EOS used. Reproducible bugs and numerical discrepancies
can be reported through [GitHub Issues](https://github.com/CPrescher/peritheos/issues).
See [SUPPORT.md](SUPPORT.md) for the information needed to investigate a result.
