websemantic 0.2.5__py3-none-any.whl

websemantic/__init__.py

@@ -0,0 +1,3 @@
+"""Software-agnostic semantic layer from intent to qualified simulated data (research prototype)."""
+
+__version__ = "0.0.1"

websemantic/adapters/__init__.py

@@ -0,0 +1 @@
+"""Thin per-software adapters. The only code allowed to call target simulator APIs."""

websemantic/adapters/lql.py

@@ -0,0 +1,118 @@
+"""Read-only LQL-Equiv execution for one explicitly fictitious course."""
+
+import csv
+import hashlib
+import importlib.util
+import json
+import math
+import sys
+import uuid
+from dataclasses import asdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from websemantic.core.validation import validate
+from websemantic.semantics import export_semantics
+
+EXPECTED_COMMIT = "dfc9a338205b8864b8e3470c4ae245b019e88844"
+# Filled from the pinned backend; line endings do not change numerical sources.
+EXPECTED_FILES = {'__init__.py': '2685b5a34b0da98c8329928f1de533ec6619178c2e2e89e92d48e231ad7a9d82', 'data/__init__.py': 'c849ce7dc4c2cd921e57faf5ffa453f8772eeed07367af69f1f9d7288f1741dd', 'data/tissues.json': '63283344abdc8147da7e112e0a5d728d1dc0bc565ad9950e9e5adccd08027f61', 'model.py': '3e0638c077e2fd9a04fedf7520a8e0c008f88d61b6e28974abd9533d681e0800', 'schedule.py': '7cffecd6e82acf536521aab1c1f58ae997a6754d43185ae6d317752c057f7dfa', 'tissues.py': '9ef2ff4d9a93b040697e5199d6902ce0ca9888474591de56126accf826a05c15'}
+
+
+def _backend(workspace, descriptor):
+    if descriptor["software"]["commit"] != EXPECTED_COMMIT:
+        raise ValueError("Révision LQL-Equiv incompatible avec cet adaptateur.")
+    root = Path(workspace) / "external/LQL-Equiv-web/src/lqlequiv"
+    for relative, expected in EXPECTED_FILES.items():
+        digest = hashlib.sha256((root / relative).read_bytes().replace(b"\r\n", b"\n")).hexdigest()
+        if digest != expected:
+            raise ValueError(f"Empreinte LQL-Equiv incorrecte : {relative}.")
+    # The library uses importlib.resources on lqlequiv.data. Reject an unrelated
+    # installed package instead of silently executing it.
+    existing = sys.modules.get("lqlequiv")
+    if existing is not None:
+        if Path(existing.__file__).resolve() != (root / "__init__.py").resolve():
+            raise ValueError("Un autre module lqlequiv est déjà chargé ; redémarrez Python.")
+        return existing
+    spec = importlib.util.spec_from_file_location(
+        "lqlequiv", root / "__init__.py", submodule_search_locations=[str(root)]
+    )
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    try:
+        spec.loader.exec_module(module)
+    except Exception:
+        for key in list(sys.modules):
+            if key == "lqlequiv" or key.startswith("lqlequiv."):
+                del sys.modules[key]
+        raise
+    return module
+
+
+def run(scenario, descriptor, workspace, output_root=None):
+    """Return native qualified indicators; never recommend a clinical dose."""
+    gate = validate(scenario, descriptor)
+    if gate.decision != "execute":
+        raise ValueError("Scénario incomplet, non accepté ou hors du profil LQL fictif.")
+    config = {name: item.value for name, item in scenario.inputs.items()}
+    if scenario.experiment.get("scenario_scope").value != "fictitious":
+        raise ValueError("Le profil accepte uniquement des scénarios fictifs de recherche.")
+    module = _backend(workspace, descriptor)
+    library = module.load_library()
+    organ = library.organ(config["organ"])
+    tumour = library.tumour_site(config["tumour_site"])
+    course = module.Course(config["dose_per_fraction"], config["n_fractions"], config["gap_days"])
+    prescription = module.Prescription(
+        courses=(course,), reference_dose=config["reference_dose"],
+        bifractionated=config["bifractionated"] == "yes",
+    )
+    result = module.compute(organ, tumour, prescription, options=module.Options())
+    native = result.courses[0]
+    oar_ok = result.oar_total_valid and not native.oar_saturated
+    tumour_ok = result.tumour_total_valid and not native.tumour_saturated
+    values = {
+        "physical_dose_gy": course.total_dose,
+        "bed_oar": native.bed_oar if result.oar_total_valid else None,
+        "bed_tumour": native.bed_tumour if result.tumour_total_valid else None,
+        "eqd_oar_total": result.eqd_oar_total if oar_ok else None,
+        "eqd_tumour_total": result.eqd_tumour_total if tumour_ok else None,
+        "ntcp_percent": result.ntcp_percent if oar_ok else None,
+        "tcp_percent": result.tcp_percent if tumour_ok else None,
+        "cancer_risk": result.cancer_risk if oar_ok else None,
+        "overall_days_oar": native.overall_days_oar,
+        "overall_days_tumour": native.overall_days_tumour,
+    }
+    if any(value is not None and not math.isfinite(value) for value in values.values()):
+        raise ValueError("Sortie LQL-Equiv non finie ; résultat refusé.")
+    flags = {
+        "oar_total_valid": result.oar_total_valid, "tumour_total_valid": result.tumour_total_valid,
+        "oar_saturated": native.oar_saturated, "tumour_saturated": native.tumour_saturated,
+    }
+    target = (Path(output_root) if output_root else Path(workspace) / "runs") / (
+        datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + "-" + uuid.uuid4().hex[:8]
+    )
+    target.mkdir(parents=True)
+    row = {**values, **flags}
+    with (target / "indicators.csv").open("w", newline="", encoding="utf-8") as handle:
+        writer = csv.DictWriter(handle, fieldnames=list(row))
+        writer.writeheader()
+        writer.writerow(row)
+    qualification = {"tables": {"indicators": {
+        "file": "indicators.csv", "aggregation": "Un calcul déterministe, un seul cursus fictif.",
+        "columns": {name: {"unit": spec.get("display_unit"), "meaning": spec["definition"]}
+                    for name, spec in descriptor["outputs"].items()},
+    }}}
+    manifest = {
+        "software": descriptor["software"], "scenario": asdict(scenario),
+        "nature": descriptor["nature"], "validity_notes": descriptor["validity_notes"],
+        "source_verification": {"method": "sha256_lf", "commit": EXPECTED_COMMIT,
+                                "files": EXPECTED_FILES},
+        "backend_options": asdict(result.options), "tissues": {"organ": asdict(organ), "tumour": asdict(tumour)},
+        "flags": flags, "output_qualification": qualification,
+        "null_policy": "EQD et probabilités dépendantes supprimées si invalides ou à la borne ; coefficient absent = null.",
+    }
+    (target / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2,
+                                                      allow_nan=False), encoding="utf-8")
+    (target / "scenario.json").write_text(json.dumps(asdict(scenario), ensure_ascii=False, indent=2), encoding="utf-8")
+    export_semantics(scenario, qualification, target, descriptor)
+    return target, values

websemantic/adapters/pyrcel.py

@@ -0,0 +1,104 @@
+"""Read-only pyrcel 2.0.0 adapter: constant updraft, one lognormal mode."""
+import hashlib
+import importlib.metadata
+import json
+import os
+import sys
+import uuid
+from dataclasses import asdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from websemantic.core.validation import validate
+from websemantic.semantics import export_semantics
+
+COMMIT = "977e9094644ec4a17d658d657094651928591c89"
+SOURCE_HASHES = {'pyrcel/aerosol.py': 'd7fc5c1d055a5d6868aae53430a7d1c0797ff4c8f73caff387aef5900fcfc9c4', 'pyrcel/console_report.py': '2f64b98e0bda566582e46a6938c142d1aed361f9f3503f17864b5f153a98bf6e', 'pyrcel/constants.py': '7d75523d46874bb1faeaff3191f7effe27dc8e6e7866976dd72dc7b6d5df52d8', 'pyrcel/distributions.py': '712f41b5e72f54c3cb243d6e7708f8cb014c9f897f97a322ffac1ba832f1eb2e', 'pyrcel/ensemble.py': '856d97c73873061dfeae77c69db5da23d3b15019864808a9180ec6dd66e2641c', 'pyrcel/equilibrate.py': 'c85e21765e25589279d438f405b92bffabeac9115b290bfb76a3f3037cc0ffe7', 'pyrcel/integrator.py': 'd08876ea45151dd0fc2119aec2d4964dc0028087a904da4d7d006723b3e85992', 'pyrcel/model.py': '6c4cf795c682e4acb4b6531b4cd1fc3bf6b0689df9d046625862f0b8ef1ad5f0', 'pyrcel/model_output.py': '7214480542a6248ee914cd0e5709fd5223faf65f022bee3d6eea147ec0f64a3d', 'pyrcel/output.py': 'd7e543ed4d73fd853421f7106b0503dd3991c93a90082adfb180d2935514c472', 'pyrcel/parcel_aux.py': '07d56e3854d16acf309666d1444136fb1c52d5652d29442482a2047eadc91735', 'pyrcel/thermo.py': '779d453484e25b708afda3517f9d8f1303dd40c5ee1ead77c9ac01119cdccd80', 'pyrcel/updraft.py': 'f299171a7da17bbf206fe82b8a15a137e84265c2268b5489d32570e0f5a499ba', 'pyrcel/util.py': '7a1e64350e830870a5582822d2c93518cf18638e723fdc3333299855760db352', 'pyrcel/_types.py': '8e72187aa2c824f7adc4c784dcad676fc082b0487a422809a4619236eeb4561a', 'pyrcel/__init__.py': 'e4a30cbc78b63ef61c5a32f852a27362096c60a97f82c075b290a85acf050639', 'pyrcel/activation/_arg2000.py': 'e107a9c8ac418b09a9e6717bf14d108280ed02c2fc0ac159403cfb45d15f2ead', 'pyrcel/activation/_common.py': '383585cd6c00f2a9a7b940e3b7fa539132aba0981ac67db5f8ad061ec374514c', 'pyrcel/activation/_mbn2014.py': 'dd96adaa9c0282324b072dcf9f51dcac72507c75c0bb85d3cb7ee3f7a9f1a79d', 'pyrcel/activation/_scheme.py': 'f3976646eba72b0b81c4538be92c92fed60c39e4ec7a05bab6e204b9174254c7', 'pyrcel/activation/__init__.py': '9dd0d8a8e2246f6cc8e7aba01bc493c2cad47c9144752908f9a1e251a207cfd2', 'pyrcel/legacy/activation.py': 'f1e283f36d95ae373f705245f46d9beffebaed071a2e4e5ea8af1b81c8b4145d', 'pyrcel/legacy/postprocess.py': '4b763e13f904cd5c0662fbd43dc52e77acbedee61a6aaf9e7d19962216653dbc', 'pyrcel/legacy/thermo.py': '94e21fd06e573ebbadcf7e0ff5b2831f4e06b08f8e02ae185aeaae89e2c61a32', 'pyrcel/legacy/vis.py': '932c8ded03dcf9daeea05a6f9a5c8021841204d92afa32e1dcf85042e9b58a0d', 'pyrcel/legacy/__init__.py': '21ec0430ebb1bfdeef5e73bdf1f4227c23d83bc4d460b94a4f658f23bd45d34a', 'pyrcel/scripts/run_parcel.py': 'd8a45a5f535f469cd8ec6d9bfbc645bd3d28bc1dfc0cdc1f4496a1ccd5d40f4d', 'pyrcel/scripts/__init__.py': 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855', 'pyrcel/test/generate_data.py': '5fcb1e9f4840c56e4834bbdfa8b3bf25dcd1fe09990f5e24998f3fa3a86165a7', 'pyrcel/test/pm_test.py': 'f0733f17aadccb1620e7c453c46647f9588c39bd7d2f5e79c165ad6671934ad8', 'pyrcel/test/test_thermo.py': '3f6f0bcb7ccec593246c5578fde57c3bcacc63729b3b1bc859da453c2f3b54d3', 'pyrcel/test/__init__.py': 'aedf1b7eccb3cfb02226205f82309a1290079ce31ed5204325781ee2bf368fc7'}
+
+
+def verify_source(backend):
+    """Verify every Python module in the reviewed package, without requiring Git."""
+    actual = {str(p.relative_to(backend)).replace("\\", "/") for p in (backend / "pyrcel").rglob("*.py")}
+    if actual != set(SOURCE_HASHES):
+        raise ValueError("Modules pyrcel inattendus ou manquants; relancez Installer.")
+    for name, expected in SOURCE_HASHES.items():
+        digest = hashlib.sha256((backend / name).read_bytes().replace(b"\r\n", b"\n")).hexdigest()
+        if digest != expected:
+            raise ValueError("Code pyrcel modifié : " + name)
+    return {"method": "sha256_lf", "commit": COMMIT, "files": SOURCE_HASHES}
+
+
+def run(scenario, descriptor, workspace, output_root=None):
+    gate = validate(scenario, descriptor)
+    if gate.decision != "execute":
+        raise ValueError("Paramètres incomplets ou hypothèses non acceptées : " + "; ".join(i.field + ": " + i.code for i in gate.issues))
+    if descriptor["software"]["commit"] != COMMIT:
+        raise ValueError("Révision pyrcel incorrecte.")
+    params = {k: v.value for k, v in scenario.inputs.items()}
+    experiment = {k: v.value for k, v in scenario.experiment.items()}
+    if experiment["output_dt"] > experiment["t_end"] or experiment["t_end"] / experiment["output_dt"] > 100000:
+        raise ValueError("Pas de sortie incompatible avec la durée ou expérience trop volumineuse.")
+    workspace = Path(workspace)
+    backend = workspace / "external/pyrcel"
+    if not backend.is_dir():
+        backend = workspace / "work/candidates/pyrcel"
+    verification = verify_source(backend)
+    # Must configure before importing JAX; refuse a previously initialised incompatible runtime.
+    os.environ["JAX_ENABLE_X64"] = "true"
+    os.environ["JAX_PLATFORMS"] = "cpu"
+    try:
+        import jax
+        importlib.import_module("diffrax")  # required solver; checked before source import
+    except ImportError as exc:
+        raise ValueError("Composants pyrcel manquants; lancez Installer.cmd pour installer le profil atmosphérique.") from exc
+    jax.config.update("jax_enable_x64", True)
+    if any(device.platform != "cpu" for device in jax.devices()):
+        raise ValueError("Ce profil nécessite JAX CPU.")
+    sys.path.insert(0, str(backend))
+    try:
+        import pyrcel as pm
+        if Path(pm.__file__).resolve() != (backend / "pyrcel/__init__.py").resolve():
+            raise ValueError("Un autre module pyrcel est déjà chargé; ouvrez une nouvelle session.")
+        import numpy as np
+        aerosol = pm.AerosolSpecies("mode1", pm.Lognorm(mu=params["mu"], sigma=params["sigma"], N=params["N"]), kappa=params["kappa"], bins=params["bins"])
+        model = pm.ParcelModel([aerosol], V=params["V"], T0=params["T0"], P0=params["P0"], S0=params["S0"], accom=params["accom"], console=False)
+        output = model.run(experiment["t_end"], output_dt=experiment["output_dt"], terminate=experiment["terminate"] == "yes", terminate_depth=experiment["terminate_depth"])
+    except ImportError as exc:
+        raise ValueError("Composants pyrcel manquants; lancez Installer.cmd pour installer le profil atmosphérique.") from exc
+    finally:
+        sys.path.remove(str(backend))
+    if not np.isfinite(output.state).all() or not np.isfinite(output.time).all():
+        raise ValueError("Sortie pyrcel non finie; résultat refusé.")
+    if len(output.time) < 2 or np.any(np.diff(output.time) <= 0):
+        raise ValueError("Support temporel invalide.")
+    frame, aerosol_frames = output.to_pandas()
+    frame = frame.reset_index()
+    frame.rename(columns={frame.columns[0]: "time_s"}, inplace=True)
+    if not np.array_equal(frame["time_s"].to_numpy(), output.time):
+        raise ValueError("Le support temporel natif n’a pas été conservé.")
+    metrics = {"maximum_supersaturation_percent": float(output.summary["S_max"]) * 100, "activated_number_cm3": float(output.Nd) / 1e6, "activated_fraction": float(output.nd_frac), "actual_end_time_s": float(output.time[-1])}
+    if not all(np.isfinite(v) for v in metrics.values()):
+        raise ValueError("Indicateurs pyrcel non finis.")
+    target = (Path(output_root) if output_root else workspace / "runs") / (datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") + "-" + uuid.uuid4().hex[:8])
+    target.mkdir(parents=True)
+    frame.to_csv(target / "trajectory.csv", index=False)
+    wet = aerosol_frames["mode1"].reset_index()
+    wet.rename(columns={wet.columns[0]: "time_s"}, inplace=True)
+    wet.to_csv(target / "wet_radii.csv", index=False)
+    import pandas as pd
+    pd.DataFrame([metrics]).to_csv(target / "kpis.csv", index=False)
+    qualification = {"trajectory": {"units": {"time_s": "s", "z": "m", "P": "Pa", "T": "K", "wv": "kg/kg", "wc": "kg/kg", "wi": "kg/kg", "S": "1"}, "temporal_support": "Exact native timestamps; nominal output_dt; final interval may be irregular"}, "wet_radii": {"time_unit": "s", "all_radius_columns_unit": "m", "definition": "Wet particle radius per size bin; not dry diameter"}, "kpis": {"maximum_supersaturation_percent": {"unit": "%", "definition": "Native solver peak locator; may differ from sampled CSV maximum"}, "activated_number_cm3": {"unit": "cm^-3", "definition": "Native hard-activation count at actual final output time"}, "activated_fraction": {"unit": "1", "definition": "Native activation fraction at actual final time"}, "actual_end_time_s": {"unit": "s", "definition": "Actual end; t_end is a maximum"}}}
+    qualification['tables'] = {
+        'trajectory': {'file': 'trajectory.csv', 'aggregation': 'Pas natif exact, dernier intervalle potentiellement irrégulier.',
+            'columns': {name: {'unit': unit, 'meaning': name + ' : sortie native de la parcelle idéale.'} for name, unit in qualification['trajectory']['units'].items()}},
+        'wet_radii': {'file': 'wet_radii.csv', 'aggregation': 'Rayons humides par classe aux instants natifs.',
+            'columns': {name: {'unit': 's' if name == 'time_s' else 'm', 'meaning': 'Temps natif' if name == 'time_s' else 'Rayon humide, pas diamètre sec'} for name in wet.columns}},
+        'kpis': {'file': 'kpis.csv', 'aggregation': 'Indicateurs natifs ; activation à la fin effective.',
+            'columns': {name: {'unit': spec['unit'], 'meaning': spec['definition']} for name, spec in qualification['kpis'].items()}}
+    }
+    export_semantics(scenario, qualification, target, descriptor)
+    versions = {name: importlib.metadata.version(name) for name in ("jax", "jaxlib", "diffrax", "equinox", "optimistix", "numpy", "pandas", "scipy")}
+    manifest = {"software": descriptor["software"], "source_verification": verification, "scenario": asdict(scenario), "nature": descriptor["nature"], "validity_notes": descriptor["validity_notes"], "output_qualification": qualification, "execution": {"python": sys.version, "versions": versions, "jax_backend": "cpu", "jax_enable_x64": bool(jax.config.jax_enable_x64), "requested_maximum_duration_s": experiment["t_end"], "actual_duration_s": metrics["actual_end_time_s"]}}
+    (target / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2, allow_nan=False), encoding="utf8")
+    (target / "scenario.json").write_text(json.dumps(asdict(scenario), ensure_ascii=False, indent=2, allow_nan=False), encoding="utf8")
+    return target, metrics

websemantic/adapters/tls.py

@@ -0,0 +1,130 @@
+"""Pinned, read-only TLS adapter with a validation gate at every run."""
+
+import hashlib
+import importlib.util
+import json
+import shutil
+import subprocess
+import uuid
+from dataclasses import asdict
+from datetime import datetime, timezone
+from pathlib import Path
+
+from websemantic.adapters.tls_outputs import qualify
+from websemantic.core.validation import validate
+from websemantic.semantics import export_semantics
+
+
+def run(scenario, descriptor, workspace, output_root=None):
+    result = validate(scenario, descriptor)
+    if result.decision != "execute":
+        raise ValueError("Configuration non validee : /show puis completer les champs.")
+    config = {k: v.value for k, v in scenario.inputs.items()}
+    exp = {k: v.value for k, v in scenario.experiment.items()}
+    if exp["freq_minutes"] not in (5, 10, 15, 30, 60):
+        raise ValueError("Pas temporel autorise : 5, 10, 15, 30, 60 minutes.")
+    if exp["n_days"] * 1440 / exp["freq_minutes"] * exp["n_runs"] > 2_000_000:
+        raise ValueError("Experience trop volumineuse pour ce PoC local.")
+    nonnegative = (
+        "max_depth_m",
+        "gradient_percent",
+        "aux_kw_per_km_tube",
+        "base_fixed_kw",
+        "traffic_level",
+        "traffic_sensitivity",
+        "pollution_sensitivity",
+        "accident_sensitivity",
+    )
+    if config["peak_width_h"] <= 0 or any(config[k] < 0 for k in nonnegative):
+        raise ValueError(
+            "Largeur des pics positive et charges/sensibilites non negatives requises."
+        )
+    if any(not 0 <= config[k] < 24 for k in ("morning_peak_hour", "evening_peak_hour")):
+        raise ValueError("Heures de pointe attendues entre 0 inclus et 24 exclu.")
+    backend = Path(workspace) / "external/tunnel-load-simulator"
+    expected_commit = "748e053e129669cf3e896d381e3c0ac01c763edd"
+    expected_digest = "8377b8a26e18d060a7a217721100512625f53fbd4d8aa9d7a3b085bd14663464"
+    if descriptor["software"]["commit"] != expected_commit:
+        raise ValueError("La revision TLS ne correspond pas au descripteur.")
+    source_path = backend / "src/tunnel_load_simulator/simulator.py"
+    source_bytes = source_path.read_bytes().replace(b"\r\n", b"\n")
+    digest = hashlib.sha256(source_bytes).hexdigest()
+    if digest != expected_digest:
+        raise ValueError("Empreinte du code TLS incorrecte; execution refusee.")
+    verification = {"method": "sha256_lf", "commit": expected_commit,
+                    "file": "src/tunnel_load_simulator/simulator.py", "sha256": digest,
+                    "scope": "Executed simulator module; CRLF normalized to LF."}
+    if (backend / ".git").exists() and shutil.which("git"):
+        commit = subprocess.run(
+            ["git", "-C", str(backend), "rev-parse", "HEAD"],
+            capture_output=True, text=True, check=True,
+        ).stdout.strip()
+        if commit != expected_commit:
+            raise ValueError("La revision TLS ne correspond pas au descripteur.")
+        dirty = subprocess.run(
+            ["git", "-C", str(backend), "status", "--porcelain", "--untracked-files=no"],
+            capture_output=True, text=True, check=True,
+        ).stdout
+        if dirty:
+            raise ValueError("Le backend comporte des modifications suivies; execution refusee.")
+        verification["method"] = "git_and_sha256_lf"
+    import pandas as pd
+
+    spec = importlib.util.spec_from_file_location(
+        "websemantic_pinned_tls", backend / "src/tunnel_load_simulator/simulator.py"
+    )
+    module = importlib.util.module_from_spec(spec)
+    import sys
+
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    outputs = module.run_monte_carlo(
+        module.TunnelConfig(**config),
+        pd.Timestamp(exp["start_date"]),
+        exp["n_days"],
+        exp["freq_minutes"],
+        exp["n_runs"],
+        exp["base_seed"],
+    )
+    # Add explicit operational provenance without changing numerical indicators.
+    outputs["kpis"]["base_seed"] = exp["base_seed"]
+    # Preserve native TLS trajectories; derive daily energy from its first trajectory.
+    outputs["daily"] = (
+        outputs["representative"].set_index("timestamp")
+        .resample("1D").agg({"energy_kwh": "sum", "power_kw": "mean"})
+        .rename(columns={"power_kw": "mean_kw"}).reset_index()
+    )
+    qualification = qualify(outputs, exp)
+    target = (
+        (Path(output_root) if output_root else Path(workspace) / "runs")
+        / (
+            datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+            + "-"
+            + uuid.uuid4().hex[:8]
+        )
+    )
+    target.mkdir(parents=True)
+    for name, table in outputs.items():
+        table.to_csv(target / f"{name}.csv", index=False)
+    manifest = {
+        "software": descriptor["software"],
+        "source_verification": verification,
+        "scenario": asdict(scenario),
+        "nature": descriptor["nature"],
+        "uncertainty": descriptor["uncertainty"],
+        "validity_notes": descriptor["validity_notes"],
+        "outputs": list(outputs),
+        "output_qualification": qualification,
+        "note": "Synthetic simulation outputs.",
+    }
+    (target / "manifest.json").write_text(
+        json.dumps(manifest, ensure_ascii=False, indent=2, allow_nan=False),
+        encoding="utf-8",
+    )
+    export_semantics(scenario, qualification, target, descriptor)
+    medians = (
+        outputs["kpis"][["total_mwh", "annualized_mwh", "peak_kw", "load_factor", "specific_kwh_m_year"]]
+        .median()
+        .to_dict()
+    )
+    return target, medians

websemantic/adapters/tls_outputs.py

@@ -0,0 +1,70 @@
+"""Output definitions checked against the pinned TLS implementation."""
+
+
+def column_metadata(name, table):
+    if table == "daily" and name == "energy_kwh":
+        return {"quantity": "energy", "unit": "kWh", "meaning": "Somme des énergies des pas natifs de la journée, réalisation 0."}
+    if table == "daily" and name == "mean_kw":
+        return {"quantity": "power", "unit": "kW", "meaning": "Moyenne des puissances des pas natifs de la journée, réalisation 0."}
+    if name.endswith("_kw") or (table == "envelope" and name in ("median", "p10", "p90", "mean")):
+        return {"quantity": "power", "unit": "kW", "meaning": "Puissance électrique calculée."}
+    definitions = {
+        "energy_kwh": ("energy", "kWh", "Énergie du pas : power_kw × freq_minutes / 60."),
+        "total_mwh": ("energy", "MWh", "Énergie de toute la période : somme des energy_kwh / 1000."),
+        "annualized_mwh": ("annualized_energy", "MWh/an", "Extrapolation : total_mwh × 365 / n_days ; pas une année observée."),
+        "specific_kwh_m_year": ("length_normalized_annualized_energy", "kWh/(m·an)", "annualized_mwh × 1000 / length_m ; ensemble des tubes, par mètre de longueur du tunnel, pas par mètre-tube."),
+        "load_factor": ("power_ratio", "1", "mean_kw / peak_kw par réalisation ; sans dimension, 0,6 équivaut à 60 %."),
+        "timestamp": ("time", "ISO 8601", "Horodatage sans fuseau horaire déclaré ; aucune localisation déduite."),
+        "hour_int": ("hour_of_day", "h", "Heure du jour, de 0 à 23 ; pas une durée."),
+        "dayofweek": ("weekday_index", "1", "Indice : lundi 0, dimanche 6."),
+        "traffic_index": ("relative_traffic_index", "1", "Indice relatif de trafic ; pas un nombre de véhicules par jour."),
+        "pollution_event": ("event_flag", "1", "Indicateur binaire d'événement de pollution simulé."),
+        "accident_event": ("event_flag", "1", "Indicateur binaire d'accident simulé."),
+        "n_pollution_events": ("transition_count", "1", "Nombre de transitions 0 vers 1 dans la série pollution_event ; un événement actif au premier pas n'est pas compté."),
+        "n_accident_events": ("transition_count", "1", "Nombre de transitions 0 vers 1 dans la série accident_event ; un événement actif au premier pas n'est pas compté."),
+        "run": ("identifier", None, "Identifiant de réalisation Monte Carlo, à partir de 0."),
+        "base_seed": ("identifier", None, "Graine de base fixe de l’expérience ; 42 par défaut, modifiable explicitement."),
+        "seed": ("identifier", None, "Graine pseudo-aléatoire : base_seed + run."),
+        "season": ("category", None, "Saison du calendrier simulé ; ne prouve pas une couverture annuelle."),
+        "day_type": ("category", None, "Jour de semaine ou week-end du calendrier simulé."),
+    }
+    if name not in definitions:
+        raise ValueError(f"Sortie TLS non qualifiée : {table}.{name}")
+    quantity, unit, meaning = definitions[name]
+    return {"quantity": quantity, "unit": unit, "meaning": meaning}
+
+
+def qualify(outputs, experiment):
+    aggregations = {
+        "daily": "Agrégation journalière de la réalisation 0 : somme de l'énergie et moyenne de la puissance ; pas une médiane Monte Carlo. Les dates suivent le calendrier sans fuseau déclaré.",
+        "representative": "Réalisation 0 au pas natif ; exemple de trajectoire, pas la médiane.",
+        "kpis": "Une ligne par réalisation sur toute la période simulée.",
+        "envelope": "Puissances moyennées par heure dans chaque réalisation, puis statistiques entre réalisations. p10/p90 sont des quantiles empiriques, pas un intervalle de confiance.",
+        "season_profiles": "Puissance moyenne par saison et heure du jour, dans chaque réalisation, uniquement sur les jours simulés.",
+    }
+    return {
+        "schema_version": "tls-output-qualification-1",
+        "data_origin": "synthetic_simulation",
+        "spatial_scope": "Ensemble du tunnel et de ses tubes ; aucune coordonnée géographique déclarée.",
+        "temporal_scope": {
+            "start_date": experiment["start_date"],
+            "duration_days": experiment["n_days"],
+            "native_step_minutes": experiment["freq_minutes"],
+            "timezone": None,
+        },
+        "monte_carlo": {"realizations": experiment["n_runs"], "base_seed": experiment["base_seed"]},
+        "fitness_for_use": {
+            "admitted": "Exploration des sorties du modèle sous les hypothèses déclarées.",
+            "excluded": "Certification, consommation réelle sans calibration, classement fort/faible non paramétré.",
+            "evidence_status": "Contrôles logiciels et calculs ; aucune validation terrain.",
+        },
+        "tables": {
+            name: {
+                "file": f"{name}.csv",
+                "aggregation": aggregations[name],
+                "rows": len(table),
+                "columns": {column: column_metadata(column, name) for column in table.columns},
+            }
+            for name, table in outputs.items()
+        },
+    }