simudyne-pulse 0.9.0__tar.gz → 0.9.0.dev2__tar.gz

{simudyne_pulse-0.9.0/src/simudyne_pulse.egg-info → simudyne_pulse-0.9.0.dev2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simudyne-pulse
-Version: 0.9.0
+Version: 0.9.0.dev2
 Summary: Python SDK for the Simudyne Pulse synthetic market data API
 Author-email: Simudyne <support@simudyne.com>
 License-Expression: MIT

{simudyne_pulse-0.9.0 → simudyne_pulse-0.9.0.dev2}/pyproject.toml

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

{simudyne_pulse-0.9.0 → simudyne_pulse-0.9.0.dev2}/src/simudyne/resources/validation.py

@@ -70,10 +70,13 @@ _AREA_FLAGS = (
 )
 
 #: ``lob`` marks the frames as L2 snapshots, which switches off anything
-#: 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")
+#: needing the message stream; ``resample_method`` and ``sessions`` say how the
+#: historical day is put onto the generated frames' grid; ``plots`` is False,
+#: True, or a list of plot ids.
+_EXTRA_FIELDS = ("lob", "resample_method", "sessions", "plots")
+
+#: How the historical day can be put onto the generated grid in lob mode.
+RESAMPLE_METHODS = ("last", "pulseflow")
 
 
 def _frame_to_parquet(entry, index: int):
@@ -257,8 +260,8 @@ class ValidationResource:
         fid=None,
         mind=None,
         lob=None,
-        sample_period=None,
-        match_generated_sample=None,
+        resample_method=None,
+        sessions=None,
         n_levels: int = 10,
         plots=None,
     ) -> dict:
@@ -318,15 +321,22 @@ class ValidationResource:
         lob : bool, optional
             The frames are L2 snapshots. Anything needing the message stream
             is skipped, with the reason reported in
-            ``metadata["areas_skipped"]``.
-        sample_period : str, optional
-            The grid the book is resampled onto in lob mode, e.g. ``"1s"``.
-            Omitted, the cadence is read off your generated frames; if those
-            are event-level there is no grid to match and nothing is
-            resampled.
-        match_generated_sample : bool, optional
-            Match the generated frames' grid even when ``sample_period`` is
-            given.
+            ``metadata["areas_skipped"]``. The historical day is resampled
+            onto your generated frames' own grid, read off them (e.g. one
+            second); event-level frames are left as they are.
+        resample_method : {"last", "pulseflow"}, optional
+            How the historical day is put onto that grid in lob mode.
+            ``"last"`` (the default when unset) keeps the last event in each
+            interval. ``"pulseflow"`` reproduces PulseFLOW's training-data
+            preprocessing exactly — the first event per interval on a fixed
+            session grid, forward-filled to the session edges, sizes clipped
+            at each session's 99th percentile — so a PulseFLOW run is scored
+            against the data it was trained on. Needs ``sessions``.
+        sessions : list of [start_h, start_m, end_h, end_m], optional
+            The model's trading sessions, for ``resample_method="pulseflow"``
+            only; the end is exclusive. ``[[8, 0, 16, 30]]`` for LSE
+            continuous trading, ``[[9, 30, 12, 0], [13, 0, 16, 0]]`` for
+            HKEX.
         n_levels : int, default 10
             Book levels to measure over.
         plots : bool or list of str, optional
@@ -408,14 +418,16 @@ class ValidationResource:
         ...     plots=["statistical.radar", "stylised_facts.overall"],
         ... )
 
-        L2 snapshots resampled onto a one-second grid:
+        A PulseFLOW run on its one-second grid, scored against the historical
+        day downsampled exactly as PulseFLOW's training data was:
 
         >>> job = client.validation.run(
         ...     symbol="BARC", date="2025-09-02",
         ...     provider="bmll", exchange="lse",
-        ...     sim_files=["book_snapshots.parquet"],
+        ...     sim_files=["pulseflow_sample.parquet"],
         ...     lob=True,
-        ...     sample_period="1s",
+        ...     resample_method="pulseflow",
+        ...     sessions=[[8, 0, 16, 30]],
         ... )
         """
         if sim_ids is None and sim_files is None:
@@ -433,6 +445,14 @@ class ValidationResource:
             )
         if n_levels < 1:
             raise ValueError("n_levels must be at least 1")
+        if resample_method is not None and resample_method not in RESAMPLE_METHODS:
+            raise ValueError(f"resample_method must be one of {RESAMPLE_METHODS}")
+        if resample_method == "pulseflow" and not sessions:
+            raise ValueError(
+                "resample_method='pulseflow' needs sessions, e.g. [[8, 0, 16, 30]]"
+            )
+        if sessions and resample_method != "pulseflow":
+            raise ValueError("sessions only applies with resample_method='pulseflow'")
 
         config = _build_config(
             n_levels,
@@ -443,8 +463,8 @@ class ValidationResource:
             fid=fid,
             mind=mind,
             lob=lob,
-            sample_period=sample_period,
-            match_generated_sample=match_generated_sample,
+            resample_method=resample_method,
+            sessions=sessions,
             plots=plots,
         )
 

{simudyne_pulse-0.9.0 → simudyne_pulse-0.9.0.dev2/src/simudyne_pulse.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simudyne-pulse
-Version: 0.9.0
+Version: 0.9.0.dev2
 Summary: Python SDK for the Simudyne Pulse synthetic market data API
 Author-email: Simudyne <support@simudyne.com>
 License-Expression: MIT

{simudyne_pulse-0.9.0 → simudyne_pulse-0.9.0.dev2}/tests/test_validation.py

@@ -106,14 +106,42 @@ class TestMetricFlags:
         "flag,value",
         [("statistical", False), ("stylised_facts", True), ("impact", False),
          ("volume_correlation", True), ("fid", False), ("mind", True),
-         ("lob", True), ("sample_period", "100ms"),
-         ("match_generated_sample", True),
+         ("lob", True), ("resample_method", "last"),
          ("plots", ["statistical.radar"])],
     )
     def test_explicit_options_are_forwarded(self, flag, value):
         client, _ = _run([{"job_id": "v1"}], **{flag: value})
         assert client.calls[0][2]["json"]["config"][flag] == value
 
+    def test_pulseflow_resampling_is_forwarded_with_its_sessions(self):
+        client, _ = _run([{"job_id": "v1"}], lob=True, resample_method="pulseflow",
+                         sessions=[[8, 0, 16, 30]])
+        config = client.calls[0][2]["json"]["config"]
+        assert config["resample_method"] == "pulseflow"
+        assert config["sessions"] == [[8, 0, 16, 30]]
+
+    @pytest.mark.parametrize(
+        "kwargs,match",
+        [({"resample_method": "mean"}, "resample_method must be one of"),
+         ({"resample_method": "pulseflow"}, "needs sessions"),
+         ({"sessions": [[8, 0, 16, 30]]}, "only applies"),
+         ({"resample_method": "last", "sessions": [[8, 0, 16, 30]]}, "only applies")],
+    )
+    def test_bad_resampling_is_refused_before_any_request(self, kwargs, match):
+        client = FakeClient()
+        with pytest.raises(ValueError, match=match):
+            ValidationResource(client).run(sim_ids=SIM_IDS, **IDENTITY, **kwargs)
+        assert client.calls == []
+
+    def test_the_old_grid_options_are_gone(self):
+        """Replaced by resample_method: in lob mode the grid is read off the
+        generated frames."""
+        for dead in ("sample_period", "match_generated_sample"):
+            with pytest.raises(TypeError):
+                ValidationResource(FakeClient()).run(
+                    sim_ids=SIM_IDS, **IDENTITY, **{dead: "1s"}
+                )
+
     def test_the_legacy_aliases_are_gone(self):
         """run_* and l2_only/plot_data were two names for one thing."""
         for dead in ("run_metrics", "run_impact", "run_stylised_facts",