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 a step with existing states and any staged primary batch.

void	async (SpanConstPrimary primaries) final
	Copy new primaries into owned storage and start a step with them.

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.

size_type	primary_capacity () const noexcept final
	Fixed capacity of each stepper-owned primary buffer.

size_type	initializer_capacity () const noexcept final
	Return the fixed capacity of the track initializer queue.

size_type	secondary_capacity () const noexcept final
	Fixed capacity of the per-step secondary stack.

size_type	num_buffered_primaries () const noexcept final
	Number of primaries accumulated in the producer buffer.

void	push_primary (Primary const &primary) final
	Add a primary to the producer buffer.

void	stage_primaries () final
	Stage the producer buffer for transport.

SpanConstPrimary	staged_primaries () const noexcept final
	Access the unsubmitted primary batch staged for the next step.

StepperResult	operator() () final
	Transport already-initialized states.

void	stage_primaries (SpanConstPrimary primaries) final
	Copy user-provided primaries into owned storage and stage them.

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.

The two primary buffers are reserved to primary_capacity at construction, so accumulating and staging primaries within capacity does not reallocate. Device buffers use pinned host memory so inserting a staged batch can enqueue its host-to-device copy. The submitted source storage is retained until that copy completes; same-stream ordering ensures the step actions see the copied input. Reusing a submitted source may wait for its copy event, but does not wait for the full step to complete.

The following sequence overlaps production of a later primary batch with an outstanding result:

Stepper<MemSpace::device> step(input);
 
step.async(make_span(first_primaries));
for (Primary primary : second_primaries)
{
    step.push_primary(std::move(primary));
}
step.stage_primaries();
StepperResult result = step.get();
do
{
    // Submit the staged batch while continuing any active tracks
    step.async();
    result = step.get();
} while (result);

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. Primary buffering has an independent state, tracked by primary_phase_ and primary_copy_done_. The staged storage remains internal while a copy source is submitted, but the public staged_primaries accessor returns only an unsubmitted batch:

Primary phase	Producer	Staged storage	Accessor	Copy event
`empty`	May fill	Empty	Empty	Null/ready or allocated/ready
`staged`	May fill	Next input	Next input	Recorded after H2D copy
`submitted`	May fill	Prior copy source	Empty	Pending or ready

Calling stage_primaries changes empty to staged. Calling async changes staged to submitted after the actions have been enqueued. A later stage_primaries call may reclaim a submitted source after waiting only for its copy event, then stage the producer buffer. Calling get also reclaims a submitted source, but leaves a next staged batch unchanged. Host copies complete synchronously, so primary_copy_done_ is null and reclaiming the source does not wait.

The expected state transitions are

no result + producer -- async() --> valid result + same producer
no result + no queued input -- async(primaries) --> valid result
valid result -- ready() or wait() --> valid result
valid result -- get() --> no result
 
producer -- stage_primaries() --> staged
valid result + producer -- stage_primaries() --> valid result + staged
staged + no result -- async() --> submitted + valid result
submitted + producer -- stage_primaries() --> staged

Calling ready or wait repeatedly with a valid result is allowed. The next async call is allowed only after get consumes the previous result. Primaries may be pushed and staged while a result is valid, and the producer may begin filling again while that next batch is staged. The staged batch cannot be submitted until the prior result is consumed. Calls to warm_up, reset_state, and reseed are rejected while a result or queued primary batch exists. Calling kill_active permits buffered primaries but rejects a pending result or staged batch. 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.

Public Types

Public Member Functions

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ actions()

◆ async() [1/2]

◆ async() [2/2]

◆ get()

◆ initializer_capacity()

◆ kill_active()

◆ num_buffered_primaries()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ primary_capacity()

◆ push_primary()

◆ ready()

◆ reseed()

◆ secondary_capacity()

◆ sp_state()

◆ stage_primaries() [1/2]

◆ stage_primaries() [2/2]

◆ staged_primaries()

◆ state()

◆ valid()

◆ wait()

◆ warm_up()