peritheos 0.2.0__tar.gz → 0.5.0__tar.gz

peritheos-0.5.0/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+All notable changes to Peritheos are documented here. The project follows
+[Semantic Versioning](https://semver.org/).
+
+## [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
+
+- Branch-aware coverage enforcement, Ruff lint and formatting gates, and a
+  minimum-supported-dependency CI job.
+- Literature-tagged numerical cases for all public EOS families and an
+  independently solvable weighted least-squares fitting benchmark.
+- Automatic GitHub Releases with source and wheel artifacts.
+- Citation metadata, API stability, contribution, security, support, conduct,
+  issue, and pull-request policies.
+- Versioned Read the Docs builds using the locked uv documentation environment.
+- Joint reference-isotherm and thermal parameter fitting with complete
+  cross-covariance through `fit_joint_eos`.
+- Per-observation correlated P-V and P-V-T covariance matrices and robust
+  least-squares losses for all fitting entry points.
+- Human-readable fit summaries and versioned, JSON-safe result export including
+  model parameters, covariance, adjusted observations, diagnostics, and solver
+  metadata.
+
+### Changed
+
+- Uncertainty propagation tests now cover Monte Carlo state sampling, invalid
+  covariance and option handling, one-sided numerical derivatives, wrapper
+  behavior, and failed sampling; branch-aware project coverage exceeds 90%.
+- Corrected the fourth-order Birch-Murnaghan documentation to match its
+  implemented Eulerian-strain signs and exponents.
+- Package maturity metadata now identifies the 0.4 development line as beta.
+- The minimum supported NumPy version is now 1.21, matching the public typing
+  APIs used by Peritheos.
+- Distribution package discovery is restricted to `peritheos`, preventing
+  generated documentation directories from entering or blocking builds.
+
+## [0.3.0] - 2026-08-08
+
+### Added
+
+- Murnaghan, modified Tait, and second- through fourth-order natural-strain
+  room-temperature equations of state.
+- Holland-Powell thermal modified Tait equation of state.
+- Bounded P-V and P-V-T errors-in-variables fitting with independently optional
+  pressure, volume, and temperature standard errors.
+- `FitResult` covariance, correlation, parameter-error, residual, chi-square,
+  information-criterion, and adjusted-state diagnostics.
+- `EOSUncertainty` for propagating complete covariance matrices, parameter
+  errors with correlations, or partial independent parameter errors into EOS
+  calculations.
+- Linear covariance propagation and reproducible Monte Carlo propagation for
+  pressure, volume, bulk modulus, and arbitrary public EOS quantities.
+- Optional propagation of pressure, volume, and temperature errors in the
+  requested state.
+- Explicit combination of separately quantified thermal and reference-EOS
+  uncertainty blocks.
+- Isothermal compressibility, thermal expansivity, constant-volume and
+  constant-pressure heat capacities, thermodynamic Gruneisen parameter, and
+  adiabatic bulk modulus APIs.
+- Vibrational entropy, internal energy, Helmholtz energy, enthalpy, and Gibbs
+  energy for the Mie-Gruneisen-Debye and Mie-Gruneisen-Einstein models.
+- Molar-volume and density conversion helpers with explicit unit validation.
+- Literature-tagged reference cases and expanded numerical regression tests.
+- A multi-page MkDocs documentation site covering models, fitting,
+  uncertainty, properties, units, validation, references, and development.
+
+### Changed
+
+- EOS models now expose reconstructable parameter values and safe parameter
+  replacement, including dotted reference-EOS parameters such as
+  `rt_eos.K0`.
+- Thermal EOS calculations consistently document and enforce their molar
+  volume, pressure, and temperature units.
+- CI now builds the documentation strictly, and source distributions include
+  documentation and literature-validation data.
+- The legacy fitting argument `sigma` remains supported as an alias for
+  `pressure_sigma`.
+
+### Statistical assumptions
+
+- Parameters omitted from an uncertainty specification are treated as exact.
+- Individual parameter errors without a correlation matrix are treated as
+  mutually independent.
+- Combining thermal and reference-EOS results from separate fits requires an
+  explicit block-independence assumption.
+
+## [0.2.0] - 2026-08-07
+
+### Added
+
+- Fourth-order Birch-Murnaghan support.
+- Complete Sokolova et al. (2016) pressure terms and parameters.
+- Automated test and trusted PyPI publication workflows.
+
+### Changed
+
+- EOS pressure and volume validation and inversion were hardened for invalid
+  and out-of-domain states.
+- Project naming and release metadata were standardized.
+
+[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.5.0/CITATION.cff

@@ -0,0 +1,20 @@
+cff-version: 1.2.0
+message: >-
+  If you use Peritheos in published work, please cite the software and the
+  original references for the equation-of-state models you use.
+title: Peritheos
+type: software
+version: 0.5.0
+date-released: 2026-08-30
+authors:
+  - family-names: Prescher
+    given-names: Clemens
+    email: clemens.prescher@gmail.com
+repository-code: https://github.com/CPrescher/peritheos
+url: https://peritheos.readthedocs.io/
+license: MIT
+keywords:
+  - equation of state
+  - high pressure
+  - thermodynamics
+  - solid materials

peritheos-0.5.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,19 @@
+# Code of conduct
+
+Peritheos is committed to a respectful, inclusive, and scientifically rigorous
+community.
+
+Participants are expected to communicate constructively, distinguish evidence
+from opinion, acknowledge uncertainty, welcome correction, and respect differing
+levels of experience. Harassment, personal attacks, discriminatory language,
+deliberate misrepresentation, and disclosure of another person's private
+information are unacceptable.
+
+Project maintainers may edit or remove contributions that violate these
+expectations and may temporarily or permanently restrict participation. Report
+conduct concerns privately to `clemens.prescher@gmail.com`. Reports will be
+handled as confidentially as practical, with attention to the safety of the
+reporter and others affected.
+
+This policy applies in project spaces and when someone publicly represents the
+project.

peritheos-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing to Peritheos
+
+Contributions are welcome, particularly independently reproducible validation
+cases, numerical robustness improvements, and documentation clarifications.
+
+## Development setup
+
+Install [uv](https://docs.astral.sh/uv/) and create the locked development
+environment:
+
+```bash
+uv sync --all-groups
+```
+
+Run the same checks used by continuous integration:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest -q -W error --cov --cov-report=term-missing
+uv run --group docs mkdocs build --strict
+```
+
+## Scientific changes
+
+Changes to an equation, constant, unit convention, fitting statistic, or
+uncertainty calculation should include:
+
+- the primary literature reference and DOI where one exists;
+- an independently calculated numerical case, not only a value generated by
+  the implementation under test;
+- reference-state, derivative, array, invalid-domain, and inversion tests when
+  applicable;
+- the model order, units, parameter convention, and valid state range in the
+  documentation; and
+- an entry under `Unreleased` in `CHANGELOG.md`.
+
+Do not silently change an existing scientific convention. Follow the
+[API stability policy](https://peritheos.readthedocs.io/en/latest/api-stability/)
+and document any migration path.
+
+## Pull requests
+
+Keep each pull request focused. Explain the physical or statistical motivation,
+identify the validation source, and call out any API or numerical-compatibility
+impact. All checks must pass before merging.

peritheos-0.5.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include mkdocs.yml
+include CHANGELOG.md
+include CITATION.cff
+include CODE_OF_CONDUCT.md
+include CONTRIBUTING.md
+include SECURITY.md
+include SUPPORT.md
+recursive-include docs *.md *.txt
+recursive-include tests/data *.json

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

@@ -1,13 +1,16 @@
 Metadata-Version: 2.4
 Name: peritheos
-Version: 0.2.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
 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 :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.9
@@ -21,30 +24,47 @@ 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
+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 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.
+- 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
 
@@ -84,6 +104,46 @@ 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
@@ -137,9 +197,18 @@ 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.

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

@@ -2,22 +2,39 @@
 
 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 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.
+- 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
 
@@ -57,6 +74,46 @@ 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
@@ -110,9 +167,18 @@ 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.

peritheos-0.5.0/SECURITY.md

@@ -0,0 +1,25 @@
+# Security policy
+
+## Supported versions
+
+Peritheos supports the latest released minor series. Security fixes may be
+backported when an older release remains widely used, but no backport is
+guaranteed before version 1.0.
+
+## Reporting a vulnerability
+
+Please do not open a public issue for a vulnerability that could expose users.
+Use the repository's
+[private vulnerability reporting](https://github.com/CPrescher/peritheos/security/advisories/new)
+or email Clemens Prescher at `clemens.prescher@gmail.com` with:
+
+- the affected version;
+- a minimal reproduction or proof of concept;
+- the expected impact; and
+- any proposed mitigation.
+
+You should receive an acknowledgement within seven days. A fix and disclosure
+timeline will be coordinated after the report is reproduced.
+
+Numerical inaccuracies without a security impact should use the scientific
+validation issue template instead.

peritheos-0.5.0/SUPPORT.md

@@ -0,0 +1,14 @@
+# Support
+
+Use [GitHub Issues](https://github.com/CPrescher/peritheos/issues) for confirmed
+bugs, documentation problems, and focused feature requests.
+
+For a numerical discrepancy, include the Peritheos version, model and complete
+parameter set, units, input state, observed result, expected result, and the
+publication or independent program used for comparison. A minimal Python
+example is strongly preferred.
+
+Peritheos is research software supplied without warranty. Users remain
+responsible for checking model choice, reference state, units, weighting, and
+extrapolation limits before relying on results in publications or safety-
+critical decisions.

peritheos-0.5.0/docs/api-stability.md

@@ -0,0 +1,39 @@
+# API stability
+
+Peritheos follows [Semantic Versioning](https://semver.org/). Before 1.0, a
+minor release may include a necessary breaking correction, particularly when a
+published equation or unit convention was implemented incorrectly. Such a
+change must be prominent in the changelog and release notes.
+
+## Public API
+
+The supported public API consists of:
+
+- names documented in the [API reference](api.md);
+- names exported by a module's `__all__`;
+- constructor parameters and documented public methods of exported EOS classes;
+- the documented GPa, kelvin, and molar-volume conventions; and
+- scalar and NumPy broadcasting behavior described in the documentation.
+
+Names beginning with an underscore, implementation details not documented in
+the API reference, and exact optimizer messages are private.
+
+## Compatibility commitments
+
+`volume()` is the preferred pressure-to-volume method. `calculate_volume()` is
+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
+case and a migration note.
+
+Patch releases may improve numerical precision, validation, warning text, or
+solver robustness without treating the last floating-point bit or exact error
+message as stable. Published calculations should record the Peritheos version,
+model order, complete parameters, units, and uncertainty convention.