Packages

FAST-HEP is developed as a collection of focused packages.

Most users do not need to install or interact with these packages individually. The fasthep meta package provides curated installations that bring together the components needed for common use cases.

The package split becomes useful when you want to understand where a capability comes from, use a component independently, or extend FAST-HEP with your own implementations.

Toolkit overview#

The main packages have distinct responsibilities:

flowchart TD
    CLI["<b>CLI</b><br/>user interface"]:::input

    Flow["<b>Flow</b><br/>compile, plan,<br/>orchestrate"]:::flow

    Carpenter["<b>Carpenter</b><br/>HEP data processing"]:::capability
    Curator["<b>Curator</b><br/>inspection + provenance"]:::capability
    Render["<b>Render</b><br/>visualisation + reports"]:::capability

    CLI --> Flow

    Carpenter -.->|"registered capabilities"| Flow
    Curator -.->|"registered capabilities"| Flow
    Render -.->|"registered capabilities"| Flow

classDef input fill:#f7f7f7,stroke:#5f6368,stroke-width:2px,color:#111111;
classDef flow fill:#e8f0fe,stroke:#3c6fbd,stroke-width:2px,color:#111111;
classDef source fill:#e7f5ff,stroke:#1c7ed6,stroke-width:2px,color:#111111;
classDef transform fill:#fff9db,stroke:#f08c00,stroke-width:2px,color:#111111;
classDef sink fill:#ebfbee,stroke:#2f9e44,stroke-width:2px,color:#111111;
classDef artifact fill:#eadcf8,stroke:#7950a3,stroke-width:2px,color:#111111;
classDef runtime fill:#fce8d5,stroke:#b56b22,stroke-width:2px,color:#111111;
classDef capability fill:#f7f7f7,stroke:#5f6368,stroke-width:2px,color:#111111;

Flow provides the workflow compilation, planning, and runtime machinery. Carpenter, Curator, Render, and external packages contribute capabilities through registries and stable contracts.

This is not a closed set: experiments, projects, and individual analyses can provide capabilities through the same interfaces.

Core toolkit#

fasthep-flow#

Flow is the workflow compiler and runtime.

It provides the general infrastructure for:

• workflow description and normalisation
• logical graph construction and compiler analysis
• execution planning
• profiles and registries
• runtime orchestration and execution backends

Flow is designed to remain largely domain-independent. HEP-specific analysis functionality is provided by other packages rather than built into the workflow engine.

Documentation · GitHub

fasthep-carpenter#

Carpenter provides common HEP data-processing and analysis capabilities.

These include:

• data readers and writers, including ROOT-based workflows
• derived quantities and selections
• histogramming, aggregation, and cutflows
• common HEP operations
• data writers
• specialised execution capabilities

Carpenter provides these capabilities to Flow through registries and operation contracts, allowing them to evolve independently of the workflow engine.

Documentation · GitHub

fasthep-curator#

Curator provides inspection, metadata, provenance, and diagnostic capabilities.

These include:

• dataset and schema inspection
• provenance collection
• runtime diagnostics
• inspection reports and diagnostics

Curator focuses on understanding and recording what happens around an analysis without owning its scientific transformations.

Documentation · GitHub

fasthep-render#

Render provides visualisation and reporting capabilities.

These include:

• scientific plots
• tables and reports
• reusable rendering styles
• publication-oriented outputs

Rendering is kept separate from the analysis operations that produce the underlying scientific products.

Documentation · GitHub

fasthep-cli#

CLI provides the user-facing fasthep command.

For example:

fasthep run workflow.yaml

The CLI provides a common interface to capabilities and workflows provided by the other FAST-HEP packages rather than implementing workflow or analysis behaviour itself.

Documentation · GitHub

Installation and supporting packages#

fasthep#

The fasthep meta package is the recommended installation entry point.

For a typical HEP environment:

pip install "fasthep[hep]"

It provides curated combinations of FAST-HEP packages so users do not need to manage the toolkit components individually.

fasthep-toolbench#

fasthep-toolbench contains small shared utilities used across the toolkit, including download, package-discovery, and terminal helpers.

Most users will encounter Toolbench indirectly through other FAST-HEP packages.

Examples and development#

fasthep-workshop#

fasthep-workshop contains the runnable examples and tutorials used throughout the FAST-HEP documentation and training material.

It also demonstrates how analysis repositories can provide their own workflows, profiles, operations, and supporting code.

Workshop documentation · GitHub

fasthep-dev#

fasthep-dev is the integration workspace used when developing multiple FAST-HEP packages together.

It provides a common environment for cross-package development, integration testing, and coordinated ecosystem validation.

Most FAST-HEP users do not need fasthep-dev.

Which package should I use?#

For most users, the answer is simply FAST-HEP as a whole: install the fasthep meta package and use the fasthep command-line interface.

Individual packages become relevant when you want to go deeper:

FAST-HEP packages use the same extension mechanisms available to experiment and analysis packages. The toolkit is therefore a collection of useful implementations built around Flow rather than a fixed set of capabilities built into it.

For more about this architecture, see Profiles and registries and Analysis repositories.