pantometry 0.16.0__tar.gz

pantometry-0.16.0/Cargo.toml

@@ -0,0 +1,77 @@
+[workspace]
+members = [
+    "crates/pantometry-units",
+    "crates/pantometry-core",
+    "crates/pantometry-optics",
+    "crates/pantometry-thermal",
+    "crates/pantometry-mechanics",
+    "crates/pantometry-acoustic",
+    "crates/pantometry-molecular",
+    "crates/pantometry-electrical",
+    "crates/pantometry-porous",
+    "crates/pantometry-elastic",
+    "crates/pantometry-em",
+    "crates/pantometry-fluid",
+    "crates/pantometry-quantum",
+    # Not a domain and not a layer: input preparation. It depends on `pantometry-units` and nothing else
+    # in the workspace, and no domain depends on it — it hands out a predicate and a domain's `fill`
+    # takes one, which is the whole coupling.
+    "crates/pantometry-shape",
+    "crates/pantometry-scene",
+    "crates/pantometry-view",
+    "crates/pantometry",
+    # The first consumer. Not published — it exists to find out where the SDK is awkward,
+    # which is a question no test in the library can answer about itself.
+    "crates/pantometry-world",
+]
+exclude = [
+    # Its own workspace: pyo3 brings fifteen crates and a libpython link, and the library's
+    # lockfile, `deny.toml` allow-list and wasm jobs are promises that should not have to
+    # accommodate a Python extension. See its Cargo.toml.
+    "bindings/python",
+    # And its own for the same reason, measured rather than assumed: pyo3 adds seven external
+    # crates and that was enough to split it out. A GPU stack is far past that, and none of the
+    # eleven published crates may carry it. See runtime/viewer/Cargo.toml.
+    "runtime/viewer",
+    # And the GPU accelerator, which is the same argument again plus one that is not about
+    # dependencies at all: WGSL has no f64, so a compute kernel is a *different computation* from
+    # the domain it accelerates. See runtime/gpu/README.md.
+    "runtime/gpu",
+]
+resolver = "2"
+
+[workspace.package]
+version = "0.16.0"
+edition = "2021"
+# Verified by the `msrv` CI job rather than guessed, and set by `Cargo.lock` being
+# format version 4 rather than by anything in the source — see that job's comment.
+rust-version = "1.78"
+license = "MIT OR Apache-2.0"
+authors = ["Younghyeon Park and pantometry contributors"]
+repository = "https://github.com/YounghyeonPark/pantometry"
+
+[workspace.dependencies]
+pantometry-units = { path = "crates/pantometry-units", version = "0.16.0" }
+pantometry-core = { path = "crates/pantometry-core", version = "0.16.0" }
+pantometry-optics = { path = "crates/pantometry-optics", version = "0.16.0" }
+pantometry-thermal = { path = "crates/pantometry-thermal", version = "0.16.0" }
+pantometry-mechanics = { path = "crates/pantometry-mechanics", version = "0.16.0" }
+pantometry-acoustic = { path = "crates/pantometry-acoustic", version = "0.16.0" }
+pantometry = { path = "crates/pantometry", version = "0.16.0" }
+pantometry-molecular = { path = "crates/pantometry-molecular", version = "0.16.0" }
+pantometry-electrical = { path = "crates/pantometry-electrical", version = "0.16.0" }
+pantometry-porous = { path = "crates/pantometry-porous", version = "0.16.0" }
+pantometry-elastic = { path = "crates/pantometry-elastic", version = "0.16.0" }
+pantometry-em = { path = "crates/pantometry-em", version = "0.16.0" }
+pantometry-fluid = { path = "crates/pantometry-fluid", version = "0.16.0" }
+pantometry-quantum = { path = "crates/pantometry-quantum", version = "0.16.0" }
+pantometry-shape = { path = "crates/pantometry-shape", version = "0.16.0" }
+pantometry-scene = { path = "crates/pantometry-scene", version = "0.16.0" }
+pantometry-view = { path = "crates/pantometry-view", version = "0.16.0" }
+glam = { version = "0.29", features = ["serde"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+[profile.release]
+opt-level = 3
+lto = true

pantometry-0.16.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: pantometry
+Version: 0.16.0
+Classifier: Programming Language :: Rust
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering :: Physics
+Summary: Coupled physics whose conservation audit is an exception you can catch
+License: MIT OR Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://github.com/YounghyeonPark/pantometry
+
+# pantometry for Python
+
+Coupled physics whose conservation audit is an exception you can catch.
+
+```sh
+pip install pantometry        # wheels for linux, macos and windows; abi3, so 3.10 upward
+```
+
+```python
+import pantometry
+
+sim = pantometry.Simulation(schedule="multirate", conservation_tolerance=1e-9)
+sim.add_heater("element", watts=2.0, reserve_j=6.0)
+sim.add_bar("bar", length_m=0.020, cells=41, area_m2=1e-4)
+
+for _ in range(8):
+    sim.advance(0.5)          # raises pantometry.Violation if the books do not close
+
+print(sim.temperature("bar"))     # 294.39 K
+print(sim.profile("bar")[:3])     # warmer at the fed end
+```
+
+## Several bodies and the drop between them
+
+`add_lump` gives you one temperature for a whole assembly. The number that decides whether a
+motor survives is the *winding*, which is hotter than the case by however much the joint
+between them resists — so for that, a network:
+
+```python
+sim = pantometry.Simulation(schedule="staggered")
+sim.add_heater("losses", watts=6.0, reserve_j=5_400.0)
+sim.add_network("motor",
+    nodes=[{"name": "winding", "material": "copper", "volume_m3": 18e-6,
+            "thickness_m": 2e-3, "initial_k": 298.15},
+           {"name": "case", "material": "aluminium", "volume_m3": 220e-6,
+            "thickness_m": 4e-3, "initial_k": 298.15,
+            "ambient_k": 298.15, "area_m2": 0.042}],   # both keys, or neither
+    links=[{"from": "winding", "to": "case", "w_per_k": 0.9}],
+    absorbing="winding")
+
+for _ in range(900):
+    sim.advance(1.0)
+
+dict(sim.node_temperatures("motor"))     # {'winding': 311.2, 'case': 304.9}
+sim.heat_flow_w("motor", "winding", "case")   # 5.585 W crossing the joint
+```
+
+`material` is any name in the kernel's catalogue, and this line no longer lists them — it used to say
+five, the binding accepted those same five against a catalogue of nine, and listing them here made a
+**fourth** copy of a spelling that had already gone stale three times. The error message names them, and
+it is generated from the catalogue, so it is right by construction. A node with `ambient_k` and
+`area_m2` loses heat to still air; a node with neither is interior. Giving one without the other
+is refused rather than quietly producing a node that looks like it is cooling and is not.
+
+Names are resolved once, when the network is built, so a link to a node that does not exist
+raises before any stepping happens and lists the nodes that do. That matters more here than it
+looks: a link adds `+q` to one node and `−q` to another in the same sum, so a missing or
+misdirected link passes the conservation audit at machine precision and simply reports the wrong
+temperature forever.
+
+`temperature()` refuses a network rather than averaging it — the reason to build one is that its
+nodes differ, so a mean would describe no part of it.
+
+## Why this rather than numpy
+
+Write physics in numpy and a wrong model runs happily, producing plausible output. There is no
+signal; you find out when somebody notices the answer is silly.
+
+Every `advance` here either moves the clock or raises, and the exception is addressable rather
+than a sentence to parse:
+
+```python
+try:
+    sim.advance(0.5)
+except pantometry.Violation as v:
+    v.quantity     # 'energy'
+    v.site         # 'bus (published but not consumed)'
+    v.before, v.after, v.scale, v.tolerance
+    sim.time       # unchanged — a refused step does not advance the clock
+```
+
+**Be clear about what it catches.** Quantities appearing or vanishing, amounts left unclaimed on
+the bus, and a domain refusing a step it cannot take. It does *not* catch a model that is
+internally consistent and physically wrong. For that, check against something the library did not
+compute — which is what `heat_capacity_j_per_k` is exported for, and what
+`tests/test_pantometry.py` does throughout.
+
+## What crosses the boundary, and what does not
+
+Values cross as **SI floats with the unit in the parameter name**: `length_m`, `watts`,
+`initial_k`. pantometry's dimensional types are a compile-time thing — `Length + Time` does not
+compile in Rust — and Python cannot have that. A runtime `Quantity` wrapper would cost an
+allocation and a check per operation to catch, at run time, a class of error a Python caller
+mostly does not make, because it passes values in and reads them out rather than doing algebra on
+them. So the types stay on the Rust side and the units stay in the names.
+
+What crosses instead is the audit, which is the part worth having.
+
+## What this cannot do
+
+**You cannot run an ensemble from Python, and it is not an oversight.** `Ensemble` exists to run
+many independent samples across threads, and a Python sample function cannot: the GIL serialises
+it. A binding for it would look parallel, measure slower than a plain Python loop because of the
+crossing cost, and have nothing left of the one thing it is for. Write the sampler in Rust, or
+loop in Python and accept one core.
+
+**You cannot write a domain in Python.** That means calling back into the interpreter from inside
+the step loop, holding the GIL across it, and deciding what an exception raised mid-sweep does to
+a half-advanced simulation. All three are answerable and none cheaply, so this binds the physics
+the library has and says so rather than shipping a subtly wrong version of that.
+
+So: enough to **run and audit** coupled physics from Python, not enough to **extend** it. The
+extending lives in Rust, and [the workspace](https://github.com/YounghyeonPark/pantometry) is where.
+
+A `Simulation` is also bound to the thread that created it. `Domain` is not `Send`, and the
+binding says so rather than asking the kernel for a bound it does not offer.
+
+**There is no scene or view binding.** The Rust side has `pantometry-scene` for capturing a run and
+`pantometry-view` for drawing one; neither crosses. Nothing forbids it in principle — the reason is
+that a Python caller already has matplotlib, pandas and every plotting stack there is, and what
+they want from this side is the *numbers*: `profile`, `node_temperatures`, `temperature`,
+`ledger`. Handing them an SVG instead would be the worse half of both worlds. If you want the
+HTML report, run the scene from Rust.
+
+## Building
+
+Its own cargo workspace, deliberately. This one resolves fifteen external crates where the
+library resolves twelve, seven of them pyo3's and appearing nowhere in the library, plus a
+libpython link — and the library's lockfile, licence allow-list and WebAssembly jobs are promises
+that should not have to accommodate a Python extension.
+
+```sh
+cd bindings/python
+pip install "maturin>=1.7,<2.0"
+maturin build --release          # an abi3 wheel: one build serves 3.10 upward
+pip install target/wheels/pantometry-*.whl
+python tests/test_pantometry.py
+```
+
+`maturin develop` works too, in a virtualenv. CI builds the wheel, installs it and runs those
+tests on every commit — because "it compiles" proves neither half of "pip install then import".
+

pantometry-0.16.0/README.md

@@ -0,0 +1,141 @@
+# pantometry for Python
+
+Coupled physics whose conservation audit is an exception you can catch.
+
+```sh
+pip install pantometry        # wheels for linux, macos and windows; abi3, so 3.10 upward
+```
+
+```python
+import pantometry
+
+sim = pantometry.Simulation(schedule="multirate", conservation_tolerance=1e-9)
+sim.add_heater("element", watts=2.0, reserve_j=6.0)
+sim.add_bar("bar", length_m=0.020, cells=41, area_m2=1e-4)
+
+for _ in range(8):
+    sim.advance(0.5)          # raises pantometry.Violation if the books do not close
+
+print(sim.temperature("bar"))     # 294.39 K
+print(sim.profile("bar")[:3])     # warmer at the fed end
+```
+
+## Several bodies and the drop between them
+
+`add_lump` gives you one temperature for a whole assembly. The number that decides whether a
+motor survives is the *winding*, which is hotter than the case by however much the joint
+between them resists — so for that, a network:
+
+```python
+sim = pantometry.Simulation(schedule="staggered")
+sim.add_heater("losses", watts=6.0, reserve_j=5_400.0)
+sim.add_network("motor",
+    nodes=[{"name": "winding", "material": "copper", "volume_m3": 18e-6,
+            "thickness_m": 2e-3, "initial_k": 298.15},
+           {"name": "case", "material": "aluminium", "volume_m3": 220e-6,
+            "thickness_m": 4e-3, "initial_k": 298.15,
+            "ambient_k": 298.15, "area_m2": 0.042}],   # both keys, or neither
+    links=[{"from": "winding", "to": "case", "w_per_k": 0.9}],
+    absorbing="winding")
+
+for _ in range(900):
+    sim.advance(1.0)
+
+dict(sim.node_temperatures("motor"))     # {'winding': 311.2, 'case': 304.9}
+sim.heat_flow_w("motor", "winding", "case")   # 5.585 W crossing the joint
+```
+
+`material` is any name in the kernel's catalogue, and this line no longer lists them — it used to say
+five, the binding accepted those same five against a catalogue of nine, and listing them here made a
+**fourth** copy of a spelling that had already gone stale three times. The error message names them, and
+it is generated from the catalogue, so it is right by construction. A node with `ambient_k` and
+`area_m2` loses heat to still air; a node with neither is interior. Giving one without the other
+is refused rather than quietly producing a node that looks like it is cooling and is not.
+
+Names are resolved once, when the network is built, so a link to a node that does not exist
+raises before any stepping happens and lists the nodes that do. That matters more here than it
+looks: a link adds `+q` to one node and `−q` to another in the same sum, so a missing or
+misdirected link passes the conservation audit at machine precision and simply reports the wrong
+temperature forever.
+
+`temperature()` refuses a network rather than averaging it — the reason to build one is that its
+nodes differ, so a mean would describe no part of it.
+
+## Why this rather than numpy
+
+Write physics in numpy and a wrong model runs happily, producing plausible output. There is no
+signal; you find out when somebody notices the answer is silly.
+
+Every `advance` here either moves the clock or raises, and the exception is addressable rather
+than a sentence to parse:
+
+```python
+try:
+    sim.advance(0.5)
+except pantometry.Violation as v:
+    v.quantity     # 'energy'
+    v.site         # 'bus (published but not consumed)'
+    v.before, v.after, v.scale, v.tolerance
+    sim.time       # unchanged — a refused step does not advance the clock
+```
+
+**Be clear about what it catches.** Quantities appearing or vanishing, amounts left unclaimed on
+the bus, and a domain refusing a step it cannot take. It does *not* catch a model that is
+internally consistent and physically wrong. For that, check against something the library did not
+compute — which is what `heat_capacity_j_per_k` is exported for, and what
+`tests/test_pantometry.py` does throughout.
+
+## What crosses the boundary, and what does not
+
+Values cross as **SI floats with the unit in the parameter name**: `length_m`, `watts`,
+`initial_k`. pantometry's dimensional types are a compile-time thing — `Length + Time` does not
+compile in Rust — and Python cannot have that. A runtime `Quantity` wrapper would cost an
+allocation and a check per operation to catch, at run time, a class of error a Python caller
+mostly does not make, because it passes values in and reads them out rather than doing algebra on
+them. So the types stay on the Rust side and the units stay in the names.
+
+What crosses instead is the audit, which is the part worth having.
+
+## What this cannot do
+
+**You cannot run an ensemble from Python, and it is not an oversight.** `Ensemble` exists to run
+many independent samples across threads, and a Python sample function cannot: the GIL serialises
+it. A binding for it would look parallel, measure slower than a plain Python loop because of the
+crossing cost, and have nothing left of the one thing it is for. Write the sampler in Rust, or
+loop in Python and accept one core.
+
+**You cannot write a domain in Python.** That means calling back into the interpreter from inside
+the step loop, holding the GIL across it, and deciding what an exception raised mid-sweep does to
+a half-advanced simulation. All three are answerable and none cheaply, so this binds the physics
+the library has and says so rather than shipping a subtly wrong version of that.
+
+So: enough to **run and audit** coupled physics from Python, not enough to **extend** it. The
+extending lives in Rust, and [the workspace](https://github.com/YounghyeonPark/pantometry) is where.
+
+A `Simulation` is also bound to the thread that created it. `Domain` is not `Send`, and the
+binding says so rather than asking the kernel for a bound it does not offer.
+
+**There is no scene or view binding.** The Rust side has `pantometry-scene` for capturing a run and
+`pantometry-view` for drawing one; neither crosses. Nothing forbids it in principle — the reason is
+that a Python caller already has matplotlib, pandas and every plotting stack there is, and what
+they want from this side is the *numbers*: `profile`, `node_temperatures`, `temperature`,
+`ledger`. Handing them an SVG instead would be the worse half of both worlds. If you want the
+HTML report, run the scene from Rust.
+
+## Building
+
+Its own cargo workspace, deliberately. This one resolves fifteen external crates where the
+library resolves twelve, seven of them pyo3's and appearing nowhere in the library, plus a
+libpython link — and the library's lockfile, licence allow-list and WebAssembly jobs are promises
+that should not have to accommodate a Python extension.
+
+```sh
+cd bindings/python
+pip install "maturin>=1.7,<2.0"
+maturin build --release          # an abi3 wheel: one build serves 3.10 upward
+pip install target/wheels/pantometry-*.whl
+python tests/test_pantometry.py
+```
+
+`maturin develop` works too, in a virtualenv. CI builds the wheel, installs it and runs those
+tests on every commit — because "it compiles" proves neither half of "pip install then import".