celeritas::LocalTransporter Class Reference

Manage offloading of tracks to Celeritas. More...

#include <LocalTransporter.hh>

Inheritance diagram for celeritas::LocalTransporter:

Public Member Functions
	LocalTransporter (SetupOptions const &options, SharedParams &params)
	Construct with shared (MT) params.
void	Push (G4Track &) final
	Convert a Geant4 track and add it to the Stepper producer buffer.
CoreStateInterface const &	GetState () const
	Access core state data for user diagnostics.
CoreStateInterface &	GetState ()
	Access core state data for user diagnostics.
	operator bool () const
	Whether the class instance is initialized.
LocalOffload interface
void	Initialize (SetupOptions const &options, SharedParams &params) final
	Helper for making initialization more obvious from user code.
void	InitializeEvent (int) final
	Set the event ID and reseed the Celeritas RNG at the start of an event.
void	Flush () final
	Transport all buffered tracks and produced secondaries.
void	Finalize () final
	Clear local data.
bool	Initialized () const final
	Helper for making initialization more obvious from user code.
size_type	GetBufferSize () const final
	Number of accepted primaries not yet accounted as transported.
MapStrDbl	GetActionTime () const final
	Get the accumulated action times.
Public Member Functions inherited from celeritas::LocalOffloadInterface
	operator bool () const
	Whether the class instance is initialized.

Additional Inherited Members
Public Types inherited from celeritas::LocalOffloadInterface
using	MapStrDbl = std::unordered_map< std::string, double >
Protected Member Functions inherited from celeritas::LocalOffloadInterface
	LocalOffloadInterface (LocalOffloadInterface const &)=default
LocalOffloadInterface &	operator= (LocalOffloadInterface const &)=default
	LocalOffloadInterface (LocalOffloadInterface &&)=default
LocalOffloadInterface &	operator= (LocalOffloadInterface &&)=default

Detailed Description

Manage offloading of tracks to Celeritas.

This class must be constructed locally on each worker thread/task/stream, usually as a shared pointer that's accessible to:

• a run action (for initialization),
• an event action (to set the event ID and flush offloaded tracks at the end of the event)
• a tracking action (to try offloading every track)

Primary buffering

Stepper owns two fixed-capacity host primary buffers and the device event that protects the source of an asynchronous H2D copy. LocalTransporter validates and converts Geant4 tracks, pushes accepted primaries into the Stepper producer buffer, and keeps the corresponding Geant4 energy and loss accounting. Primaries outside the Celeritas geometry are counted as lost but are not added to either Stepper buffer.

Device execution

When the producer buffer first reaches capacity, Push stages it and immediately calls StepperInterface::async. Same-stream ordering ensures that the primary-copy completes before the stepping kernels use it. The Stepper retains the staged host storage until the copy completes, while Geant4 can continue filling the second buffer.

At most one step result, one staged batch, and one producer batch can be pending. Before reusing a full producer buffer, Push submits any staged batch. It then applies backpressure by consuming and advancing the current result only until start-of-step initialization can consume enough queued tracks and primaries to preserve room for the secondary stack. Active tail tracks may remain when a new batch is staged and launched. Calls to stage_primaries and async can still block on synchronization internal to the current Stepper implementation. Before accepting each subsequent track, Push polls a pending step. If it is ready, its result is consumed and another step is launched whenever existing transport remains or another batch is staged. This allows device transport to progress while Geant4 continues producing primaries. A full producer batch is staged only when it fits alongside queued initializers and leaves the maximum usable initializer capacity for secondaries after vacant track slots have been filled.

Event completion

At event end, Flush first submits any staged batch. If a partially filled producer buffer remains, it advances the current transport until that batch satisfies the same initializer and secondary-capacity admission rule, then stages and launches the producer batch. It finally steps all transport synchronously to completion. Hit processing and Geant4 track reconstruction are kept alive across the asynchronous work and cleared only after this drain completes. A flush with only rejected primaries still reports and clears their loss accounting.

Host mode has the same buffering interface but no asynchronous overlap: a full producer buffer calls Flush and is transported to completion before Push returns.

LocalTransporter accounting follows the Stepper primary lifecycle:

State	Stepper state	Local accounting
Producer	Primaries accepted by push_primary	buffered_accum_
Staged	H2D copy queued; actions not submitted	staged_accum_
Submitted	Batch submitted by async	in_flight_accum_
Accounted	First result for batch consumed	Added to run_accum_

in_flight_accum_ is cleared when the first result for its submitted batch is consumed, even if the resulting active tracks require additional steps. GetBufferSize returns accepted primaries that have not yet reached this accounting point. It does not count rejected primaries, active Celeritas tracks, or generated secondaries. The transport_active_ flag records whether the last consumed result requires another step, while valid on the Stepper records a currently pending result. The step iteration count spans all overlapping primary batches and resets only after transport becomes empty. Calling Finalize requires both states to be idle, normally by first calling Flush.

Warning

Due to Geant4 thread-local allocators, this class must be finalized or destroyed on the same CPU thread in which is created and used!

Member Function Documentation

Finalize()

void celeritas::LocalTransporter::Finalize ( )

finalvirtual

Clear local data.

This may need to be executed on the same thread it was created in order to safely deallocate some Geant4 objects under the hood...

Implements celeritas::LocalOffloadInterface.

Flush()

void celeritas::LocalTransporter::Flush ( )

finalvirtual

Transport all buffered tracks and produced secondaries.

Implements celeritas::LocalOffloadInterface.

GetActionTime()

auto celeritas::LocalTransporter::GetActionTime ( ) const

finalvirtual

Get the accumulated action times.

Implements celeritas::LocalOffloadInterface.

GetBufferSize()

size_type celeritas::LocalTransporter::GetBufferSize ( ) const

finalvirtual

Number of accepted primaries not yet accounted as transported.

Implements celeritas::LocalOffloadInterface.

Initialize()

void celeritas::LocalTransporter::Initialize ( SetupOptions const &  options, SharedParams &  params  )

inlinefinalvirtual

Helper for making initialization more obvious from user code.

This gives it some symmetry with Finalize, which is provided as an exception-friendly destructor.

Implements celeritas::LocalOffloadInterface.

Initialized()

bool celeritas::LocalTransporter::Initialized ( ) const

inlinefinalvirtual

Helper for making initialization more obvious from user code.

This gives it some symmetry with Finalize, which is provided as an exception-friendly destructor.

Implements celeritas::LocalOffloadInterface.

InitializeEvent()

void celeritas::LocalTransporter::InitializeEvent ( int  id )

finalvirtual

Set the event ID and reseed the Celeritas RNG at the start of an event.

Implements celeritas::LocalOffloadInterface.

Push()

void celeritas::LocalTransporter::Push ( G4Track &  g4track )

finalvirtual

Convert a Geant4 track and add it to the Stepper producer buffer.

Todo:

Eliminate event ID from primary.

Implements celeritas::TrackOffloadInterface.

---

The documentation for this class was generated from the following files:

• LocalTransporter.hh
• LocalTransporter.cc