celeritas::Stepper< M > Class Template Reference

Manage a state vector and execute a single step on all of them. More...

#include <Stepper.hh>

Inheritance diagram for celeritas::Stepper< M >:

Public Types
Type aliases
using	StateRef = CoreStateData< Ownership::reference, M >
Public Types inherited from celeritas::StepperInterface
using	Input = StepperInput
using	SpanConstPrimary = Span< Primary const >
using	result_type = StepperResult
using	SPState = std::shared_ptr< CoreStateInterface >

Public Member Functions
	Stepper (Input input)
	Construct with problem parameters and setup options.
	~Stepper () final
	Default destructor.
void	warm_up () final
	Run all step actions with no active particles.
void	async () final
	Start asynchronous transport of already-initialized states.
void	async (SpanConstPrimary primaries) final
	Start asynchronous transport with new primaries.
bool	valid () const noexcept final
	Whether an asynchronous step result can be retrieved.
bool	ready () const final
	Whether the asynchronous step has completed.
void	wait () const final
	Wait for the asynchronous step to complete without consuming its result.
StepperResult	get () final
	Wait for and return the asynchronous step result.
StepperResult	operator() () final
	Transport already-initialized states.
StepperResult	operator() (SpanConstPrimary primaries) final
void	kill_active () final
	Kill all tracks in flight to debug "stuck" tracks.
void	reseed (UniqueEventId event_id) final
	Reseed RNGs and counters at the start of an event for reproducibility.
ActionSequence const &	actions () const final
	Get action sequence for timing diagnostics.
StateRef const &	state_ref () const
	Access core data, primarily for debugging.
CoreStateInterface const &	state () const final
	Get the core state interface for diagnostic output.
void	reset_state ()
	Reset the core state counters and data so it can be reused.
SPState	sp_state () final
	Get a shared pointer to the state (TEMPORARY, DO NOT USE)

Additional Inherited Members
Protected Member Functions inherited from celeritas::StepperInterface
	StepperInterface (StepperInterface const &)=default
StepperInterface &	operator= (StepperInterface const &)=default
	StepperInterface (StepperInterface &&)=default
StepperInterface &	operator= (StepperInterface &&)=default

Detailed Description

template<MemSpace M>
class celeritas::Stepper< M >

Manage a state vector and execute a single step on all of them.

Note

This is likely to be removed and refactored since we're changing how primaries are created and how multithread state ownership is managed.

Device steps have separate start and result phases. Calling async enqueues the action sequence, a counter snapshot, and a completion event on the state stream. Diagnostic action or step timing can still synchronize the stream. Other synchronization within the action sequence is being removed separately.

Stepper<MemSpace::device> step(input);
 
// Start the initial step and later retrieve its result
step.async(my_primaries);
while (step.valid())
{
    // Optional: do host work or poll step.ready() before waiting
    step.wait();
    StepperResult result = step.get();
    if (result)
    {
        step.async();
    }
}

Asynchronous state

The valid_ flag tracks whether a result can be consumed, whereas step_done_ tracks completion of device work. Their states after successful calls are:

Lifecycle point	valid_	CPU step_done_	GPU step_done_
Construction or after get	false	Null	Allocated and ready
After async	true	Null and ready	Recorded; pending or ready
After ready returns false	true	Not possible	Recorded and pending
After ready is true or wait	true	Null/ready	Recorded/ready

A host step executes synchronously, so its null event is always ready. A device event is allocated once and re-recorded after each counter snapshot. Calling get first waits for completion and then clears valid_; it does not reset or replace the event.

The expected state transitions are

no result -- async([primaries]) --> valid result
valid result -- ready() or wait() --> valid result
valid result -- get() --> no result

Calling ready or wait repeatedly with a valid result is allowed. The next async call is allowed only after get consumes the previous result. While a result is valid, calls to warm_up, reset_state, reseed, and kill_active are rejected. The synchronous call operators perform async followed immediately by get.

Member Function Documentation

actions()

template<MemSpace M>

ActionSequence const & celeritas::Stepper< M >::actions ( ) const

inlinefinalvirtual

Get action sequence for timing diagnostics.

Implements celeritas::StepperInterface.

async() [1/2]

template<MemSpace M>

void celeritas::Stepper< M >::async ( )

finalvirtual

Start asynchronous transport of already-initialized states.

A single transport step is simply a loop over a topologically sorted DAG of kernels. The step result must be retrieved with get before another step can be started. In device mode the result counters are copied asynchronously to pinned host memory, followed by a completion event.

Existing synchronization within the action sequence can still block this call. Removing those counter-dependent synchronization points is handled separately.

Implements celeritas::StepperInterface.

async() [2/2]

template<MemSpace M>

void celeritas::Stepper< M >::async ( SpanConstPrimary  primaries )

finalvirtual

Start asynchronous transport with new primaries.

Implements celeritas::StepperInterface.

get()

template<MemSpace M>

auto celeritas::Stepper< M >::get ( )

finalvirtual

Wait for and return the asynchronous step result.

Calling this consumes the pending result and allows another step to be started.

Implements celeritas::StepperInterface.

kill_active()

template<MemSpace M>

void celeritas::Stepper< M >::kill_active ( )

finalvirtual

Kill all tracks in flight to debug "stuck" tracks.

The next "step" will apply the tracking cut and (if CPU) print diagnostic output about the failed tracks.

Implements celeritas::StepperInterface.

operator()() [1/2]

template<MemSpace M>

auto celeritas::Stepper< M >::operator() ( )

finalvirtual

Transport already-initialized states.

Deprecated:

This is the deprecated synchronous compatibility wrapper for async and get.

Implements celeritas::StepperInterface.

operator()() [2/2]

template<MemSpace M>

auto celeritas::Stepper< M >::operator() ( SpanConstPrimary  primaries )

finalvirtual

Deprecated:

Initialize new primaries and transport them for a single step.

Implements celeritas::StepperInterface.

ready()

template<MemSpace M>

bool celeritas::Stepper< M >::ready ( ) const

finalvirtual

Whether the asynchronous step has completed.

Implements celeritas::StepperInterface.

reseed()

template<MemSpace M>

void celeritas::Stepper< M >::reseed ( UniqueEventId  event_id )

finalvirtual

Reseed RNGs and counters at the start of an event for reproducibility.

This reinitializes the RNG states using a single seed and unique subsequence for each thread. It ensures that given an event identification, the random number sequence for the event (and thus the event's behavior) can be reproduced.

Implements celeritas::StepperInterface.

sp_state()

template<MemSpace M>

SPState celeritas::Stepper< M >::sp_state ( )

inlinefinalvirtual

Get a shared pointer to the state (TEMPORARY, DO NOT USE)

Implements celeritas::StepperInterface.

state()

template<MemSpace M>

CoreStateInterface const & celeritas::Stepper< M >::state ( ) const

inlinefinalvirtual

Get the core state interface for diagnostic output.

Implements celeritas::StepperInterface.

valid()

template<MemSpace M>

bool celeritas::Stepper< M >::valid ( ) const

inlinefinalvirtualnoexcept

Whether an asynchronous step result can be retrieved.

Implements celeritas::StepperInterface.

wait()

template<MemSpace M>

void celeritas::Stepper< M >::wait ( ) const

finalvirtual

Wait for the asynchronous step to complete without consuming its result.

Implements celeritas::StepperInterface.

warm_up()

template<MemSpace M>

void celeritas::Stepper< M >::warm_up ( )

finalvirtual

Run all step actions with no active particles.

The warmup stage is useful for profiling and debugging since the first step iteration can do the following:

• Initialize asynchronous memory pools
• Interrogate kernel functions for properties to be output later
• Allocate "lazy" auxiliary data (e.g. action diagnostics)

Implements celeritas::StepperInterface.

---

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

• Stepper.hh
• Stepper.cc