fasthep-carpenter 2026.6.1

HEP analysis components for FAST-HEP workflows.

fasthep-carpenter

fasthep-carpenter provides common analysis building blocks for FAST-HEP workflows.

It contains reusable High Energy Physics transforms, sources, sinks, and runtime helpers built on top of fasthep-flow.

The Python import namespace is:

import fasthep_carpenter

Scope

fasthep-carpenter is responsible for:

• ROOT and awkward-array based sources
• event stream manipulation
• HEP analysis transforms
• histogram filling
• cutflows
• object selection helpers
• common CMS/LHC analysis utilities
• workflow runtime extensions

It is the main “analysis implementation” layer of the FAST-HEP ecosystem.

Relationship to fasthep-flow

fasthep-flow provides:

• workflow compilation
• execution planning
• orchestration
• registries
• backend interfaces

fasthep-carpenter provides:

• concrete analysis operations
• HEP-specific runtime behaviour
• physics object manipulation
• common workflow primitives

In practice, most HEP users will use both packages together.

Recommended companion packages

• fasthep-flow

  • workflow language and execution engine

• fasthep-curator

  • dataset inspection
  • schema generation
  • metadata snapshots

• fasthep-render

  • plotting
  • tables
  • reports

• fasthep-cli

  • the fasthep command-line interface

Alternatively, install the meta package:

pip install fasthep

Installation

Install directly:

pip install fasthep-carpenter

Development environment:

pixi install
pixi run ci

Minimal example

Example transform registration:

registry:
  transforms:
    define:
      spec: fasthep_carpenter.spec.define_transform:DEFINE_TRANSFORM_SPEC
      impl: fasthep_carpenter.impl.define_transform:run_define_transform

Example workflow snippet:

steps:
  - id: TightMuon
    op: hep.select
    params:
      collection: Muon
      mask: Muon_tightId

Design principles

fasthep-carpenter focuses on:

• reusable analysis primitives
• declarative workflows
• registry-driven extension
• experiment-agnostic interfaces where possible
• compatibility with awkward-array based analysis ecosystems

The package intentionally separates workflow orchestration (fasthep-flow) from domain-specific analysis behaviour.

Documentation

Main FAST-HEP documentation:

• https://fast-hep.github.io

API documentation for this package:

• https://fasthep-carpenter.readthedocs.io/en/latest/

Repository

Main FAST-HEP repository and project links:

• https://github.com/FAST-HEP/fasthep

Contributing

Contribution guidelines, development setup, and project-wide documentation are maintained centrally in the main FAST-HEP repository.

Legacy branch

The pre-split prototype implementation is preserved in the legacy branch.

The new main branch contains the split-package architecture.

Status

FAST-HEP is currently in active pre-alpha development.

Interfaces may still evolve rapidly while the package split and stabilization work continues.