nmbackend 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (139) hide show
  1. nmbackend-0.4.0/LICENSE +21 -0
  2. nmbackend-0.4.0/PKG-INFO +168 -0
  3. nmbackend-0.4.0/README.md +118 -0
  4. nmbackend-0.4.0/pyproject.toml +44 -0
  5. nmbackend-0.4.0/setup.cfg +4 -0
  6. nmbackend-0.4.0/src/nmbackend/__init__.py +22 -0
  7. nmbackend-0.4.0/src/nmbackend/adapters/__init__.py +4 -0
  8. nmbackend-0.4.0/src/nmbackend/adapters/rift.py +95 -0
  9. nmbackend-0.4.0/src/nmbackend/constants.py +55 -0
  10. nmbackend-0.4.0/src/nmbackend/cooling/README.md +159 -0
  11. nmbackend-0.4.0/src/nmbackend/cooling/__init__.py +13 -0
  12. nmbackend-0.4.0/src/nmbackend/cooling/build_nscool.sh +51 -0
  13. nmbackend-0.4.0/src/nmbackend/cooling/isothermal.py +76 -0
  14. nmbackend-0.4.0/src/nmbackend/cooling/nscool_nmbackend.patch +310 -0
  15. nmbackend-0.4.0/src/nmbackend/cooling/physics/__init__.py +18 -0
  16. nmbackend-0.4.0/src/nmbackend/cooling/physics/_spline.py +71 -0
  17. nmbackend-0.4.0/src/nmbackend/cooling/physics/blanket.py +66 -0
  18. nmbackend-0.4.0/src/nmbackend/cooling/physics/conduct.py +196 -0
  19. nmbackend-0.4.0/src/nmbackend/cooling/physics/core_conduct.py +68 -0
  20. nmbackend-0.4.0/src/nmbackend/cooling/physics/core_nu.py +268 -0
  21. nmbackend-0.4.0/src/nmbackend/cooling/physics/crust.py +113 -0
  22. nmbackend-0.4.0/src/nmbackend/cooling/physics/crust_nu.py +93 -0
  23. nmbackend-0.4.0/src/nmbackend/cooling/physics/curve.py +42 -0
  24. nmbackend-0.4.0/src/nmbackend/cooling/physics/envelope.py +37 -0
  25. nmbackend-0.4.0/src/nmbackend/cooling/physics/gaps.py +164 -0
  26. nmbackend-0.4.0/src/nmbackend/cooling/physics/geometry.py +131 -0
  27. nmbackend-0.4.0/src/nmbackend/cooling/physics/heat.py +125 -0
  28. nmbackend-0.4.0/src/nmbackend/cooling/physics/native.py +138 -0
  29. nmbackend-0.4.0/src/nmbackend/cooling/physics/reference.py +53 -0
  30. nmbackend-0.4.0/src/nmbackend/cooling/physics/star.py +225 -0
  31. nmbackend-0.4.0/src/nmbackend/cooling/physics/superfluid.py +41 -0
  32. nmbackend-0.4.0/src/nmbackend/cooling/physics/whole.py +136 -0
  33. nmbackend-0.4.0/src/nmbackend/cooling/runner.py +583 -0
  34. nmbackend-0.4.0/src/nmbackend/cooling/validate.py +120 -0
  35. nmbackend-0.4.0/src/nmbackend/data/crust_sly_dh2001.dat +81 -0
  36. nmbackend-0.4.0/src/nmbackend/data/frib_scenario_ladder.yaml +100 -0
  37. nmbackend-0.4.0/src/nmbackend/durca.py +111 -0
  38. nmbackend-0.4.0/src/nmbackend/ejecta.py +614 -0
  39. nmbackend-0.4.0/src/nmbackend/eos/__init__.py +19 -0
  40. nmbackend-0.4.0/src/nmbackend/eos/base.py +523 -0
  41. nmbackend-0.4.0/src/nmbackend/eos/compose.py +251 -0
  42. nmbackend-0.4.0/src/nmbackend/eos/coolcomp.py +67 -0
  43. nmbackend-0.4.0/src/nmbackend/eos/crust.py +318 -0
  44. nmbackend-0.4.0/src/nmbackend/eos/ddrmf.py +388 -0
  45. nmbackend-0.4.0/src/nmbackend/eos/hybrid.py +173 -0
  46. nmbackend-0.4.0/src/nmbackend/eos/leptons.py +74 -0
  47. nmbackend-0.4.0/src/nmbackend/eos/metamodel.py +303 -0
  48. nmbackend-0.4.0/src/nmbackend/eos/polytrope.py +33 -0
  49. nmbackend-0.4.0/src/nmbackend/eos/rmft.py +450 -0
  50. nmbackend-0.4.0/src/nmbackend/eos/skyrme.py +352 -0
  51. nmbackend-0.4.0/src/nmbackend/inference/__init__.py +13 -0
  52. nmbackend-0.4.0/src/nmbackend/inference/fisher.py +174 -0
  53. nmbackend-0.4.0/src/nmbackend/inference/synthetic.py +83 -0
  54. nmbackend-0.4.0/src/nmbackend/ipad.py +102 -0
  55. nmbackend-0.4.0/src/nmbackend/lab_likelihood.py +587 -0
  56. nmbackend-0.4.0/src/nmbackend/nscool_io.py +112 -0
  57. nmbackend-0.4.0/src/nmbackend/postmerger.py +264 -0
  58. nmbackend-0.4.0/src/nmbackend/priors/__init__.py +16 -0
  59. nmbackend-0.4.0/src/nmbackend/priors/bridge.py +437 -0
  60. nmbackend-0.4.0/src/nmbackend/priors/bridge_jax.py +435 -0
  61. nmbackend-0.4.0/src/nmbackend/priors/gp_pca.py +325 -0
  62. nmbackend-0.4.0/src/nmbackend/reference/__init__.py +11 -0
  63. nmbackend-0.4.0/src/nmbackend/reference/reprimand.py +108 -0
  64. nmbackend-0.4.0/src/nmbackend/reference/scipy_tov.py +289 -0
  65. nmbackend-0.4.0/src/nmbackend/rift/__init__.py +26 -0
  66. nmbackend-0.4.0/src/nmbackend/rift/compressed.py +194 -0
  67. nmbackend-0.4.0/src/nmbackend/rift/evidence.py +276 -0
  68. nmbackend-0.4.0/src/nmbackend/rift/sequence.py +428 -0
  69. nmbackend-0.4.0/src/nmbackend/rotating/__init__.py +7 -0
  70. nmbackend-0.4.0/src/nmbackend/rotating/rns.py +197 -0
  71. nmbackend-0.4.0/src/nmbackend/rotating/tabulated.py +249 -0
  72. nmbackend-0.4.0/src/nmbackend/thermal/__init__.py +1 -0
  73. nmbackend-0.4.0/src/nmbackend/thermal/diffusion.py +86 -0
  74. nmbackend-0.4.0/src/nmbackend/tov/__init__.py +15 -0
  75. nmbackend-0.4.0/src/nmbackend/tov/central.py +72 -0
  76. nmbackend-0.4.0/src/nmbackend/tov/family.py +155 -0
  77. nmbackend-0.4.0/src/nmbackend/tov/phase_transition.py +93 -0
  78. nmbackend-0.4.0/src/nmbackend/tov/solver.py +475 -0
  79. nmbackend-0.4.0/src/nmbackend/validation/__init__.py +5 -0
  80. nmbackend-0.4.0/src/nmbackend/validation/model_diagnostic.py +67 -0
  81. nmbackend-0.4.0/src/nmbackend/validation/reference_matrix.py +216 -0
  82. nmbackend-0.4.0/src/nmbackend.egg-info/PKG-INFO +168 -0
  83. nmbackend-0.4.0/src/nmbackend.egg-info/SOURCES.txt +137 -0
  84. nmbackend-0.4.0/src/nmbackend.egg-info/dependency_links.txt +1 -0
  85. nmbackend-0.4.0/src/nmbackend.egg-info/requires.txt +20 -0
  86. nmbackend-0.4.0/src/nmbackend.egg-info/top_level.txt +1 -0
  87. nmbackend-0.4.0/tests/test_ad_gradients.py +80 -0
  88. nmbackend-0.4.0/tests/test_bridge_jax.py +381 -0
  89. nmbackend-0.4.0/tests/test_bridge_prior.py +227 -0
  90. nmbackend-0.4.0/tests/test_central.py +52 -0
  91. nmbackend-0.4.0/tests/test_compose.py +404 -0
  92. nmbackend-0.4.0/tests/test_coolcomp.py +147 -0
  93. nmbackend-0.4.0/tests/test_cooling_core_conduct.py +73 -0
  94. nmbackend-0.4.0/tests/test_cooling_crust_chemistry.py +73 -0
  95. nmbackend-0.4.0/tests/test_cooling_dump.py +95 -0
  96. nmbackend-0.4.0/tests/test_cooling_geometry.py +177 -0
  97. nmbackend-0.4.0/tests/test_cooling_isothermal.py +117 -0
  98. nmbackend-0.4.0/tests/test_cooling_native.py +67 -0
  99. nmbackend-0.4.0/tests/test_cooling_native_blanket.py +92 -0
  100. nmbackend-0.4.0/tests/test_cooling_nscool.py +131 -0
  101. nmbackend-0.4.0/tests/test_cooling_physics_core.py +134 -0
  102. nmbackend-0.4.0/tests/test_cooling_physics_crust.py +115 -0
  103. nmbackend-0.4.0/tests/test_cooling_physics_gaps.py +90 -0
  104. nmbackend-0.4.0/tests/test_cooling_physics_star.py +179 -0
  105. nmbackend-0.4.0/tests/test_cooling_whole.py +57 -0
  106. nmbackend-0.4.0/tests/test_core_stability.py +153 -0
  107. nmbackend-0.4.0/tests/test_crust.py +182 -0
  108. nmbackend-0.4.0/tests/test_ddrmf.py +118 -0
  109. nmbackend-0.4.0/tests/test_durca.py +101 -0
  110. nmbackend-0.4.0/tests/test_ejecta.py +283 -0
  111. nmbackend-0.4.0/tests/test_eos_metamodel.py +47 -0
  112. nmbackend-0.4.0/tests/test_fisher.py +82 -0
  113. nmbackend-0.4.0/tests/test_gp_pca_prior.py +127 -0
  114. nmbackend-0.4.0/tests/test_ipad.py +54 -0
  115. nmbackend-0.4.0/tests/test_lab_likelihood.py +336 -0
  116. nmbackend-0.4.0/tests/test_lepton_derivatives.py +30 -0
  117. nmbackend-0.4.0/tests/test_model_diagnostic.py +29 -0
  118. nmbackend-0.4.0/tests/test_no_recompile.py +99 -0
  119. nmbackend-0.4.0/tests/test_nscool_io.py +94 -0
  120. nmbackend-0.4.0/tests/test_phase_transition.py +115 -0
  121. nmbackend-0.4.0/tests/test_postmerger.py +106 -0
  122. nmbackend-0.4.0/tests/test_reference_matrix.py +33 -0
  123. nmbackend-0.4.0/tests/test_reference_surface.py +23 -0
  124. nmbackend-0.4.0/tests/test_rift_adapter.py +36 -0
  125. nmbackend-0.4.0/tests/test_rift_compressed.py +90 -0
  126. nmbackend-0.4.0/tests/test_rift_sequence.py +334 -0
  127. nmbackend-0.4.0/tests/test_rmft.py +75 -0
  128. nmbackend-0.4.0/tests/test_rotating_rns.py +75 -0
  129. nmbackend-0.4.0/tests/test_rotating_tabulated.py +150 -0
  130. nmbackend-0.4.0/tests/test_rotating_urca_example.py +114 -0
  131. nmbackend-0.4.0/tests/test_skyrme.py +126 -0
  132. nmbackend-0.4.0/tests/test_synthetic_events.py +74 -0
  133. nmbackend-0.4.0/tests/test_thermal_diffusion.py +83 -0
  134. nmbackend-0.4.0/tests/test_tidal_cs2_consistency.py +181 -0
  135. nmbackend-0.4.0/tests/test_tov.py +55 -0
  136. nmbackend-0.4.0/tests/test_tov_jump_ts.py +141 -0
  137. nmbackend-0.4.0/tests/test_tov_profile.py +44 -0
  138. nmbackend-0.4.0/tests/test_units.py +33 -0
  139. nmbackend-0.4.0/tests/test_validation_reference.py +43 -0
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 R. O'Shaughnessy and the RIT CCRG nuclear-matter group
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,168 @@
1
+ Metadata-Version: 2.4
2
+ Name: nmbackend
3
+ Version: 0.4.0
4
+ Summary: NuclearMatter-Backend: differentiable EOS + TOV tools for neutron-star EOS inference, interfacing RIFT and gwkokab.
5
+ Author: R. O'Shaughnessy, RIT CCRG nuclear-matter group
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 R. O'Shaughnessy and the RIT CCRG nuclear-matter group
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Keywords: neutron-star,equation-of-state,TOV,tidal-deformability,gravitational-waves,automatic-differentiation,jax,RIFT,gwkokab
29
+ Classifier: License :: OSI Approved :: MIT License
30
+ Classifier: Programming Language :: Python :: 3
31
+ Requires-Python: >=3.9
32
+ Description-Content-Type: text/markdown
33
+ License-File: LICENSE
34
+ Requires-Dist: numpy>=1.21
35
+ Requires-Dist: scipy>=1.7
36
+ Requires-Dist: jax>=0.4.20
37
+ Requires-Dist: jaxlib>=0.4.20
38
+ Requires-Dist: diffrax>=0.5
39
+ Requires-Dist: pyyaml>=5.0
40
+ Provides-Extra: reprimand
41
+ Provides-Extra: rift
42
+ Provides-Extra: gwkokab
43
+ Requires-Dist: numpyro; extra == "gwkokab"
44
+ Provides-Extra: test
45
+ Requires-Dist: pytest>=7.0; extra == "test"
46
+ Provides-Extra: docs
47
+ Requires-Dist: sphinx; extra == "docs"
48
+ Requires-Dist: myst-parser; extra == "docs"
49
+ Dynamic: license-file
50
+
51
+ # NuclearMatter-Backend (`nmbackend`)
52
+
53
+ An open-source research toolkit for neutron-star **equations of state (EOS),
54
+ stellar structure, tidal deformability, and EOS inference**. The JAX core combines
55
+ nuclear models and imported tables with an adaptive TOV solver and selected
56
+ automatic-differentiation paths. It extends the preliminary EOS tooling in RIFT's
57
+ `EOSManager.py` and provides implemented RIFT adapters and sequence I/O.
58
+
59
+ **Status: v0.4.0, research software.** Capabilities have different validation and
60
+ differentiation coverage; inclusion does not establish precision-inference
61
+ readiness. Start with the [documentation index](docs/index.rst),
62
+ [capability guide](docs/capabilities.rst), and [validation guide](docs/validation.rst).
63
+
64
+ ## Capabilities
65
+
66
+ - **EOS families:** nuclear empirical-parameter metamodel with causal tail;
67
+ nonlinear RMFT (GM1), density-dependent RMF (DD2/DDME2), standard/extended
68
+ Skyrme (SLy4/BSkG3), polytropes, Maxwell hybrid transitions, CompOSE/simple
69
+ tables and MUSES-CMF CSV readers, with crust and lepton/composition utilities.
70
+ - **Structure and tides:** adaptive diffrax TOV-in-enthalpy, Love numbers and
71
+ M–R–Λ families; explicit hybrid tidal junctions and an independent radius-domain
72
+ SciPy reference. Twin-star handling remains limited (see below).
73
+ - **Priors and inference:** constrained Brownian-bridge EOS draws, PCA sequence
74
+ compression and Gaussian coefficient-prior tools; fixed-mass and maximum-mass
75
+ sensitivities, Fisher forecasts, density-tagged laboratory likelihoods and
76
+ published merger-ejecta fitting families with uncertainty estimates.
77
+ - **RIFT workflows:** `EOSConcreteNMB`, native tabular and PCA sequences, and legacy
78
+ Landry-format export. A recorded RIFT CIP smoke test establishes plumbing,
79
+ **not** science-grade per-EOS evidence: its 12-EOS input was remapped against an
80
+ interpolant indexed for 10,000 EOS. See [RIFT integration](docs/rift.rst).
81
+ - **Rotation and cooling interfaces:** pinned external RNS equilibrium runner and
82
+ tabulated-EOS adapter, external NSCool driver, and separate JAX thermal transport
83
+ on frozen backgrounds. RNS/NSCool are not bundled; these paths do not establish
84
+ a fully coupled rotating-star cooling model. See [rotation](docs/rotating.md)
85
+ and [thermal limits](docs/cooling/core_transport_validation.md).
86
+
87
+ **Integration boundaries:** gwkokab is a planned adapter, despite an optional
88
+ package dependency. MUSES supplies out-of-band EOS tables/reference targets;
89
+ it is not an integrated inference dependency.
90
+
91
+ ## Install and quickstart
92
+
93
+ Use a project-local environment (Python ≥3.9; core dependencies include NumPy,
94
+ SciPy, JAX, diffrax and PyYAML):
95
+
96
+ ```bash
97
+ python -m venv .venv
98
+ source .venv/bin/activate
99
+ python -m pip install -e .
100
+ python examples/quickstart.py
101
+ # Optional test dependencies and suite:
102
+ python -m pip install -e '.[test]'
103
+ python -m pytest
104
+ ```
105
+
106
+ For the heavier validation environment and optional references, see
107
+ [installation](docs/installation.rst) and [environment notes](docs/environment.md).
108
+
109
+ ```python
110
+ from nmbackend.eos import MetaModelEOS
111
+ from nmbackend.tov import build_family, m_max, radius_of_mass, lambda_of_mass
112
+ from nmbackend.adapters import EOSConcreteNMB
113
+
114
+ model = MetaModelEOS()
115
+ params = dict(K_sat=230., E_sym=32., L_sym=60., cs2_tail=0.4)
116
+ family = build_family(model.eos_table(params))
117
+ print(m_max(family), radius_of_mass(family, 1.4), lambda_of_mass(family, 1.4))
118
+ eos = EOSConcreteNMB(model, params) # RIFT-compatible single-EOS interface
119
+ ```
120
+
121
+ ## Differentiation and branch limits
122
+
123
+ Use forward mode (`jax.jacfwd`, `jax.jvp`) for supported EOS/TOV sensitivities.
124
+ Reverse mode is supported for structure-only solves (`tidal=False`); reverse mode
125
+ through the tidal variable is not recommended. First derivatives in central
126
+ enthalpy are supported, but second derivatives in central enthalpy or EOS
127
+ parameters are not. Accuracy depends on tolerance, EOS representation and
128
+ transitions; the [physics guide](docs/physics.rst) records the current node/jump
129
+ handling and derivative caveats. Fixed-mass sensitivities use the implicit-function
130
+ theorem rather than coarse family interpolation; see [inference](docs/inference.rst).
131
+
132
+ `build_family`/single-EOS adapters do not yet provide complete disconnected
133
+ (twin-star) branch handling. RIFT sequence scalar accessors and legacy export
134
+ retain the primary stable rising branch; sequence branch counts let callers detect
135
+ and reject or route multi-branch EOS. They do not marginalize over all branches.
136
+
137
+ ## Validation evidence and remaining work
138
+
139
+ The repository records internal comparisons against an independently implemented
140
+ radius-domain SciPy solver, including <0.1% M/R/Λ agreement for the documented
141
+ smooth/hybrid cases. Hybrid references sharing the same junction formula check
142
+ integration consistency; the smeared-transition limit separately checks the sign.
143
+ October 2026 interpolation/tidal fixes and their table-specific results are
144
+ recorded in the [physics guide](docs/physics.rst).
145
+
146
+ The initial **~200 m RePrimAnd radius mismatch is historical**: the later
147
+ [surface/interpolation report](docs/devlog/2026-06-02f-consistent-interpolation.md)
148
+ records **~3–10 m in R and <0.1% in Λ against RePrimAnd 1.7** for the compared cases.
149
+ That dated result is separate from the internal SciPy comparison and is not a
150
+ comprehensive accuracy certification of today's entire model/parameter space.
151
+ External-reference coverage, convergence, crust systematics and disconnected
152
+ branches remain work items. See the [evidence and limits](docs/validation.rst),
153
+ [validation plan](docs/validation-plan.md), and [roadmap](docs/roadmap.md).
154
+
155
+ ## Scientific credit and license
156
+
157
+ MIT-licensed, by R. O'Shaughnessy and the RIT CCRG nuclear-matter group.
158
+ [ATTRIBUTION.md](ATTRIBUTION.md) distinguishes independently implemented methods,
159
+ reused data and optional external software; external licenses remain separate.
160
+ Data products we generate and archive (for example on Zenodo) are released
161
+ under CC-BY-4.0. Third-party data shipped here keep their own licenses, listed
162
+ in ATTRIBUTION.md.
163
+ Foundations include Margueron, Hoffmann Casali & Gulminelli's metamodel
164
+ ([I](https://arxiv.org/abs/1708.06894), [II](https://arxiv.org/abs/1708.06895)),
165
+ [Hinderer's tidal calculation](https://arxiv.org/abs/0711.2420),
166
+ [Damour & Nagar](https://arxiv.org/abs/0906.0096), and laboratory constraints from
167
+ [Huth et al.](https://arxiv.org/abs/2107.06229) and
168
+ [Tsang et al.](https://arxiv.org/abs/2310.11588).
@@ -0,0 +1,118 @@
1
+ # NuclearMatter-Backend (`nmbackend`)
2
+
3
+ An open-source research toolkit for neutron-star **equations of state (EOS),
4
+ stellar structure, tidal deformability, and EOS inference**. The JAX core combines
5
+ nuclear models and imported tables with an adaptive TOV solver and selected
6
+ automatic-differentiation paths. It extends the preliminary EOS tooling in RIFT's
7
+ `EOSManager.py` and provides implemented RIFT adapters and sequence I/O.
8
+
9
+ **Status: v0.4.0, research software.** Capabilities have different validation and
10
+ differentiation coverage; inclusion does not establish precision-inference
11
+ readiness. Start with the [documentation index](docs/index.rst),
12
+ [capability guide](docs/capabilities.rst), and [validation guide](docs/validation.rst).
13
+
14
+ ## Capabilities
15
+
16
+ - **EOS families:** nuclear empirical-parameter metamodel with causal tail;
17
+ nonlinear RMFT (GM1), density-dependent RMF (DD2/DDME2), standard/extended
18
+ Skyrme (SLy4/BSkG3), polytropes, Maxwell hybrid transitions, CompOSE/simple
19
+ tables and MUSES-CMF CSV readers, with crust and lepton/composition utilities.
20
+ - **Structure and tides:** adaptive diffrax TOV-in-enthalpy, Love numbers and
21
+ M–R–Λ families; explicit hybrid tidal junctions and an independent radius-domain
22
+ SciPy reference. Twin-star handling remains limited (see below).
23
+ - **Priors and inference:** constrained Brownian-bridge EOS draws, PCA sequence
24
+ compression and Gaussian coefficient-prior tools; fixed-mass and maximum-mass
25
+ sensitivities, Fisher forecasts, density-tagged laboratory likelihoods and
26
+ published merger-ejecta fitting families with uncertainty estimates.
27
+ - **RIFT workflows:** `EOSConcreteNMB`, native tabular and PCA sequences, and legacy
28
+ Landry-format export. A recorded RIFT CIP smoke test establishes plumbing,
29
+ **not** science-grade per-EOS evidence: its 12-EOS input was remapped against an
30
+ interpolant indexed for 10,000 EOS. See [RIFT integration](docs/rift.rst).
31
+ - **Rotation and cooling interfaces:** pinned external RNS equilibrium runner and
32
+ tabulated-EOS adapter, external NSCool driver, and separate JAX thermal transport
33
+ on frozen backgrounds. RNS/NSCool are not bundled; these paths do not establish
34
+ a fully coupled rotating-star cooling model. See [rotation](docs/rotating.md)
35
+ and [thermal limits](docs/cooling/core_transport_validation.md).
36
+
37
+ **Integration boundaries:** gwkokab is a planned adapter, despite an optional
38
+ package dependency. MUSES supplies out-of-band EOS tables/reference targets;
39
+ it is not an integrated inference dependency.
40
+
41
+ ## Install and quickstart
42
+
43
+ Use a project-local environment (Python ≥3.9; core dependencies include NumPy,
44
+ SciPy, JAX, diffrax and PyYAML):
45
+
46
+ ```bash
47
+ python -m venv .venv
48
+ source .venv/bin/activate
49
+ python -m pip install -e .
50
+ python examples/quickstart.py
51
+ # Optional test dependencies and suite:
52
+ python -m pip install -e '.[test]'
53
+ python -m pytest
54
+ ```
55
+
56
+ For the heavier validation environment and optional references, see
57
+ [installation](docs/installation.rst) and [environment notes](docs/environment.md).
58
+
59
+ ```python
60
+ from nmbackend.eos import MetaModelEOS
61
+ from nmbackend.tov import build_family, m_max, radius_of_mass, lambda_of_mass
62
+ from nmbackend.adapters import EOSConcreteNMB
63
+
64
+ model = MetaModelEOS()
65
+ params = dict(K_sat=230., E_sym=32., L_sym=60., cs2_tail=0.4)
66
+ family = build_family(model.eos_table(params))
67
+ print(m_max(family), radius_of_mass(family, 1.4), lambda_of_mass(family, 1.4))
68
+ eos = EOSConcreteNMB(model, params) # RIFT-compatible single-EOS interface
69
+ ```
70
+
71
+ ## Differentiation and branch limits
72
+
73
+ Use forward mode (`jax.jacfwd`, `jax.jvp`) for supported EOS/TOV sensitivities.
74
+ Reverse mode is supported for structure-only solves (`tidal=False`); reverse mode
75
+ through the tidal variable is not recommended. First derivatives in central
76
+ enthalpy are supported, but second derivatives in central enthalpy or EOS
77
+ parameters are not. Accuracy depends on tolerance, EOS representation and
78
+ transitions; the [physics guide](docs/physics.rst) records the current node/jump
79
+ handling and derivative caveats. Fixed-mass sensitivities use the implicit-function
80
+ theorem rather than coarse family interpolation; see [inference](docs/inference.rst).
81
+
82
+ `build_family`/single-EOS adapters do not yet provide complete disconnected
83
+ (twin-star) branch handling. RIFT sequence scalar accessors and legacy export
84
+ retain the primary stable rising branch; sequence branch counts let callers detect
85
+ and reject or route multi-branch EOS. They do not marginalize over all branches.
86
+
87
+ ## Validation evidence and remaining work
88
+
89
+ The repository records internal comparisons against an independently implemented
90
+ radius-domain SciPy solver, including <0.1% M/R/Λ agreement for the documented
91
+ smooth/hybrid cases. Hybrid references sharing the same junction formula check
92
+ integration consistency; the smeared-transition limit separately checks the sign.
93
+ October 2026 interpolation/tidal fixes and their table-specific results are
94
+ recorded in the [physics guide](docs/physics.rst).
95
+
96
+ The initial **~200 m RePrimAnd radius mismatch is historical**: the later
97
+ [surface/interpolation report](docs/devlog/2026-06-02f-consistent-interpolation.md)
98
+ records **~3–10 m in R and <0.1% in Λ against RePrimAnd 1.7** for the compared cases.
99
+ That dated result is separate from the internal SciPy comparison and is not a
100
+ comprehensive accuracy certification of today's entire model/parameter space.
101
+ External-reference coverage, convergence, crust systematics and disconnected
102
+ branches remain work items. See the [evidence and limits](docs/validation.rst),
103
+ [validation plan](docs/validation-plan.md), and [roadmap](docs/roadmap.md).
104
+
105
+ ## Scientific credit and license
106
+
107
+ MIT-licensed, by R. O'Shaughnessy and the RIT CCRG nuclear-matter group.
108
+ [ATTRIBUTION.md](ATTRIBUTION.md) distinguishes independently implemented methods,
109
+ reused data and optional external software; external licenses remain separate.
110
+ Data products we generate and archive (for example on Zenodo) are released
111
+ under CC-BY-4.0. Third-party data shipped here keep their own licenses, listed
112
+ in ATTRIBUTION.md.
113
+ Foundations include Margueron, Hoffmann Casali & Gulminelli's metamodel
114
+ ([I](https://arxiv.org/abs/1708.06894), [II](https://arxiv.org/abs/1708.06895)),
115
+ [Hinderer's tidal calculation](https://arxiv.org/abs/0711.2420),
116
+ [Damour & Nagar](https://arxiv.org/abs/0906.0096), and laboratory constraints from
117
+ [Huth et al.](https://arxiv.org/abs/2107.06229) and
118
+ [Tsang et al.](https://arxiv.org/abs/2310.11588).
@@ -0,0 +1,44 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61.0", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "nmbackend"
7
+ version = "0.4.0"
8
+ description = "NuclearMatter-Backend: differentiable EOS + TOV tools for neutron-star EOS inference, interfacing RIFT and gwkokab."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = { file = "LICENSE" }
12
+ classifiers = ["License :: OSI Approved :: MIT License", "Programming Language :: Python :: 3"]
13
+ authors = [
14
+ { name = "R. O'Shaughnessy" },
15
+ { name = "RIT CCRG nuclear-matter group" },
16
+ ]
17
+ keywords = ["neutron-star", "equation-of-state", "TOV", "tidal-deformability",
18
+ "gravitational-waves", "automatic-differentiation", "jax", "RIFT", "gwkokab"]
19
+ dependencies = [
20
+ "numpy>=1.21",
21
+ "scipy>=1.7",
22
+ "jax>=0.4.20",
23
+ "jaxlib>=0.4.20",
24
+ "diffrax>=0.5", # adaptive (accurate) TOV backend; default solver
25
+ "pyyaml>=5.0", # packaged FRIB scenario-ladder data (lab_likelihood)
26
+ ]
27
+
28
+ [project.optional-dependencies]
29
+ # Heavier / external reference backends, kept optional so the core stays light.
30
+ reprimand = [] # pyreprimand (high-accuracy reference TOV); install separately
31
+ rift = [] # RIFT / lalsuite for downstream inference
32
+ gwkokab = ["numpyro"] # population-inference target
33
+ test = ["pytest>=7.0"]
34
+ docs = ["sphinx", "myst-parser"]
35
+
36
+ [tool.setuptools.packages.find]
37
+ where = ["src"]
38
+
39
+ [tool.setuptools.package-data]
40
+ nmbackend = ["data/*.yaml", "data/*.dat", "cooling/*.patch", "cooling/*.sh", "cooling/README.md"]
41
+
42
+ [tool.pytest.ini_options]
43
+ testpaths = ["tests"]
44
+ addopts = "-q"
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,22 @@
1
+ """NuclearMatter-Backend (nmbackend).
2
+
3
+ A differentiable (JAX) neutron-star EOS + TOV toolkit for EOS inference, designed
4
+ to interface with RIFT (per-EOS evidence / hyperpipeline) and gwkokab (population
5
+ inference). See README.md and docs/architecture.md.
6
+ """
7
+ from . import constants
8
+ from . import ejecta
9
+ from . import ipad
10
+ from . import postmerger
11
+ # lab_likelihood, priors, inference, rift, adapters are add-ons imported
12
+ # explicitly (from nmbackend import lab_likelihood), not eagerly here.
13
+ from .eos import MetaModelEOS, PolytropeEOS, EOSModel, EOSTable
14
+ from .tov import solve_structure, build_family, m_max
15
+
16
+ __version__ = "0.4.0"
17
+
18
+ __all__ = [
19
+ "constants", "ejecta",
20
+ "MetaModelEOS", "PolytropeEOS", "EOSModel", "EOSTable",
21
+ "solve_structure", "build_family", "m_max",
22
+ ]
@@ -0,0 +1,4 @@
1
+ """Adapters to downstream inference frameworks (RIFT now; gwkokab planned)."""
2
+ from .rift import EOSConcreteNMB
3
+
4
+ __all__ = ["EOSConcreteNMB"]
@@ -0,0 +1,95 @@
1
+ """RIFT ``EOSConcrete``-compatible adapter.
2
+
3
+ RIFT's ``EOSManager.EOSConcrete`` objects are consumed downstream mainly through
4
+
5
+ * ``lambda_from_m(m)`` -> tidal deformability at gravitational mass m
6
+ * ``lambda_from_m_vector(marr)``
7
+ * ``pressure_density_on_grid(logrho_grid, ...)`` -> log10 p(SI) vs log10 rho(SI)
8
+ * ``mMaxMsun`` -> maximum mass (prior bound)
9
+ * ``name`` -> identifier
10
+
11
+ ``EOSConcreteNMB`` provides exactly this surface, backed by the differentiable
12
+ JAX TOV family, so a NuclearMatter-Backend EOS drops into "normal" RIFT (per-EOS
13
+ evidence) and hence the tabular hyperpipeline. It does **not** import lalsuite;
14
+ ``self.eos``/``self.eos_fam`` are exposed (table / ``None``) for duck-typing.
15
+
16
+ Accepts mass either in solar masses (~1.4) or SI kg (>1e10), matching RIFT.
17
+ """
18
+ from __future__ import annotations
19
+
20
+ import numpy as np
21
+
22
+ from ..constants import MSUN_SI, MEVFM3_TO_PA, NUCLEON_KG, FM3_TO_M3
23
+ from ..eos.base import EOSModel
24
+ from ..tov.family import build_family, default_hc_grid
25
+
26
+
27
+ def _to_msun(m):
28
+ m = np.asarray(m, dtype=float)
29
+ return np.where(m > 1e10, m / MSUN_SI, m)
30
+
31
+
32
+ class EOSConcreteNMB:
33
+ """Duck-typed RIFT EOSConcrete backed by nmbackend's JAX TOV family."""
34
+
35
+ def __init__(self, model: EOSModel, params: dict = None, name: str = None,
36
+ n_models: int = 120, n_steps: int = 800):
37
+ self.name = name or getattr(model, "name", "nmbackend-EOS")
38
+ self.model = model
39
+ self.params = dict(params or {})
40
+
41
+ table = model.eos_table(self.params)
42
+ self.eos = table # RIFT duck-typing: the EOS object
43
+ self.eos_fam = None # no lalsuite family; sequence cached below
44
+
45
+ fam = build_family(table, default_hc_grid(table, n_models=n_models),
46
+ n_steps=n_steps)
47
+
48
+ # cache stable rising branch (numpy) for fast lookup
49
+ M = np.asarray(fam.M_msun)
50
+ R = np.asarray(fam.R_km)
51
+ L = np.asarray(fam.Lambda)
52
+ stable = np.asarray(fam.stable)
53
+ idx_max = int(np.argmax(np.where(stable, M, -np.inf)))
54
+ sl = slice(int(np.argmax(stable)), idx_max + 1) # minimum mass to M_max
55
+ self._M = M[sl]
56
+ self._R = R[sl]
57
+ self._L = L[sl]
58
+ self.mMaxMsun = float(M[idx_max])
59
+
60
+ # EOS table in SI for pressure_density_on_grid
61
+ n = np.asarray(table.n) # fm^-3
62
+ self._rho_si = n * NUCLEON_KG / FM3_TO_M3 # kg/m^3 (rest-mass density)
63
+ self._p_si = np.asarray(table.p_mevfm3) * MEVFM3_TO_PA # Pa
64
+
65
+ # ---- RIFT EOSConcrete surface ----
66
+ def lambda_from_m(self, m):
67
+ m_msun = float(_to_msun(np.atleast_1d(m))[0])
68
+ if m_msun >= self.mMaxMsun:
69
+ return 0.0
70
+ return float(np.interp(m_msun, self._M, self._L))
71
+
72
+ def lambda_from_m_vector(self, m):
73
+ m_msun = _to_msun(m)
74
+ out = np.interp(m_msun, self._M, self._L,
75
+ left=self._L[0], right=0.0)
76
+ out = np.where(m_msun >= self.mMaxMsun, 0.0, out)
77
+ return out
78
+
79
+ def radius_from_m(self, m):
80
+ m_msun = float(_to_msun(np.atleast_1d(m))[0])
81
+ return float(np.interp(m_msun, self._M, self._R))
82
+
83
+ def pressure_density_on_grid(self, logrho_grid, enforce_causal=False):
84
+ """log10 p[SI, Pa] on a grid of log10 rho[SI, kg/m^3] (rest-mass density)."""
85
+ logrho_tab = np.log10(self._rho_si)
86
+ logp_tab = np.log10(self._p_si)
87
+ return np.interp(np.asarray(logrho_grid), logrho_tab, logp_tab)
88
+
89
+ def mass_radius_lambda(self):
90
+ """Return cached stable-branch (M[Msun], R[km], Lambda) arrays."""
91
+ return self._M.copy(), self._R.copy(), self._L.copy()
92
+
93
+ def __repr__(self):
94
+ return (f"<EOSConcreteNMB {self.name} "
95
+ f"mMax={self.mMaxMsun:.3f} Msun, params={self.params}>")
@@ -0,0 +1,55 @@
1
+ """Physical constants and unit conversions for NuclearMatter-Backend.
2
+
3
+ Internal TOV units are *geometric* (G = c = 1) with **length in km**. In these
4
+ units energy density and pressure have dimension km^-2, mass has dimension km,
5
+ and the pseudo-enthalpy h = integral dp/(eps+p) is dimensionless. Masses are
6
+ reported in solar masses by dividing the geometric mass (km) by GMsun/c^2.
7
+
8
+ Nuclear inputs are in MeV and fm^-3; the conversion ``MEVFM3_TO_GEOM`` maps an
9
+ energy density in MeV/fm^3 to geometric km^-2.
10
+
11
+ Motivated by unit handling in RIFT ``EOSManager`` and ``jester`` (MIT); see
12
+ ATTRIBUTION.md.
13
+ """
14
+ from __future__ import annotations
15
+
16
+ # --- fundamental constants (CODATA-ish, SI) ---
17
+ G_SI = 6.67430e-11 # m^3 kg^-1 s^-2
18
+ C_SI = 2.99792458e8 # m / s
19
+ # Solar mass parameter: the IAU 2015 Resolution B3 nominal (GM)_sun (exact by
20
+ # definition), as current LALSuite (LAL_GMSUN_SI in lal 7.7.0 LALConstants.h)
21
+ # and the Q2C oracle use. Until 2026-10-14 this module had MSUN_SI = 1.98892e30
22
+ # kg (old LAL's solar mass, meant for CODATA-1986 G); paired with CODATA-2018 G,
23
+ # GMSUN_KM came out 1.4770039 km, 2.566e-4 above the 1.476625 km its comment
24
+ # claimed (docs/devlog/2026-10-14-gmsun-iau.md). MSUN_SI is derived, so
25
+ # G_SI * MSUN_SI == GM_SUN_SI.
26
+ GM_SUN_SI = 1.3271244e20 # m^3 s^-2
27
+ MSUN_SI = GM_SUN_SI / G_SI # kg, 1.98840987069805e30 (= lal 7.7 LAL_MSUN_SI)
28
+
29
+ # --- nuclear constants ---
30
+ HBARC = 197.3269804 # MeV fm
31
+ M_N = 939.565421 # neutron mass, MeV
32
+ M_P = 938.272088 # proton mass, MeV
33
+ M_E = 0.510998950 # electron mass, MeV
34
+ M_MU = 105.6583755 # muon mass, MeV
35
+ M_BARYON = 939.0 # representative baryon (rest-mass density) mass, MeV
36
+ MEV_TO_FM_INV = 1.0 / HBARC # 1 MeV = (1/hbarc) fm^-1
37
+
38
+ # --- geometric length scale: GMsun/c^2 in km ---
39
+ # 1.476625 km (IAU nominal). Geometric mass [km] / GMSUN_KM -> mass [Msun].
40
+ GMSUN_KM = GM_SUN_SI / C_SI**2 / 1.0e3 # 1.4766250 km
41
+
42
+ # --- energy-density / pressure conversion: MeV/fm^3 -> geometric km^-2 ---
43
+ # eps_geom[m^-2] = (G/c^4) * eps_SI[Pa]; 1 MeV/fm^3 = 1.602176634e32 Pa.
44
+ _MEVFM3_TO_PA = 1.602176634e32
45
+ _G_OVER_C4 = G_SI / C_SI**4 # m^-1 kg^-1 s^2
46
+ MEVFM3_TO_GEOM = _G_OVER_C4 * _MEVFM3_TO_PA * 1.0e6 # km^-2 per (MeV/fm^3)
47
+
48
+ # --- SI helpers for the RIFT adapter (pressure in Pa, density in kg/m^3) ---
49
+ GEOM_KM2_TO_PA = 1.0 / (_G_OVER_C4 * 1.0e6) # km^-2 -> Pa
50
+ MEVFM3_TO_PA = _MEVFM3_TO_PA # MeV/fm^3 -> Pa
51
+ FM3_TO_M3 = 1.0e-45 # fm^3 -> m^3
52
+ NUCLEON_KG = M_BARYON * 1.602176634e-13 / C_SI**2 # kg per baryon (rest mass)
53
+
54
+ # default nuclear saturation density (fm^-3)
55
+ N_SAT_DEFAULT = 0.16