Jarvis-HEP-Sampler 1.0.0__tar.gz

jarvis_hep_sampler-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pengxuan Zhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jarvis_hep_sampler-1.0.0/MANIFEST.in

@@ -0,0 +1,4 @@
+recursive-include docs *.md
+recursive-include examples *.py *.yaml
+global-exclude .DS_Store
+recursive-include tests *.py

jarvis_hep_sampler-1.0.0/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.4
+Name: Jarvis-HEP-Sampler
+Version: 1.0.0
+Summary: Plug-in SDK for user-defined Jarvis-HEP samplers
+Author: Pengxuan Zhu
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Pengxuan-Zhu-Phys/Jarvis-HEP-Sampler
+Project-URL: Repository, https://github.com/Pengxuan-Zhu-Phys/Jarvis-HEP-Sampler
+Project-URL: Issues, https://github.com/Pengxuan-Zhu-Phys/Jarvis-HEP-Sampler/issues
+Keywords: HEP,physics,sampling,Jarvis-HEP,plugin
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: jsonschema>=4.18
+Dynamic: license-file
+
+# Jarvis-HEP-Sampler
+
+Jarvis-HEP-Sampler is the plug-in SDK for user-defined samplers in the Jarvis ecosystem.
+
+A user writes a sampler as one Python file, loads it once, and from then on uses it in a task card exactly like a built-in method. No Jarvis-HEP source code is changed. The plug-in's points go through the same Redis queue, logging and monitor as built-in samplers. The sampler-enabled HEP branch binds each scan to an exact source snapshot and checks scientific settings before resume. Project packages include the source and its full hash; fetch verifies it and prints a load command.
+
+```text
+Jarvis sampler init MyLatinHypercube       # fixed template -> ./MyLatinHypercube.py
+#   edit draw() (and optionally OPTIONS_SCHEMA)
+Jarvis sampler check MyLatinHypercube.py   # optional offline check, no Redis
+Jarvis sampler load MyLatinHypercube.py    # snapshot into ~/.jarvis/samplers; reloading replaces it
+Jarvis run task.yaml                     # Sampling.Method: MyLatinHypercube
+```
+
+The `Jarvis sampler` commands are part of Jarvis-HEP and use this package. They are available in the sampler-enabled Jarvis-HEP development branch. The SDK also supports offline Python use (see [Python API](#python-api)).
+
+## Scope
+
+Jarvis-HEP-Sampler owns the plug-in format:
+
+- the fixed template
+- the `PLUGIN` metadata rules and method-name rule
+- loading a plug-in file
+- the user registry in `~/.jarvis/samplers/`
+- the deterministic random streams
+- the output contract (shape, real, finite, inside `[0, 1]`)
+- the `log` facade handed to plug-ins
+- the offline driver and conformance checks
+
+Jarvis-HEP owns the runtime:
+
+- the `Jarvis sampler` CLI
+- task-card validation
+- the run preflight
+- mapping unit-cube points to physical parameters, and `selection`
+- Sample UUIDs, Redis, Workers and the Archiver
+- checkpoints and resume
+- the sampler log, telemetry and monitor
+- `Jarvis man` and project packing
+
+This package never imports Jarvis-HEP, Redis or Portal.
+
+## Complete package installation
+
+Version 1.0.0. Install from PyPI:
+
+```bash
+python -m pip install "Jarvis-HEP-Sampler==1.0.0"
+```
+
+From this repository:
+
+```bash
+python -m pip install .
+```
+
+Dependencies: NumPy and jsonschema. A sampler-enabled Jarvis-HEP installs this SDK with `Jarvis-HEP-Sampler>=1.0.0,<2`.
+
+The end-to-end user tutorial lives in Jarvis-Books, in the TeX manual chapter **Jarvis-HEP-Sampler: Implementing Your Own Sampler** (`TeX/Jarvis-HEP-V2 manual`).
+
+## A plug-in
+
+```python
+"""Latin hypercube design: one point per stratum in every variable."""
+
+import numpy as np
+
+PLUGIN = {
+    "api_version": 1,
+    "method": "MyLatinHypercube",
+    "version": "0.1.0",
+    "profile": "independent",
+}
+
+OPTIONS_SCHEMA = {  # optional
+    "type": "object",
+    "properties": {"centered": {"type": "boolean"}},
+    "additionalProperties": False,
+}
+
+
+def prepare(setup):
+    rng = setup.rng()
+    perms = np.stack([rng.permutation(setup.point_number) for _ in range(setup.dimension)])
+    return {"perms": perms, "centered": bool(setup.options.get("centered", False))}
+
+
+def draw(context, rng, plan):
+    strata = plan["perms"][:, context.candidate_index]
+    offset = 0.5 if plan["centered"] else rng.random(context.dimension)
+    return (strata + offset) / context.point_number
+```
+
+```yaml
+Sampling:
+  Method: MyLatinHypercube
+  Variables:
+    - name: mass
+      distribution: {type: Flat, parameters: {min: 100.0, max: 1000.0}}
+  Bounds:
+    seed: 7
+    point_number: 10000
+    centered: false
+```
+
+The full contract is in [Plug-in authoring](docs/development/PLUGIN_AUTHORING.md).
+
+A complete runnable card is provided in
+[examples/MyLatinHypercube.task.yaml](examples/MyLatinHypercube.task.yaml).
+It uses Jarvis-HEP's bundled Eggbox demonstration operator:
+
+```bash
+Jarvis sampler check examples/MyLatinHypercube.py --card examples/MyLatinHypercube.task.yaml
+Jarvis sampler load examples/MyLatinHypercube.py
+Jarvis validate examples/MyLatinHypercube.task.yaml
+Jarvis check examples/MyLatinHypercube.task.yaml
+Jarvis run examples/MyLatinHypercube.task.yaml
+```
+
+`Jarvis sampler check` is the offline file check and does not require `load`. `Jarvis check` is the calculator smoke: its identity, bound source and checkpoint stay under `DATABASE/test` and `checkpoints/<scan>/<Method>/check/`, and the formal scan's science database and resume checkpoint stay in place.
+
+Reloading the same method updates future scans. Removing the registration
+preserves an existing scan's bound source and its normal `Jarvis run ... --resume`
+workflow.
+
+## Python API
+
+```python
+from jarvis_hep_sampler import SamplerRegistry, write_template
+from jarvis_hep_sampler.testing import check_plugin, run_offline
+
+path = write_template("MyLatinHypercube")                  # Jarvis sampler init
+report = check_plugin(path, dimension=2, options={})     # Jarvis sampler check
+for name, result in report.rows():
+    print(f"{name:14} {result}")
+
+run = run_offline(path, variable_names=["mass", "coupling"], point_number=1000, seed=7)
+print(run.points.shape, run.stop_reason)
+
+SamplerRegistry().load(path)                             # Jarvis sampler load
+```
+
+## Documentation
+
+- [Plug-in authoring](docs/development/PLUGIN_AUTHORING.md)
+
+## Status
+
+Alpha. API version 1 supports the independent execution contract; generational metadata reserves a future profile, whose running state/feedback contract remains under design. This release runs `independent` plug-ins; `generational` (feedback samplers) arrives in a later release.
+
+## License
+
+MIT. See [LICENSE](LICENSE). Copyright (c) 2026 Pengxuan Zhu.

jarvis_hep_sampler-1.0.0/README.md

@@ -0,0 +1,153 @@
+# Jarvis-HEP-Sampler
+
+Jarvis-HEP-Sampler is the plug-in SDK for user-defined samplers in the Jarvis ecosystem.
+
+A user writes a sampler as one Python file, loads it once, and from then on uses it in a task card exactly like a built-in method. No Jarvis-HEP source code is changed. The plug-in's points go through the same Redis queue, logging and monitor as built-in samplers. The sampler-enabled HEP branch binds each scan to an exact source snapshot and checks scientific settings before resume. Project packages include the source and its full hash; fetch verifies it and prints a load command.
+
+```text
+Jarvis sampler init MyLatinHypercube       # fixed template -> ./MyLatinHypercube.py
+#   edit draw() (and optionally OPTIONS_SCHEMA)
+Jarvis sampler check MyLatinHypercube.py   # optional offline check, no Redis
+Jarvis sampler load MyLatinHypercube.py    # snapshot into ~/.jarvis/samplers; reloading replaces it
+Jarvis run task.yaml                     # Sampling.Method: MyLatinHypercube
+```
+
+The `Jarvis sampler` commands are part of Jarvis-HEP and use this package. They are available in the sampler-enabled Jarvis-HEP development branch. The SDK also supports offline Python use (see [Python API](#python-api)).
+
+## Scope
+
+Jarvis-HEP-Sampler owns the plug-in format:
+
+- the fixed template
+- the `PLUGIN` metadata rules and method-name rule
+- loading a plug-in file
+- the user registry in `~/.jarvis/samplers/`
+- the deterministic random streams
+- the output contract (shape, real, finite, inside `[0, 1]`)
+- the `log` facade handed to plug-ins
+- the offline driver and conformance checks
+
+Jarvis-HEP owns the runtime:
+
+- the `Jarvis sampler` CLI
+- task-card validation
+- the run preflight
+- mapping unit-cube points to physical parameters, and `selection`
+- Sample UUIDs, Redis, Workers and the Archiver
+- checkpoints and resume
+- the sampler log, telemetry and monitor
+- `Jarvis man` and project packing
+
+This package never imports Jarvis-HEP, Redis or Portal.
+
+## Complete package installation
+
+Version 1.0.0. Install from PyPI:
+
+```bash
+python -m pip install "Jarvis-HEP-Sampler==1.0.0"
+```
+
+From this repository:
+
+```bash
+python -m pip install .
+```
+
+Dependencies: NumPy and jsonschema. A sampler-enabled Jarvis-HEP installs this SDK with `Jarvis-HEP-Sampler>=1.0.0,<2`.
+
+The end-to-end user tutorial lives in Jarvis-Books, in the TeX manual chapter **Jarvis-HEP-Sampler: Implementing Your Own Sampler** (`TeX/Jarvis-HEP-V2 manual`).
+
+## A plug-in
+
+```python
+"""Latin hypercube design: one point per stratum in every variable."""
+
+import numpy as np
+
+PLUGIN = {
+    "api_version": 1,
+    "method": "MyLatinHypercube",
+    "version": "0.1.0",
+    "profile": "independent",
+}
+
+OPTIONS_SCHEMA = {  # optional
+    "type": "object",
+    "properties": {"centered": {"type": "boolean"}},
+    "additionalProperties": False,
+}
+
+
+def prepare(setup):
+    rng = setup.rng()
+    perms = np.stack([rng.permutation(setup.point_number) for _ in range(setup.dimension)])
+    return {"perms": perms, "centered": bool(setup.options.get("centered", False))}
+
+
+def draw(context, rng, plan):
+    strata = plan["perms"][:, context.candidate_index]
+    offset = 0.5 if plan["centered"] else rng.random(context.dimension)
+    return (strata + offset) / context.point_number
+```
+
+```yaml
+Sampling:
+  Method: MyLatinHypercube
+  Variables:
+    - name: mass
+      distribution: {type: Flat, parameters: {min: 100.0, max: 1000.0}}
+  Bounds:
+    seed: 7
+    point_number: 10000
+    centered: false
+```
+
+The full contract is in [Plug-in authoring](docs/development/PLUGIN_AUTHORING.md).
+
+A complete runnable card is provided in
+[examples/MyLatinHypercube.task.yaml](examples/MyLatinHypercube.task.yaml).
+It uses Jarvis-HEP's bundled Eggbox demonstration operator:
+
+```bash
+Jarvis sampler check examples/MyLatinHypercube.py --card examples/MyLatinHypercube.task.yaml
+Jarvis sampler load examples/MyLatinHypercube.py
+Jarvis validate examples/MyLatinHypercube.task.yaml
+Jarvis check examples/MyLatinHypercube.task.yaml
+Jarvis run examples/MyLatinHypercube.task.yaml
+```
+
+`Jarvis sampler check` is the offline file check and does not require `load`. `Jarvis check` is the calculator smoke: its identity, bound source and checkpoint stay under `DATABASE/test` and `checkpoints/<scan>/<Method>/check/`, and the formal scan's science database and resume checkpoint stay in place.
+
+Reloading the same method updates future scans. Removing the registration
+preserves an existing scan's bound source and its normal `Jarvis run ... --resume`
+workflow.
+
+## Python API
+
+```python
+from jarvis_hep_sampler import SamplerRegistry, write_template
+from jarvis_hep_sampler.testing import check_plugin, run_offline
+
+path = write_template("MyLatinHypercube")                  # Jarvis sampler init
+report = check_plugin(path, dimension=2, options={})     # Jarvis sampler check
+for name, result in report.rows():
+    print(f"{name:14} {result}")
+
+run = run_offline(path, variable_names=["mass", "coupling"], point_number=1000, seed=7)
+print(run.points.shape, run.stop_reason)
+
+SamplerRegistry().load(path)                             # Jarvis sampler load
+```
+
+## Documentation
+
+- [Plug-in authoring](docs/development/PLUGIN_AUTHORING.md)
+
+## Status
+
+Alpha. API version 1 supports the independent execution contract; generational metadata reserves a future profile, whose running state/feedback contract remains under design. This release runs `independent` plug-ins; `generational` (feedback samplers) arrives in a later release.
+
+## License
+
+MIT. See [LICENSE](LICENSE). Copyright (c) 2026 Pengxuan Zhu.

jarvis_hep_sampler-1.0.0/docs/README.md

@@ -0,0 +1,3 @@
+# Jarvis-HEP-Sampler docs
+
+- [Plug-in authoring](development/PLUGIN_AUTHORING.md): the plug-in contract, for sampler authors

jarvis_hep_sampler-1.0.0/docs/development/PLUGIN_AUTHORING.md

@@ -0,0 +1,140 @@
+# Plug-in authoring
+
+A sampler plug-in is one `.py` file. Start from the template (`Jarvis sampler init <Name>`), edit it, load it (`Jarvis sampler load <file>`), then write `Sampling.Method: <Name>` in a task card.
+
+The plug-in only produces points in the unit cube. Jarvis-HEP maps them through `Variables` and `Mapper`, applies `selection`, and runs them through Workers. You never touch Sample objects, UUIDs, Redis or the DATABASE.
+
+## File contents
+
+| Name | Required | Purpose |
+| --- | --- | --- |
+| `PLUGIN` | yes | Metadata dict, JSON data only (below) |
+| `OPTIONS_SCHEMA` | no | JSON Schema (draft 2020-12) for your Bounds options. Leave it out, or set it to `None`, and your options are not checked |
+| `prepare(setup)` | no | Runs once per scan, and again on resume. Returns the `plan` passed to `draw` |
+| `draw(context, rng, plan)` | yes, unless you use blocks | Returns one point |
+| `draw_block(context, rng, plan)` | with `block_size` | Returns `block_size` points at once |
+| `validate_options(options)` | no | Raise to reject options, beyond what the schema checks |
+| `settings_rows(setup, plan)` | no | Extra rows for the settings table |
+| `summary_rows(plan, stats)` | no | Extra rows for the summary table |
+| `stop_reason(plan, stats)` | no | Stop reason for the summary |
+| `status(plan, stats)` | no | Metrics for the monitor |
+
+You may import any library installed in your environment. Missing imports fail at `load`, at `check`, or when the run starts.
+
+## `PLUGIN`
+
+| Key | Required | Value |
+| --- | --- | --- |
+| `api_version` | yes | `1` |
+| `method` | yes | The `Sampling.Method` name. It must look like a built-in name: an upper-case letter, then 1–63 letters or digits (`MyLatinHypercube`). It cannot be a built-in name, in any letter case |
+| `version` | yes | Your version string. Change it whenever the algorithm changes meaning. HEP checks saved version/configuration on resume; start a new scan after science changes |
+| `profile` | yes | `"independent"`. `"generational"` is reserved for feedback samplers in a later release |
+| `description` | no | One line, shown by `Jarvis man` and `Jarvis sampler list` |
+| `statistical` | no | `True` turns on the same Mapper warnings as the statistical built-in methods. It does not make your points posterior samples |
+| `block_size` | no | Use `draw_block` with blocks of this size instead of `draw` |
+
+Unknown keys are an error, so a typo cannot pass silently.
+
+## Bounds: reserved keys and your options
+
+| Key | Owner | Rule |
+| --- | --- | --- |
+| `seed` | Jarvis-HEP | Non-negative integer, default `0` |
+| `point_number` | Jarvis-HEP | Positive integer, required. The number of candidates; points rejected by `selection` count |
+| `max_worker` | Jarvis-HEP | Run-time in-flight limit |
+| everything else | you | Your options, available as `setup.options` / `context.options` |
+
+Options must be JSON data (strings, numbers, booleans, null, lists, mappings). Inside the plug-in they are read-only: lists arrive as tuples and mappings cannot be changed. Schema `default` values are not filled in; use `options.get("key", default)`.
+
+## Contexts
+
+| Field | `setup` | `context` (draw) | `context` (draw_block) |
+| --- | --- | --- | --- |
+| `seed` | ✓ | | |
+| `point_number`, `dimension`, `variable_names`, `options`, `log` | ✓ | ✓ | ✓ |
+| `rng()` | ✓, a generator reserved for `prepare` | | |
+| `candidate_index` | | ✓ | |
+| `block_index`, `block_size` | | | ✓ |
+
+`variable_names` follows the order of `Variables` in the task card, and `dimension` is its length.
+
+## Points
+
+- `draw` returns a 1-D array, list or tuple of length `dimension`.
+- `draw_block` returns shape `(block_size, dimension)` for candidates `[block_index * block_size, (block_index + 1) * block_size)`. Rows past `point_number` are dropped.
+- Values must be real numbers (not bool, complex or strings), finite, with `0 <= u <= 1`.
+- After mapping, every physical value must also be finite. Jarvis-HEP checks this.
+
+A bad point stops the scan with the candidate index and the component. Nothing is clipped or redrawn for you.
+
+## Randomness and resume
+
+Use the `rng` you are given; do not use `np.random.*` global functions, time or process IDs.
+
+- `draw` gets a generator that depends only on `(seed, candidate_index)`.
+- `draw_block` gets one that depends only on `(seed, block_index)`.
+- `prepare` uses `setup.rng()`.
+
+For a deterministic plan, points are the same whatever the number of Workers, batch size or completion order. Replaying the same source and configuration reproduces the indexed stream within the same environment; the sampler-enabled HEP branch checks configuration, checkpoint identity and the full bound source hash before recovery. Reloading or removing the user registration does not change an existing scan.
+
+`prepare` runs again on resume, so the plan must follow from `setup` alone. Module-level state is allowed but outside this guarantee. `Jarvis sampler check` catches the common case of drawing from an unseeded global generator.
+
+## Logging and monitor
+
+Every context has `log`. Jarvis-HEP writes the start, settings, ready, checkpoint, failure, result and summary records itself. Use `log` for the rest:
+
+| Call | Record |
+| --- | --- |
+| `log.step(title, rows)` | A table per stage or generation (INFO) |
+| `log.adjust(name, old, new, why)` | A setting you changed, ignored or clamped (WARNING) |
+| `log.saved(what, path)` | `<What> saved to <path>` for a file you wrote (WARNING) |
+| `log.info(...)`, `log.warning(...)`, `log.debug(...)` | Anything else |
+
+`stats` in the hooks has `candidates`, `accepted` and `point_number`. `status` may return up to 8 scalar metrics, with strings of up to 32 characters; NumPy boolean, integer, floating-point and string scalars are converted to their Python equivalents. Extra, non-finite or non-scalar entries are dropped. A reporting hook that raises, including while its returned rows or mapping are consumed or converted, is logged and skipped; it never stops the scan. Interrupts and process-exit requests still propagate. Without `stop_reason`, the reason is `point_number reached`.
+
+## Errors
+
+| Error | When |
+| --- | --- |
+| `PluginLoadError` | The file does not import, `PLUGIN` is invalid, a required function is missing, or the name is taken |
+| `PluginConfigError` | Options break the schema, or `validate_options` / `prepare` raised |
+| `PluginOutputError` | `draw` / `draw_block` raised or returned a bad point |
+| `PluginResumeMismatch` | A resumed scan does not match the original run |
+| `RegistryError` | `~/.jarvis/samplers` is unreadable or a snapshot is broken |
+
+Your own exception is chained to these, so its traceback reaches the log. Output conversion errors, including overflow when converting to float64, are also reported as `PluginOutputError` with the method and candidate position. A failing draw stops the scan; Jarvis-HEP never falls back to another sampler.
+
+## The registry
+
+`Jarvis sampler load` copies the file to `~/.jarvis/samplers/user_sources/<Method>-<hash>.py` and records it in `~/.jarvis/samplers/sources.json`. `JARVIS_SAMPLERS_HOME` moves that directory.
+
+- Runs use the copy, not your working file. Edit, then load again.
+- `Jarvis sampler list` marks a working file changed since the last load.
+- Loading the same method again replaces the entry and retires the old copy.
+- If removing a retired copy fails after the registration commits, the command
+  still succeeds and reports a cleanup warning. Only explicitly retired copies
+  are retried on a later successful load/remove; arbitrary files are not swept.
+- The SDK retains a private `.pending_cleanup.json` only when cleanup needs a
+  retry. A damaged retry file or a failure to save it is reported without
+  undoing the completed registration; manual cleanup may then be needed.
+
+The SDK reads and verifies snapshot bytes under the registry lock, then imports
+those same bytes after releasing the lock. Managed snapshot paths must stay
+inside `user_sources` and cannot be symbolic links. Removing a registration
+preserves the working source file and an existing scan's own bound source.
+
+The registry belongs to your user account on one machine. Load the plug-in on every machine that runs the card.
+
+## Operational limits
+
+A snapshot fixes only this Python entry file. Install any packages it imports in the same environment as Jarvis-HEP. Sibling modules and data files are not copied, and `__file__` points at the snapshot during a real run. The independent profile does not use Worker feedback; points may still be correlated, as in LHS or a low-discrepancy design.
+
+`Jarvis sampler check` executes the file, reimports the same source bytes, and restarts them in a fresh Python process to compare the tail. A successful check exercises this configuration; it does not prove the algorithm scientifically correct. `--card` preserves the card budget unless `--points` explicitly overrides it; this override changes the total design, rather than just the number of checked points.
+
+`Jarvis check` is the separate calculator smoke. It draws a few points through the loaded plug-in and the card's opera and likelihood. Its identity goes to `DATABASE/test/sampler_identity.json`, and its bound source and checkpoint go under `checkpoints/<scan>/<Method>/check/`. It does not read or replace the formal science database, bound source or resume checkpoint. `runtime.json`, logs and `run_summary` stay in the scan's ordinary files.
+
+Schemas are optional. When supplied, local `$defs`/`$ref` references are supported. Referenced documents are never downloaded during validation; unresolved references produce an offline diagnostic. Schema defaults remain documentation and are not applied automatically.
+
+Reporting hooks are optional. Jarvis-HEP logs explicit options without them, with bounded display (32 rows, 256 characters per cell); a hook can show defaults or derived values. `status` runs on the sampling thread and is cached for monitor/heartbeat readers. Keep it quick and read-only with respect to `plan`; repeated errors are logged once per hook per session, with bounded error retention. A hanging user function has no enforced timeout.
+
+Default strict resume and project source packing are implemented in the sampler-enabled HEP branch. Changing source during an existing scan, promotion to other built-in methods, and feedback/generational execution remain later milestones. Cross-version numerical identity is not promised; changed SDK/Python/NumPy versions produce a warning. The complete user workflow is documented in the Jarvis-Books TeX manual chapter **Jarvis-HEP-Sampler: Implementing Your Own Sampler**.

jarvis_hep_sampler-1.0.0/examples/MyLatinHypercube.py

@@ -0,0 +1,42 @@
+"""Latin hypercube design: one point per stratum in every variable.
+
+Load it with ``Jarvis sampler load examples/MyLatinHypercube.py`` and write
+``Sampling.Method: MyLatinHypercube`` in a task card.
+"""
+
+import numpy as np
+
+PLUGIN = {
+    "api_version": 1,
+    "method": "MyLatinHypercube",
+    "version": "0.1.0",
+    "profile": "independent",
+    "description": "Latin hypercube design with point_number strata per variable.",
+}
+
+OPTIONS_SCHEMA = {
+    "type": "object",
+    "properties": {
+        "centered": {
+            "type": "boolean",
+            "description": "Put each point at the centre of its stratum.",
+        },
+    },
+    "additionalProperties": False,
+}
+
+
+def prepare(setup):
+    rng = setup.rng()
+    perms = np.stack([rng.permutation(setup.point_number) for _ in range(setup.dimension)])
+    return {"perms": perms, "centered": bool(setup.options.get("centered", False))}
+
+
+def draw(context, rng, plan):
+    strata = plan["perms"][:, context.candidate_index]
+    offset = 0.5 if plan["centered"] else rng.random(context.dimension)
+    return (strata + offset) / context.point_number
+
+
+def settings_rows(setup, plan):
+    return [("centered", plan["centered"])]

jarvis_hep_sampler-1.0.0/examples/MyLatinHypercube.task.yaml

@@ -0,0 +1,34 @@
+# Complete native Jarvis-HEP demo card; load MyLatinHypercube.py first.
+Scan:
+  name: sampler-lhs-demo
+EnvReqs:
+  V2:
+    workers: 2
+    batch_size: 4
+Sampling:
+  Method: MyLatinHypercube
+  Bounds:
+    seed: 7
+    point_number: 32
+    centered: true
+  Variables:
+    - name: x
+      distribution:
+        type: Flat
+        parameters: {min: 0.0, max: 1.0}
+    - name: y
+      distribution:
+        type: Flat
+        parameters: {min: 0.0, max: 1.0}
+  LogLikelihood:
+    - name: LogL_Z
+      expression: z
+Operas:
+  Modules:
+    - name: DemoEggbox
+      operator: jarvishep2.testing.eggbox.eggbox2d_numpy
+      input:
+        - {name: x, expression: x}
+        - {name: y, expression: y}
+      output:
+        - {name: z, entry: z}

jarvis_hep_sampler-1.0.0/pyproject.toml

@@ -0,0 +1,52 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "Jarvis-HEP-Sampler"
+version = "1.0.0"
+description = "Plug-in SDK for user-defined Jarvis-HEP samplers"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Pengxuan Zhu" }
+]
+keywords = ["HEP", "physics", "sampling", "Jarvis-HEP", "plugin"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Physics",
+]
+dependencies = [
+  "numpy>=1.24",
+  "jsonschema>=4.18",
+]
+
+
+[project.urls]
+Homepage = "https://github.com/Pengxuan-Zhu-Phys/Jarvis-HEP-Sampler"
+Repository = "https://github.com/Pengxuan-Zhu-Phys/Jarvis-HEP-Sampler"
+Issues = "https://github.com/Pengxuan-Zhu-Phys/Jarvis-HEP-Sampler/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["jarvis_hep_sampler*"]
+
+[tool.setuptools.package-data]
+jarvis_hep_sampler = ["py.typed", "templates/*.tmpl"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

jarvis_hep_sampler-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+