fusionflux 0.2.2__py3-none-any.whl

fusionflux/__init__.py

@@ -0,0 +1,50 @@
+"""The confinement study, callable.
+
+``pip install fusionflux`` installs exactly two things: this package and
+``neutron_yield``. It deliberately does not install the analysis scripts. Those
+are ``hdb5.py``, ``scaling_law.py``, ``dimensional.py`` and the twelve
+``analysis_*.py`` modules, they are run from a checkout as ``python3 hdb5.py
+train``, and every one of them needs a dataset that is fetched from OSF rather
+than shipped. Installing them would put ``config``, ``storage``, ``validation``
+and ``forecast`` on the import path of every environment this package lands in,
+where they would shadow any other project's module of the same name, in exchange
+for scripts that cannot run without a download the wheel does not provide.
+
+So the installable surface is the part that works with nothing but the wheel: a
+point estimate, a calibrated interval, an extrapolation distance, and a refusal,
+all read from a few kilobytes of coefficients shipped inside the package.
+
+    from fusionflux import predict
+
+    result = predict(ip_ma=15.0, bt_t=5.3, ne_line_1e19_m3=10.0, p_loss_mw=87.0,
+                     r_m=6.2, inverse_aspect_ratio=0.3226, kappa=1.7, m_eff_amu=2.5)
+
+    result.tau_s                              # 2.837
+    result.physics_exceeds_training_ceiling   # True
+"""
+
+from __future__ import annotations
+
+from fusionflux.predictor import (
+    ConfinementPrediction,
+    ModelPrediction,
+    ServiceCard,
+    build_service_card,
+    format_prediction,
+    load_card,
+    predict,
+    save_card,
+)
+
+__all__ = [
+    "ConfinementPrediction",
+    "ModelPrediction",
+    "ServiceCard",
+    "build_service_card",
+    "format_prediction",
+    "load_card",
+    "predict",
+    "save_card",
+]
+
+__version__ = "0.2.1"

fusionflux/__main__.py

@@ -0,0 +1,22 @@
+"""``python3 -m fusionflux`` runs the same command as the console script.
+
+Useful in two places. In a checkout there is no installed console script until
+someone runs `pip install -e .`, and `make results` should not depend on that.
+And in an environment where the wheel is installed but its scripts directory is
+not on ``PATH``, this reaches the same entry point through the interpreter that
+imported it.
+
+``python3 -m fusionflux.predictor build`` still works and is what the card
+builder's own ``main`` is for, but it warns: importing this package imports
+``fusionflux.predictor`` eagerly, so runpy finds it in ``sys.modules`` before it
+executes it. Going through this module avoids that.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from fusionflux.cli import main
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

fusionflux/cli.py

@@ -0,0 +1,134 @@
+"""The ``fusionflux`` command: the confinement study first, the demo behind it.
+
+``pip install fusionflux`` used to give one console command, and it ran the
+synthetic neutron-yield pipeline. That pipeline is careful engineering and it
+supports no scientific claim; ``README.md`` says so in its own section, and its
+dataset is generated from a hand-written signal. So the single thing the package
+offered a new user was the one part of it that measures nothing.
+
+This module makes the front door the study:
+
+    fusionflux predict ...   an energy confinement time, with an interval, an
+                             extrapolation distance, and a refusal when the
+                             operating point is beyond anything measured here
+    fusionflux card          rebuild ``results/predictor.json``, which is what
+                             ``predict`` reads
+    fusionflux neutron ...   the synthetic pipeline, unchanged, one level down
+                             (checkout only: the wheel does not install it)
+
+The ``neutron`` subcommand delegates to ``neutron_yield.fusionflux_cli`` rather
+than reimplementing it, so that pipeline's arguments, defaults and behaviour are
+defined in exactly one place and cannot drift from the tests that cover them.
+Calling that module directly still works and is still tested; this only changes
+which command a fresh install puts on the path.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from fusionflux import predictor
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fusionflux",
+        description=(
+            "Tokamak energy confinement time: predict an operating point, or rebuild "
+            "the predictor card. The synthetic neutron-yield demo lives under `neutron`."
+        ),
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    predict_parser = subparsers.add_parser(
+        "predict",
+        help="Predict confinement time, with an interval and an out-of-range refusal.",
+        description=(
+            "Predicts energy confinement time for one operating point. Reports the "
+            "extrapolation distance, a calibrated interval, and an explicit warning when "
+            "the point sits beyond what this study measured, including when no "
+            "range-bounded model can reach the answer at all."
+        ),
+    )
+    for name in predictor.REQUIRED_INPUTS:
+        predict_parser.add_argument(
+            f"--{name.replace('_', '-')}",
+            type=float,
+            required=True,
+            help=f"{name} (finite and strictly positive)",
+        )
+    predict_parser.add_argument(
+        "--card",
+        default=str(predictor.DEFAULT_CARD_PATH),
+        help="Predictor card to read (default: results/predictor.json).",
+    )
+    predict_parser.add_argument(
+        "--json", action="store_true", help="Emit JSON instead of the readable report."
+    )
+
+    card_parser = subparsers.add_parser(
+        "card", help="Rebuild the predictor card from the pinned dataset."
+    )
+    card_parser.add_argument("--output", default=str(predictor.DEFAULT_CARD_PATH))
+
+    # ``REMAINDER`` so the delegated parser owns its own flags entirely: without
+    # it, an option this parser happens to define too would be captured here and
+    # never reach the pipeline that defines its meaning.
+    neutron_parser = subparsers.add_parser(
+        "neutron",
+        help="The synthetic neutron-yield demo pipeline (supports no scientific claim).",
+        description=(
+            "Delegates to neutron_yield.fusionflux_cli. This pipeline trains on "
+            "synthetic data generated from a hand-written signal, so its accuracy "
+            "numbers measure how learnable that generator is and nothing else."
+        ),
+    )
+    neutron_parser.add_argument(
+        "args", nargs=argparse.REMAINDER, help="Arguments passed through unchanged."
+    )
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = build_parser().parse_args(argv)
+
+    if args.command == "card":
+        print(f"wrote {predictor.save_card(predictor.build_service_card(), args.output)}")
+        return
+
+    if args.command == "neutron":
+        # Checkout-only, and not as a demotion. `neutron_yield` reaches its data
+        # directories through `config.PROJECT_ROOT`, which is derived from that
+        # module's own location, so an installed copy would resolve them inside
+        # site-packages and write training runs there. The wheel therefore does
+        # not ship it, and this says so instead of surfacing a bare import error.
+        try:
+            from neutron_yield.fusionflux_cli import main as neutron_main
+        except ModuleNotFoundError as error:
+            raise SystemExit(
+                "The neutron-yield pipeline is not installed by the wheel "
+                f"({error.name} is missing). It resolves its data directories "
+                "relative to its own source file, so an installed copy would read "
+                "and write inside site-packages. Clone the repository and run it "
+                "from there: see docs/neutron-yield-pipeline.md. Nothing in that "
+                "pipeline supports a scientific claim; `fusionflux predict` is the "
+                "study and it needs no checkout."
+            ) from error
+
+        neutron_main(args.args)
+        return
+
+    result = predictor.predict(
+        **{name: getattr(args, name) for name in predictor.REQUIRED_INPUTS},
+        card=predictor.load_card(args.card),
+    )
+    if args.json:
+        print(json.dumps(result.to_json(), indent=2))
+    else:
+        print(predictor.format_prediction(result))
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

fusionflux/predictor.json

@@ -0,0 +1,182 @@
+{
+  "generated_on": "2026-09-01",
+  "dataset_sha256": "67601c2da5c51f90cf6298ff499cccc74d09ac80c2b98c7dde0d8db3ebb9ac5b",
+  "n_training_rows": 6228,
+  "nominal_coverage": 0.9,
+  "model_feature_columns": [
+    "log_ip_ma",
+    "log_bt_t",
+    "log_ne_line_1e19_m3",
+    "log_p_loss_mw",
+    "log_r_m",
+    "log_inverse_aspect_ratio",
+    "log_kappa",
+    "log_m_eff_amu"
+  ],
+  "distance_feature_columns": [
+    "log_ip_ma",
+    "log_bt_t",
+    "log_ne_line_1e19_m3",
+    "log_p_loss_mw",
+    "log_r_m",
+    "log_kappa",
+    "log_inverse_aspect_ratio",
+    "log_m_eff_amu",
+    "log_a_m"
+  ],
+  "coefficients": {
+    "powerlaw_collisionless": [
+      -2.9016484433390097,
+      1.0588378196767754,
+      0.1357600483267104,
+      0.27058436642128914,
+      -0.7315326226678261,
+      1.676928781169285,
+      0.2555387339049824,
+      0.9443168653524817,
+      0.24314374146842235
+    ],
+    "powerlaw_free": [
+      -2.9038356312016065,
+      1.0804315034258738,
+      0.12016001694501567,
+      0.2166326537331674,
+      -0.688387425406081,
+      1.5791341035779596,
+      0.16673071620488358,
+      0.8975166175406656,
+      0.25641042610379533
+    ]
+  },
+  "interval_quantile": {
+    "powerlaw_collisionless": 2.838376490527002,
+    "powerlaw_free": 2.7837281921196824,
+    "ipb98y2_analytic": 3.212461708896956
+  },
+  "interval_distance_intercept": {
+    "powerlaw_collisionless": -2.045114888173274,
+    "powerlaw_free": -2.022631434539392,
+    "ipb98y2_analytic": -2.1294395081165685
+  },
+  "interval_distance_slope": {
+    "powerlaw_collisionless": -0.04025105215351508,
+    "powerlaw_free": -0.02748556544631119,
+    "ipb98y2_analytic": -0.050129759368343886
+  },
+  "distance_mean": [
+    0.14637248941480596,
+    0.6980441044410912,
+    1.6826003273110546,
+    1.8418947236029202,
+    0.7096079515122506,
+    0.43608025361888186,
+    -1.155303965685298,
+    0.6354658124628183,
+    -0.4456960141730473
+  ],
+  "distance_precision": [
+    [
+      41.50331457568594,
+      -26.270515549815787,
+      -8.5638131557017,
+      0.5470758008226411,
+      -10.39133151690429,
+      -38.71154103482346,
+      -33.4609893814481,
+      -0.3955310086525973,
+      -43.852320898356254
+    ],
+    [
+      -26.270515549815833,
+      33.03633313828385,
+      1.1735772646195255,
+      -3.6955217561400957,
+      -0.2518686768868297,
+      37.857140738093285,
+      32.56053885161475,
+      -8.208930061399926,
+      32.308670174731304
+    ],
+    [
+      -8.563813155701732,
+      1.1735772646195504,
+      14.004375935379445,
+      -4.0502627274009235,
+      8.94591684120678,
+      1.6797355231156272,
+      6.306905285930553,
+      -3.5129766590736944,
+      15.252822127138128
+    ],
+    [
+      0.547075800822676,
+      -3.6955217561401175,
+      -4.050262727400925,
+      7.126316380731758,
+      -3.9436029075366887,
+      -8.311080144723912,
+      -3.61618331933882,
+      1.4320057463930302,
+      -7.559786226876071
+    ],
+    [
+      -10.39133151690414,
+      -0.2518686768869586,
+      8.945916841206746,
+      -3.943602907536662,
+      15.317938990949708,
+      13.263892201101733,
+      -2.6929898725558457,
+      3.6058168109879043,
+      12.624949118394657
+    ],
+    [
+      -38.71154103482345,
+      37.857140738093214,
+      1.6797355231155888,
+      -8.311080144723876,
+      13.263892201101948,
+      124.24805779986187,
+      22.899513669495047,
+      -14.324932640812293,
+      36.16340587060271
+    ],
+    [
+      -33.46098938144807,
+      32.560538851614695,
+      6.306905285930513,
+      -3.6161833193387856,
+      -2.6929898725557226,
+      22.899513669495008,
+      51.09820040428655,
+      -8.294874911773647,
+      48.405210531734745
+    ],
+    [
+      -0.3955310086525263,
+      -8.208930061400002,
+      -3.5129766590736877,
+      1.4320057463930254,
+      3.605816810987901,
+      -14.324932640812401,
+      -8.294874911773736,
+      49.582000494612195,
+      -4.6890581007868
+    ],
+    [
+      -43.85232089835642,
+      32.3086701747314,
+      15.252822127138115,
+      -7.559786226876052,
+      12.624949118394866,
+      36.16340587060295,
+      48.40521053173492,
+      -4.689058100786744,
+      61.03015965013451
+    ]
+  ],
+  "training_ceiling_s": 1.32117030251898,
+  "training_hull_distance": 6.613238330602411,
+  "validated_distance_max": 11.433498320068239,
+  "validated_machine": "PBXM"
+}