peritheos 0.4.0__tar.gz → 0.5.0__tar.gz

{peritheos-0.4.0 → peritheos-0.5.0}/CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to Peritheos are documented here. The project follows
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-08-30
+
+### Added
+
+- A comprehensive equation reference for every public isothermal and thermal
+  EOS, including parameter definitions, model domains, numerical inversion,
+  thermoelastic identities, fitting diagnostics, uncertainty propagation, and
+  explicit public-unit conversion factors.
+- Documentation distinguishing the equations typeset in Sokolova et al. (2016)
+  from the accompanying Excel workbook calculation implemented by
+  `Sokolova2016`, including differences in the bulk-modulus derivative,
+  characteristic-temperature multiplier, oscillator pressure contributions,
+  reference-isotherm subtraction, and working pressure units.
+- Temperature inversion from pressure and volume for all thermal EOS models,
+  including NumPy broadcasting through `temperature()` and
+  `calculate_temperature()`.
+- Coupled temperature inference from ambient and heated volumes with a
+  fractional DAC confinement contribution through `temperature_from_volumes()`.
+  The empirical `f_dac * thermal_pressure` pressure increment is solved in its
+  algebraically reduced form and requires `0 <= f_dac < 1`.
+  Documentation distinguishes this fraction of EOS thermal pressure from a
+  fraction of cold pressure and describes its physical limits, calibration,
+  identifiability, baseline-drift, and uncertainty constraints.
+- Fixed-volume preparation for temperature inversion, avoiding repeated
+  Sokolova volume-integral evaluations during root finding.
+
+### Changed
+
+- Refreshed the locked runtime, development, documentation, and release
+  dependencies to their latest versions compatible with the supported Python
+  and declared package-version ranges.
+- The minimum supported SciPy version is now 1.9.3, ensuring a stable binary
+  installation and numerical fitting path on Python 3.9 across supported
+  platforms.
+- Documentation now uses Material for MkDocs with responsive navigation,
+  improved search and code presentation, and automatic light and dark themes.
+- The model overview now focuses on model selection and reference-EOS
+  compatibility, while advanced two-volume DAC analysis has moved out of the
+  introductory tutorial into a dedicated guide.
+
 ## [0.4.0] - 2026-08-09
 
 ### Added
@@ -102,7 +142,8 @@ All notable changes to Peritheos are documented here. The project follows
   and out-of-domain states.
 - Project naming and release metadata were standardized.
 
-[Unreleased]: https://github.com/CPrescher/peritheos/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/CPrescher/peritheos/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/CPrescher/peritheos/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/CPrescher/peritheos/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/CPrescher/peritheos/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/CPrescher/peritheos/releases/tag/v0.2.0

{peritheos-0.4.0 → peritheos-0.5.0}/CITATION.cff

@@ -4,8 +4,8 @@ message: >-
   original references for the equation-of-state models you use.
 title: Peritheos
 type: software
-version: 0.4.0
-date-released: 2026-08-09
+version: 0.5.0
+date-released: 2026-08-30
 authors:
   - family-names: Prescher
     given-names: Clemens

{peritheos-0.4.0 → peritheos-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: peritheos
-Version: 0.4.0
+Version: 0.5.0
 Summary: A library for thermodynamic equations of state calculations
 Author-email: Clemens Prescher <clemens.prescher@gmail.com>
 License-Expression: MIT
@@ -25,7 +25,7 @@ Requires-Python: >=3.9
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.21.0
-Requires-Dist: scipy>=1.7.0
+Requires-Dist: scipy>=1.9.3
 Dynamic: license-file
 
 # Peritheos
@@ -124,8 +124,26 @@ eos = MieGruneisenDebye(
 
 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
@@ -179,11 +197,13 @@ 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

{peritheos-0.4.0 → peritheos-0.5.0}/README.md

@@ -94,8 +94,26 @@ eos = MieGruneisenDebye(
 
 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
@@ -149,11 +167,13 @@ 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

{peritheos-0.4.0 → peritheos-0.5.0}/docs/api-stability.md

@@ -24,6 +24,10 @@ the API reference, and exact optimizer messages are private.
 a supported compatibility alias and will remain available throughout the 1.x
 series.
 
+`temperature()` is the preferred pressure-and-volume-to-temperature method.
+`calculate_temperature()` is its supported compatibility alias and will remain
+available throughout the 1.x series.
+
 After 1.0, planned public API removals will normally emit
 `DeprecationWarning` for at least two minor releases. Scientific corrections
 that cannot preserve old behavior will include a reproducible before-and-after

{peritheos-0.4.0 → peritheos-0.5.0}/docs/api.md

@@ -23,6 +23,25 @@ Common methods:
 - `bulk_modulus(V)`
 - `volume(P)` and `calculate_volume(P)`
 
+Constructor signatures and special requirements are:
+
+| Class | Signature after class name | Special requirement |
+|---|---|---|
+| `BM2` | `(V0, K0)` | $K_0'=4$ is implied |
+| `BM3` | `(V0, K0, K0_prime)` | none |
+| `BM4` | `(V0, K0, K0_prime, K0_double_prime)` | `K0_double_prime` has inverse-pressure units |
+| `Murnaghan` | `(V0, K0, K0_prime)` | supports the `K0_prime=0` limit |
+| `NaturalStrain2` | `(V0, K0)` | $K_0'=2$ is implied |
+| `NaturalStrain3` | `(V0, K0, K0_prime)` | none |
+| `NaturalStrain4` | `(V0, K0, K0_prime, K0_double_prime)` | `K0_double_prime` has inverse-pressure units |
+| `ModifiedTait` | `(V0, K0, K0_prime, K0_double_prime)` | rejects singular coefficient sets and volumes outside its real domain |
+| `Vinet` | `(V0, K0, K0_prime)` | none |
+| `Holzapfel` | `(V0, K0, K0_prime, n, Z)` | molar volume in `J bar^-1 mol^-1` |
+
+`Holzapfel` additionally provides `bulk_modulus_derivative(V, eps=1e-6)`.
+See the [equation reference](equation-reference.md#isothermal-equations) for
+the mathematical definitions and coefficient domains.
+
 ## Thermal equations of state
 
 ```python
@@ -35,11 +54,29 @@ from peritheos.eos.thermal import (
 )
 ```
 
+Thermal constructor signatures are:
+
+| Class | Parameters after `rt_eos` |
+|---|---|
+| `MieGruneisenDebye` | `Tr, theta0, gamma0, q, n` |
+| `MieGruneisenEinstein` | `Tr, theta0, gamma0, q, n` |
+| `ThermalModifiedTait` | `Tr, theta, alpha0, n` |
+| `Sokolova2016` | `Tr, QE1o, mE1, QE2o, mE2, delta, t, a_0, m, g, e_0`, followed by optional `beta, QBo, d, mb, QB1o, d1, mb1` |
+
+The Mie-Gruneisen classes accept any `EosBase` reference; thermal modified Tait
+requires `ModifiedTait`, and Sokolova requires `Holzapfel`. All thermal classes
+require molar volume in `J bar^-1 mol^-1`. `HollandPowell2011` is an alias for
+`ThermalModifiedTait`. Exact equations and parameter roles are documented
+under [Thermal equations](equation-reference.md#thermal-equations).
+
 Common methods:
 
 - `thermal_pressure(V, T)`
+- `dac_thermal_pressure(V, T, f_dac)`
 - `pressure(V, T)`
 - `volume(P, T)`
+- `temperature(P, V)` and `calculate_temperature(P, V)`
+- `temperature_from_volumes(V_ambient, V_heated, f_dac=...)`
 - `bulk_modulus(V, T)`
 - `isothermal_compressibility(V, T)`
 - `thermal_expansivity(V, T)`
@@ -48,6 +85,14 @@ Common methods:
 - `adiabatic_bulk_modulus(V, T)` when a caloric model exists
 - `gruneisen_parameter(V, T)` when a caloric model exists
 
+`dac_thermal_pressure()` returns only the additional confinement term
+`f_dac * thermal_pressure(V, T)`. `temperature_from_volumes()` applies the
+empirical confinement model described in
+[Diamond-anvil-cell thermal-pressure contribution](dac-thermal-pressure.md);
+it requires `0 <= f_dac < 1`. In this API, `f_dac` means
+`(P_hot - P_ambient) / thermal_pressure(V_heated, T)`; it is not a fraction of
+the cold pressure.
+
 Mie-Gruneisen models additionally expose `gruneisen_parameter()`,
 `characteristic_temperature()`, and the vibrational thermodynamic methods
 documented under [Thermoelastic properties](thermoelastic-properties.md).

peritheos-0.5.0/docs/dac-thermal-pressure.md

@@ -0,0 +1,134 @@
+# Diamond-anvil-cell thermal-pressure contribution
+
+This advanced workflow estimates temperature from separate volumes measured at
+the reference temperature and during laser heating. It introduces an
+experiment-specific boundary-condition parameter and should only be used when
+the total high-temperature pressure is not measured independently. Review the
+[thermal model](models.md#thermal-models), [unit](units.md), and
+[uncertainty](uncertainty.md) conventions before applying it.
+
+## Two-volume temperature inversion
+
+The ambient pressure is calculated from the volume measured at the reference
+temperature. A second volume is measured during heating. The two-volume
+temperature inversion solves
+
+\[
+\begin{aligned}
+P_{\mathrm{ambient}} &= P_{\mathrm{cold}}(V_{\mathrm{ambient}}), \\
+P_{\mathrm{EOS}}(V_{\mathrm{heated}}, T)
+&= P_{\mathrm{ambient}}
+   + f_{\mathrm{DAC}}\,\Delta P_{\mathrm{thermal}}(V_{\mathrm{heated}}, T).
+\end{aligned}
+\]
+
+Because `P_EOS = P_cold + Delta P_thermal`, this reduces exactly to
+
+\[
+\Delta P_{\mathrm{thermal}}(V_{\mathrm{heated}}, T)
+= \frac{P_{\mathrm{cold}}(V_{\mathrm{ambient}})
+       - P_{\mathrm{cold}}(V_{\mathrm{heated}})}
+      {1-f_{\mathrm{DAC}}}.
+\]
+
+The implementation solves this reduced equation directly. This avoids
+re-evaluating both sides of the original expression and makes the domain clear:
+for the usual positive, monotonic thermal-pressure models, a heated state needs
+the heated volume to have the larger cold-compression pressure.
+
+Here `f_dac` is defined specifically as the fraction of the EOS thermal pressure
+that appears as an increase above the reference-temperature pressure:
+
+\[
+\begin{aligned}
+\Delta P_{\mathrm{DAC}} &= P_{\mathrm{hot}} - P_{\mathrm{ambient}}, \\
+f_{\mathrm{DAC}} &=
+\frac{\Delta P_{\mathrm{DAC}}}
+     {\Delta P_{\mathrm{thermal}}(V_{\mathrm{heated}}, T)}.
+\end{aligned}
+\]
+
+It is not the ratio `Delta P_DAC / P_ambient` and therefore is not a percentage
+of the cold pressure.
+
+## Using the two-volume method
+
+```python
+f_dac = 0.25
+ambient_volume = 0.80000
+heated_volume = 0.80001
+corrected_temperature = eos.temperature_from_volumes(
+    ambient_volume,
+    heated_volume,
+    f_dac=f_dac,
+)
+ambient_pressure = eos.rt_eos.pressure(ambient_volume)
+thermal_pressure = eos.thermal_pressure(heated_volume, corrected_temperature)
+high_temperature_pressure = ambient_pressure + f_dac * thermal_pressure
+```
+
+If total high-temperature pressure is measured independently, use
+`temperature(P_hot, V_heated)` directly and do not apply the two-volume model.
+See the [thermal API reference](api.md#thermal-equations-of-state) for both
+inversion methods.
+
+## Physical interpretation and limits
+
+The two-volume inversion requires `0 <= f_dac < 1`:
+
+| `f_dac` | Boundary-condition interpretation | Consequence |
+|---:|---|---|
+| `0` | Isobaric heating | `P_hot = P_ambient` |
+| between `0` and `1` | Partial confinement | Some EOS thermal pressure raises the experimental pressure |
+| approaching `1` | Isochoric limit | `V_heated` approaches `V_ambient`; volume alone ceases to constrain temperature |
+
+This interpolation is physically consistent with the isobaric-to-isochoric
+range discussed by [Yen, Williams, and Kunz
+(2020)](https://doi.org/10.1029/2020JB020006). It remains an experimental
+boundary-condition model, not an additional term in the material EOS.
+
+The meaning of percentages in the DAC literature must be checked before using
+them as `f_dac`. [Heinz (1990)](https://doi.org/10.1029/GL017i008p01161)
+estimated roughly 40--60% of the constant-volume thermodynamic thermal pressure
+for a particular elastic hotspot model; this ratio is conceptually compatible
+with `f_dac`. In contrast, the approximately 30% result attributed to the
+Dewaele finite-element model by Yen et al. is a fraction of the *cold pressure*.
+That is a different denominator and cannot be entered as `f_dac=0.3` without an
+additional conversion.
+
+## Experimental cautions
+
+`f_dac` depends on the sample and pressure-medium strength, hotspot and sample
+geometry, temperature distribution, probe position, heating duration, and
+stress relaxation. It may vary spatially, with temperature, and between heating
+cycles. A literature value from a different assembly is therefore best treated
+as a sensitivity scenario rather than a calibrated correction.
+
+The two measured volumes cannot determine both temperature and `f_dac`.
+Assuming `f_dac` selects one temperature from a family of possible solutions.
+If an independent temperature is available, an experiment-specific fraction
+can instead be estimated from
+
+\[
+f_{\mathrm{DAC}} =
+\frac{P_{\mathrm{EOS}}(V_{\mathrm{heated}}, T_{\mathrm{independent}})
+      - P_{\mathrm{ambient}}}
+     {\Delta P_{\mathrm{thermal}}
+      (V_{\mathrm{heated}}, T_{\mathrm{independent}})}.
+\]
+
+The reference volume also needs experimental scrutiny. Heating can cause
+irreversible pressure or stress relaxation, so a post-cooling volume need not
+equal the pre-heating reference. Prefer reference measurements bracketing the
+heating sequence; interpolate a drifting baseline when justified. Otherwise,
+define the stable interval, report how its average was selected, and propagate
+its scatter rather than treating the average as exact.
+
+For a fixed volume pair, increasing `f_dac` raises the required thermal pressure
+and therefore normally raises the inferred temperature. The result is singular
+as `f_dac` approaches one and can be highly sensitive to small errors in both
+volumes, particularly when their difference is small. Sweep the plausible
+`f_dac` range, propagate both volume errors, and check that the resulting
+temperature remains inside the calibrated range of the selected EOS. Report the
+uncorrected `f_dac=0` result alongside the sensitivity cases. See
+[Uncertainty](uncertainty.md) and the [DAC references](references.md).

{peritheos-0.4.0 → peritheos-0.5.0}/docs/development.md

@@ -32,8 +32,14 @@ derivative, array, invalid-input, and round-trip tests.
 
 Subclass `ThermalEOS` and implement `thermal_pressure(V, T)`. The base class
 provides total pressure, inversion, isothermal bulk modulus, compressibility,
-and expansivity. Implement `molar_heat_capacity_v()` only when the model has a
-defined caloric potential; the base class then provides `C_P` and `K_S`.
+and expansivity. Both volume and temperature inversion are array-aware.
+Implement `molar_heat_capacity_v()` only when the model has a defined caloric
+potential; the base class then provides `C_P` and `K_S`.
+
+Models with expensive fixed-volume preparation may override the private
+`_thermal_pressure_function(V)` hook. It returns a temperature-only callable
+used by both inversion methods; Sokolova uses it to evaluate its volume integral
+once per solved state.
 
 Document the required molar-volume unit, reference temperature, pressure unit,
 parameter domain, source equations, and whether energy methods are absolute or