simudyne-pulse 0.7.0.dev8__tar.gz → 0.7.0.dev10__tar.gz

{simudyne_pulse-0.7.0.dev8 → simudyne_pulse-0.7.0.dev10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simudyne-pulse
-Version: 0.7.0.dev8
+Version: 0.7.0.dev10
 Summary: Python SDK for the Simudyne Pulse synthetic market data API
 Author-email: Simudyne <support@simudyne.com>
 License-Expression: MIT
@@ -59,6 +59,35 @@ pip install --pre simudyne-pulse
 Only use dev builds for testing unreleased changes; they are not guaranteed
 stable. Merge `dev` into `prod` to promote those changes to a stable release.
 
+### Comparing named populations
+
+Simulations are often not one population but several — a foundation model and
+an ABM, or two versions of a model. Name them and the results compare them
+instead of averaging them together:
+
+```python
+job = client.validation.run(
+    symbol="TSCO", date="2026-06-23", provider="bmll", exchange="lse",
+    sim_ids={"fm": fm_ids, "abm": abm_ids},
+    plots=["statistical.radar", "stylised_facts.overall",
+           "volume_correlation.overall"],
+)
+result = client.validation.get_job(job["job_id"], plot_dir="figs")
+result["distances"]["fm"]["spread"]["l1"]
+result["stylised_fact_verdicts"]["heavy_tails"]["simulated"]["abm"]
+```
+
+`distances`, `distributions`, the verdicts and the FID/MIND scores come back
+keyed by name; the radar draws a polygon per population, the verdict table a
+column each, and volume correlation puts historical first then a heatmap per
+population. `sim_files` groups the same way.
+
+A plain list is one unnamed population and keeps the flat shape exactly as
+before. The historical day is measured once however many groups there are.
+
+`plot_all=True` draws everything the enabled areas can draw, not just the
+summaries.
+
 ### Working from a checkout
 
 To run the SDK from source — editing it, or using unreleased changes — install

{simudyne_pulse-0.7.0.dev8 → simudyne_pulse-0.7.0.dev10}/README.md

@@ -33,6 +33,35 @@ pip install --pre simudyne-pulse
 Only use dev builds for testing unreleased changes; they are not guaranteed
 stable. Merge `dev` into `prod` to promote those changes to a stable release.
 
+### Comparing named populations
+
+Simulations are often not one population but several — a foundation model and
+an ABM, or two versions of a model. Name them and the results compare them
+instead of averaging them together:
+
+```python
+job = client.validation.run(
+    symbol="TSCO", date="2026-06-23", provider="bmll", exchange="lse",
+    sim_ids={"fm": fm_ids, "abm": abm_ids},
+    plots=["statistical.radar", "stylised_facts.overall",
+           "volume_correlation.overall"],
+)
+result = client.validation.get_job(job["job_id"], plot_dir="figs")
+result["distances"]["fm"]["spread"]["l1"]
+result["stylised_fact_verdicts"]["heavy_tails"]["simulated"]["abm"]
+```
+
+`distances`, `distributions`, the verdicts and the FID/MIND scores come back
+keyed by name; the radar draws a polygon per population, the verdict table a
+column each, and volume correlation puts historical first then a heatmap per
+population. `sim_files` groups the same way.
+
+A plain list is one unnamed population and keeps the flat shape exactly as
+before. The historical day is measured once however many groups there are.
+
+`plot_all=True` draws everything the enabled areas can draw, not just the
+summaries.
+
 ### Working from a checkout
 
 To run the SDK from source — editing it, or using unreleased changes — install

{simudyne_pulse-0.7.0.dev8 → simudyne_pulse-0.7.0.dev10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simudyne-pulse"
-version = "0.7.0-dev.8"
+version = "0.7.0-dev.10"
 description = "Python SDK for the Simudyne Pulse synthetic market data API"
 readme = "README.md"
 license = "MIT"

{simudyne_pulse-0.7.0.dev8 → simudyne_pulse-0.7.0.dev10}/src/simudyne/resources/validation.py

@@ -64,7 +64,8 @@ _AREA_FLAGS = (
 #: needing the message stream; ``sample_period`` and ``match_generated_sample``
 #: set the grid the book is resampled onto; ``plots`` is False, True, or a list
 #: of plot ids.
-_EXTRA_FIELDS = ("lob", "sample_period", "match_generated_sample", "plots")
+_EXTRA_FIELDS = ("lob", "sample_period", "match_generated_sample", "plots",
+                 "plot_all")
 
 
 def _frame_to_parquet(entry, index: int):
@@ -172,6 +173,7 @@ class ValidationResource:
         match_generated_sample=None,
         n_levels: int = 10,
         plots=None,
+        plot_all: bool = False,
     ) -> dict:
         """Submit a validation job.
 
@@ -192,13 +194,17 @@ class ValidationResource:
             ``(symbol, provider, exchange)`` is the identity, not the symbol.
         exchange : str
             Exchange, e.g. ``"lse"`` or ``"hkex_securities"``.
-        sim_ids : list of str, optional
-            Platform simulation IDs, 1 to 25. Exactly one of ``sim_ids`` or
-            ``sim_files`` is required.
-        sim_files : list, optional
+        sim_ids : list of str or dict, optional
+            Platform simulation IDs, 1 to 25. A flat list is one unnamed
+            population. A mapping — ``{"fm": [...], "abm": [...]}`` — compares
+            the named populations: distances, distributions, verdicts and
+            FID/MIND scores come back keyed by name, and the summary figures
+            draw one series per name instead of averaging them together.
+            Exactly one of ``sim_ids`` or ``sim_files`` is required.
+        sim_files : list or dict, optional
             Your own simulated runs, up to 25: paths, ``(filename, bytes)``
-            pairs, or polars / pandas DataFrames in pulse format. The
-            historical side is fetched for you.
+            pairs, or polars / pandas DataFrames in pulse format. Grouped the
+            same way as ``sim_ids``. The historical side is fetched for you.
         ticksize : float, default 1.0
             Minimum price increment. Should match the instrument.
         statistical, stylised_facts, impact, volume_correlation, fid, mind : bool, optional
@@ -221,6 +227,10 @@ class ValidationResource:
             ``None`` or ``False`` for none, ``True`` for every figure, or plot
             ids such as ``["statistical.radar", "stylised_facts.overall"]``.
             Rendered server-side; :meth:`get_job` writes them to disk.
+        plot_all : bool, default False
+            Draw everything the enabled areas can draw — every distribution and
+            every stylised fact, not just the summaries. An area switched off
+            still draws nothing, so this means "all of what ran".
 
         Returns
         -------
@@ -239,7 +249,12 @@ class ValidationResource:
             raise ValueError("sim_ids must not be empty")
         if sim_files is not None and not sim_files:
             raise ValueError("sim_files must not be empty")
-        count = len(sim_ids if sim_ids is not None else sim_files)
+        given = sim_ids if sim_ids is not None else sim_files
+        count = (
+            sum(len(v) for v in given.values())
+            if isinstance(given, dict)
+            else len(given)
+        )
         if count > MAX_SIM_FILES:
             raise ValueError(f"Maximum {MAX_SIM_FILES} simulations per validation job")
         if ticksize <= 0:
@@ -259,6 +274,7 @@ class ValidationResource:
             sample_period=sample_period,
             match_generated_sample=match_generated_sample,
             plots=plots,
+            plot_all=plot_all or None,
         )
 
         if sim_ids is not None:
@@ -270,7 +286,11 @@ class ValidationResource:
                     "date": date,
                     "provider": provider,
                     "exchange": exchange,
-                    "sim_ids": list(sim_ids),
+                    "sim_ids": (
+                        {k: list(v) for k, v in sim_ids.items()}
+                        if isinstance(sim_ids, dict)
+                        else list(sim_ids)
+                    ),
                     "ticksize": ticksize,
                     "config": config,
                 },
@@ -278,10 +298,24 @@ class ValidationResource:
         else:
             # Three-tuple parts: the content type matters to the server's
             # multipart parser, so it is sent explicitly.
+            # Grouped uploads travel flat with the grouping beside them, the
+            # same way sim_ids do — multipart has no nesting.
+            if isinstance(sim_files, dict):
+                flat, groups, offset = [], {}, 0
+                for name, runs in sim_files.items():
+                    runs = list(runs)
+                    groups[name] = list(range(offset, offset + len(runs)))
+                    offset += len(runs)
+                    flat.extend(runs)
+            else:
+                flat, groups = list(sim_files), None
+
             files = [
                 ("sim_files", (*_frame_to_parquet(entry, i), "application/octet-stream"))
-                for i, entry in enumerate(sim_files)
+                for i, entry in enumerate(flat)
             ]
+            if groups:
+                config = {**config, "sim_groups": groups}
             submitted = self._client._request(
                 "POST",
                 UPLOAD_PATH,

{simudyne_pulse-0.7.0.dev8 → simudyne_pulse-0.7.0.dev10}/src/simudyne_pulse.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simudyne-pulse
-Version: 0.7.0.dev8
+Version: 0.7.0.dev10
 Summary: Python SDK for the Simudyne Pulse synthetic market data API
 Author-email: Simudyne <support@simudyne.com>
 License-Expression: MIT
@@ -59,6 +59,35 @@ pip install --pre simudyne-pulse
 Only use dev builds for testing unreleased changes; they are not guaranteed
 stable. Merge `dev` into `prod` to promote those changes to a stable release.
 
+### Comparing named populations
+
+Simulations are often not one population but several — a foundation model and
+an ABM, or two versions of a model. Name them and the results compare them
+instead of averaging them together:
+
+```python
+job = client.validation.run(
+    symbol="TSCO", date="2026-06-23", provider="bmll", exchange="lse",
+    sim_ids={"fm": fm_ids, "abm": abm_ids},
+    plots=["statistical.radar", "stylised_facts.overall",
+           "volume_correlation.overall"],
+)
+result = client.validation.get_job(job["job_id"], plot_dir="figs")
+result["distances"]["fm"]["spread"]["l1"]
+result["stylised_fact_verdicts"]["heavy_tails"]["simulated"]["abm"]
+```
+
+`distances`, `distributions`, the verdicts and the FID/MIND scores come back
+keyed by name; the radar draws a polygon per population, the verdict table a
+column each, and volume correlation puts historical first then a heatmap per
+population. `sim_files` groups the same way.
+
+A plain list is one unnamed population and keeps the flat shape exactly as
+before. The historical day is measured once however many groups there are.
+
+`plot_all=True` draws everything the enabled areas can draw, not just the
+summaries.
+
 ### Working from a checkout
 
 To run the SDK from source — editing it, or using unreleased changes — install

{simudyne_pulse-0.7.0.dev8 → simudyne_pulse-0.7.0.dev10}/tests/test_validation.py

@@ -230,3 +230,56 @@ class TestSimulatedFrameShapes:
         frames = [pd.DataFrame({"a": [1]}), pd.DataFrame({"a": [2]})]
         names = [f[1][0] for f in self._files_sent(frames)]
         assert names == ["sim_0.parquet", "sim_1.parquet"]
+
+
+class TestNamedPopulations:
+    """Runs can be named so the results compare populations, not an average."""
+
+    def test_grouped_sim_ids_go_as_a_mapping(self):
+        client = FakeClient([{"job_id": "v1"}])
+        ValidationResource(client).run(
+            sim_ids={"fm": ["a"], "abm": ["b", "c"]}, **IDENTITY
+        )
+        assert client.calls[0][2]["json"]["sim_ids"] == {
+            "fm": ["a"],
+            "abm": ["b", "c"],
+        }
+
+    def test_the_total_is_what_is_capped(self):
+        client = FakeClient()
+        with pytest.raises(ValueError, match="Maximum 25"):
+            ValidationResource(client).run(
+                sim_ids={"a": ["x"] * 13, "b": ["y"] * 13}, **IDENTITY
+            )
+        assert client.calls == []
+
+    def test_grouped_uploads_travel_flat_with_the_grouping_beside_them(self):
+        """Multipart has no nesting, so the groups go in the config."""
+        client = FakeClient([{"job_id": "v1"}])
+        ValidationResource(client).run(
+            sim_files={"fm": [("a.parquet", b"x")],
+                       "abm": [("b.parquet", b"y"), ("c.parquet", b"z")]},
+            **IDENTITY,
+        )
+        kwargs = client.calls[0][2]
+        assert len(kwargs["files"]) == 3
+        assert json.loads(kwargs["data"]["config"])["sim_groups"] == {
+            "fm": [0], "abm": [1, 2]
+        }
+
+    def test_an_ungrouped_upload_carries_no_grouping(self):
+        client = FakeClient([{"job_id": "v1"}])
+        ValidationResource(client).run(
+            sim_files=[("a.parquet", b"x")], **IDENTITY
+        )
+        assert "sim_groups" not in json.loads(client.calls[0][2]["data"]["config"])
+
+
+class TestPlotAll:
+    def test_it_is_forwarded(self):
+        client, _ = _run([{"job_id": "v1"}], plot_all=True)
+        assert client.calls[0][2]["json"]["config"]["plot_all"] is True
+
+    def test_it_is_omitted_when_not_asked_for(self):
+        client, _ = _run([{"job_id": "v1"}])
+        assert "plot_all" not in client.calls[0][2]["json"]["config"]