peritheos 0.2.0__tar.gz → 0.4.0__tar.gz

peritheos-0.4.0/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to Peritheos are documented here. The project follows
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [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.4.0...HEAD
+[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/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.4.0
+date-released: 2026-08-09
+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.4.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.4.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.4.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.4.0}/PKG-INFO

@@ -1,13 +1,16 @@
 Metadata-Version: 2.4
 Name: peritheos
-Version: 0.2.0
+Version: 0.4.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,7 +24,7 @@ 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: numpy>=1.21.0
 Requires-Dist: scipy>=1.7.0
 Dynamic: license-file
 
@@ -29,22 +32,39 @@ Dynamic: license-file
 
 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,28 @@ 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)
+```
+
 Diamond thermal equation of state from sokolova et al. 2016
 
 ```python
@@ -143,3 +185,10 @@ print(f"RT pressure: {rt_pressure} GPa")
 print(f"Total pressure: {pressure} GPa")
 print(f"Recovered volume: {recovered_volume} J bar^-1")
 ```
+
+## 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.4.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,28 @@ 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)
+```
+
 Diamond thermal equation of state from sokolova et al. 2016
 
 ```python
@@ -116,3 +155,10 @@ print(f"RT pressure: {rt_pressure} GPa")
 print(f"Total pressure: {pressure} GPa")
 print(f"Recovered volume: {recovered_volume} J bar^-1")
 ```
+
+## 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.4.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.4.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.4.0/docs/api-stability.md

@@ -0,0 +1,35 @@
+# 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.
+
+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.

peritheos-0.4.0/docs/api.md

@@ -0,0 +1,105 @@
+# API reference
+
+## Isothermal equations of state
+
+```python
+from peritheos.eos.rt import (
+    BM2,
+    BM3,
+    BM4,
+    Holzapfel,
+    ModifiedTait,
+    Murnaghan,
+    NaturalStrain2,
+    NaturalStrain3,
+    NaturalStrain4,
+    Vinet,
+)
+```
+
+Common methods:
+
+- `pressure(V)`
+- `bulk_modulus(V)`
+- `volume(P)` and `calculate_volume(P)`
+
+## Thermal equations of state
+
+```python
+from peritheos.eos.thermal import (
+    HollandPowell2011,
+    MieGruneisenDebye,
+    MieGruneisenEinstein,
+    Sokolova2016,
+    ThermalModifiedTait,
+)
+```
+
+Common methods:
+
+- `thermal_pressure(V, T)`
+- `pressure(V, T)`
+- `volume(P, T)`
+- `bulk_modulus(V, T)`
+- `isothermal_compressibility(V, T)`
+- `thermal_expansivity(V, T)`
+- `molar_heat_capacity_v(V, T)` when a caloric model exists
+- `molar_heat_capacity_p(V, T)` when a caloric model exists
+- `adiabatic_bulk_modulus(V, T)` when a caloric model exists
+- `gruneisen_parameter(V, T)` when a caloric model exists
+
+Mie-Gruneisen models additionally expose `gruneisen_parameter()`,
+`characteristic_temperature()`, and the vibrational thermodynamic methods
+documented under [Thermoelastic properties](thermoelastic-properties.md).
+
+## Fitting
+
+```python
+from peritheos.fitting import FitResult, fit_joint_eos, fit_rt_eos, fit_thermal_eos
+```
+
+`FitResult` contains the fitted `model`, parameter and uncertainty mappings,
+covariance and correlation matrices, raw and weighted residuals, chi-square,
+degrees of freedom, AIC, BIC, convergence status, and solver message. It also
+reports `adjusted_volume`, `adjusted_temperature`, `volume_corrections`, and
+`temperature_corrections` for errors-in-variables fits. See
+[Fitting P-V and P-V-T data](fitting.md) for the pressure, volume, and
+temperature uncertainty API.
+
+`FitResult.summary()` returns a compact text report. `FitResult.to_dict()` and
+`FitResult.to_json()` export a versioned, JSON-safe record containing the model
+identity and reconstructable parameters, fit arrays, diagnostics, and solver
+configuration. Passing a path to `to_json()` also writes the record to disk.
+
+`fit_joint_eos()` estimates reference-isotherm and thermal parameters in one
+regression. Reference parameters use dotted names such as `rt_eos.V0`; its
+covariance includes reference/thermal cross-correlations and is directly
+compatible with `FitResult.eos_uncertainty()`.
+
+## Units
+
+```python
+from peritheos.units import (
+    convert_density,
+    convert_molar_volume,
+    density_from_molar_volume,
+    molar_volume_from_density,
+)
+```
+
+## Uncertainty propagation
+
+```python
+from peritheos import EOSUncertainty, ParameterUncertainty, PredictionUncertainty
+```
+
+`EOSUncertainty` wraps a deterministic EOS and provides `pressure()`, `volume()`,
+`bulk_modulus()`, and the generic `evaluate()` method. Each returns a
+`PredictionUncertainty` containing the nominal value, standard error, confidence
+limits, statistical assumptions, and an optional output covariance matrix.
+
+`FitResult.eos_uncertainty()` constructs the wrapper directly from fitted
+parameter covariance. See [Uncertainty in EOS calculations](uncertainty.md).
+Partial parameter-error sets are supported. Parameters omitted from the error
+mapping or covariance ordering are treated as exact, rather than as having an
+unknown error that Peritheos will estimate.

peritheos-0.4.0/docs/development.md

@@ -0,0 +1,40 @@
+# Development
+
+## Test suite
+
+```bash
+uv sync --all-groups
+uv run ruff check .
+uv run ruff format --check .
+uv run pytest -q -W error --cov --cov-report=term-missing
+```
+
+If the default uv cache is unavailable in a sandbox:
+
+```bash
+UV_CACHE_DIR=/tmp/peritheos-uv-cache uv run pytest -q
+```
+
+## Documentation
+
+```bash
+uv run --group docs mkdocs build --strict
+```
+
+## Adding an isothermal EOS
+
+Subclass `EosBase`, validate `V0` and modulus parameters using the shared
+validators, and implement analytic `pressure()` and `bulk_modulus()` methods.
+The inherited volume solver supplies array-aware inversion. Add reference-state,
+derivative, array, invalid-input, and round-trip tests.
+
+## Adding a thermal EOS
+
+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`.
+
+Document the required molar-volume unit, reference temperature, pressure unit,
+parameter domain, source equations, and whether energy methods are absolute or
+reference contributions.