McStas Readout Master for ESS detectors

Components and tools linking McStas 3.3+ ray-tracing neutron simulations to the ESS data pipeline via the Event Formation Unit (EFU).

Simulated readout records are collected to HDF5 files while the simulation runs, combined across repeated runs or scan points, and replayed to EFUs afterwards, statistically correctly — the data-acquisition stack does not need to be running (or reachable) during the simulation.

Documentation

Guides, per-component parameter references, CLI documentation, and the C/C++ API reference are published at

https://mcdotstar.github.io/mcstas-readout-master/

To build the site locally (requires Doxygen):

cmake -S . -B build-docs -DREADOUT_DOCS_ONLY=ON
cmake --build build-docs --target docs
# open build-docs/docs/html/index.html

Quickstart

1. Install

git clone https://github.com/mcdotstar/mcstas-readout-master.git
cmake -S mcstas-readout-master -B mcstas-readout-master-build -DCMAKE_INSTALL_PREFIX=~/.local
cmake --build mcstas-readout-master-build --target install

This installs libreadout, the readout-config, readout-combine, and readout-replay tools, and the McStas component files.

2. Collect

Add a Collector* component matching your detector electronics (CAEN, TTLMonitor, CDT, VMM3, BM0, BM2, BMI) to the end of your instrument's TRACE section. Identifying values are read by name from particle variables (typically USER_VARS set in an EXTEND block):

TRACE
  ...
  SEARCH SHELL "readout-config --show compdir"
  COMPONENT collect = CollectorCAEN(
    ring="ring_id", tube="tube_id", a_name="left", b_name="right",
    filename="run", dataset_name="caen_bank0")
  AT (0, 0, 0) ABSOLUTE

Each run produces a cue-based HDF5 file; several collectors can share one file, each writing its own named group.

3. Combine

readout-combine validate run_*.h5
readout-combine append      --output merged.h5 run_a.h5 run_b.h5   # identical parameters
readout-combine concatenate --output scan.h5   point_*.h5          # scan points

4. Replay

readout-replay --time 2.0 --seed 42 --addr my-efu.example.org --port 9000 scan.h5

Replay steps through the stored points, publishes each point's parameters, draws n ~ Poisson(w * counting_time) events per stored readout, and sends them to EFUs resolved from explicit configuration, file-embedded attributes, or the command-line defaults — in that order. See the CLI reference for all options.

Legacy runtime streaming

The original per-ray streaming components remain available for use cases where the EFU runs alongside the simulation: ReadoutCAEN and ReadoutTTLMonitor make a Poisson-distributed Monte Carlo choice per traced neutron and send packets immediately, and ReadoutDiscreteCAEN sends an exact number of weighted-sampled events at the end of the run. Their parameters are documented on the site and in the component headers (mcdoc-compatible).

MPI support

The Collector* components gather records to the master node, which writes one HDF5 file. For the streaming Readout* components, all nodes need network access to the EFU host.

Development

See DEVELOPMENT.md for the development-mode build (-DREADOUT_DEVELOPMENT_MODE=ON), test suites, and the reasoning behind the self-locating readout-config.

Use with McStas 3.2

The SEARCH SHELL automatic path modification used above requires McStas 3.3+. With McStas 3.2, copy the component files into one of the McStas component search directories and omit the SEARCH SHELL line.

Project links

Data verified by PyPI on Jul 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for g5t from gravatar.com g5t

Credits

Author: Gregory Tucker

GitHub Statistics

Data verified by PyPI on Jul 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

BSD-3-Clause

Requires

Python >=3.10

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mcstas_readout_master-0.5.1.tar.gz (328.5 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

mcstas_readout_master-0.5.1-py3-none-manylinux_2_28_x86_64.whl (9.1 MB view details)

Uploaded Python 3manylinux: glibc 2.28+ x86-64

mcstas_readout_master-0.5.1-py3-none-macosx_14_0_x86_64.whl (5.8 MB view details)

Uploaded Python 3macOS 14.0+ x86-64

mcstas_readout_master-0.5.1-py3-none-macosx_14_0_arm64.whl (4.8 MB view details)

Uploaded Python 3macOS 14.0+ ARM64

File details

Details for the file mcstas_readout_master-0.5.1.tar.gz.

File metadata

  • Download URL: mcstas_readout_master-0.5.1.tar.gz
  • Upload date:
  • Size: 328.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for mcstas_readout_master-0.5.1.tar.gz
Algorithm Hash digest
SHA256 28f11e1216731e59a5bb5489682653c263e1abd784b8a739f1177785a38124e7
MD5 f1b100fe1d91c492c423269572b5b842
BLAKE2b-256 de7f67e8451b041460bd7336745da9aa54474d3e410f35d95a8da4a90e345ccb

See more details on using hashes here.

Provenance

The following attestation bundles were made for mcstas_readout_master-0.5.1.tar.gz:

Publisher: wheels.yml on mcdotstar/mcstas-readout-master

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mcstas_readout_master-0.5.1-py3-none-manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for mcstas_readout_master-0.5.1-py3-none-manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 192e626e70e65736601a323ab7647c4e477fe357b9d0fc7ba1fad421614c2067
MD5 10a57aaf510e27d275abf01cf3690419
BLAKE2b-256 20069f183959e6762ff583962d2462fb0f4bf1e7965a6e18bb865d0ef0d6ded0

See more details on using hashes here.

Provenance

The following attestation bundles were made for mcstas_readout_master-0.5.1-py3-none-manylinux_2_28_x86_64.whl:

Publisher: wheels.yml on mcdotstar/mcstas-readout-master

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mcstas_readout_master-0.5.1-py3-none-macosx_14_0_x86_64.whl.

File metadata

File hashes

Hashes for mcstas_readout_master-0.5.1-py3-none-macosx_14_0_x86_64.whl
Algorithm Hash digest
SHA256 4fdef6f72db38b3a4d7c4c0f0a360d7aede41b34d698874f144254936b2ecfd0
MD5 222ca50d5495e6dc3a292bbe01d4a67b
BLAKE2b-256 8dbbed6a231471cbc207887edabc8b2ffe3e2ff8632c8632018ba3c32d32a7de

See more details on using hashes here.

Provenance

The following attestation bundles were made for mcstas_readout_master-0.5.1-py3-none-macosx_14_0_x86_64.whl:

Publisher: wheels.yml on mcdotstar/mcstas-readout-master

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file mcstas_readout_master-0.5.1-py3-none-macosx_14_0_arm64.whl.

File metadata

File hashes

Hashes for mcstas_readout_master-0.5.1-py3-none-macosx_14_0_arm64.whl
Algorithm Hash digest
SHA256 b32406ddd5143af33f46d9d33e7eb64011750b2746437cb25638b4d845381c3c
MD5 f6fe4a43b287ac20d3f0e77698886464
BLAKE2b-256 873770eb02c889fca687e5cc9eac6a9e7bb36300e89c103c908b9e4c17fa648b

See more details on using hashes here.

Provenance

The following attestation bundles were made for mcstas_readout_master-0.5.1-py3-none-macosx_14_0_arm64.whl:

Publisher: wheels.yml on mcdotstar/mcstas-readout-master

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.5.1 This release

4 files

0.5.0

4 files

0.3.3

4 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page