ChannelEventGenerator

class ChannelEventGenerator

Event generation and integration for one integration channel.

Owns one channel’s compiled integrand, unweighter and (optional) histogram runtimes, one set per Context passed to the constructor, and runs its survey, VEGAS/channel-weight optimization and unweighting. EventGenerator coordinates one ChannelEventGenerator per channel of a subprocess.

Public Functions

ChannelEventGenerator(const std::vector<ContextPtr> &contexts, const Integrand &integrand, const std::string &event_file, const std::string &weight_file, const GeneratorConfig &config, std::size_t subprocess_index, const std::string &name, const std::optional<ObservableHistograms> &histograms)

Parameters:

• contexts – One context per device to run on.

• integrand – The channel’s compiled integrand.

• event_file – Path of the weighted event file.

• weight_file – Path of the max-weight tracking file.

• config – Generator configuration.

• subprocess_index – Index of the owning subprocess.

• name – Human-readable channel name.

• histograms – Optional observable histograms filled alongside integration.

ChannelEventGenerator(ChannelEventGenerator&&) = default

ChannelEventGenerator &operator=(ChannelEventGenerator&&) = default

ChannelEventGenerator(const ChannelEventGenerator&) = delete

ChannelEventGenerator &operator=(const ChannelEventGenerator&) = delete

inline const GeneratorStatus &status() const

Current progress snapshot.

inline const RunningIntegral &cross_section() const

Running cross-section estimate.

inline const RunningIntegral &abs_cross_section() const

Running estimate of the mean absolute weight.

inline std::size_t count_requested_opt() const

Weighted events requested since the last reset of count_opt, counting each job at its nominal batch size rather than its raw point count.

inline const std::vector<Histogram> &histograms() const

The filled observable histograms, if any were requested.

inline EventFile &event_file()

The weighted event file.

inline EventFile &weight_file()

The max-weight tracking file.

inline double max_weight() const

Current maximum-weight estimate, used for unweighting.

void set_fixed_max_weight(double max_weight)

Use max_weight for unweighting from now on, instead of estimating it from the generated events.

Must be positive.

void set_abs_integral_prior(double mean, double error)

Set the integral of the absolute weights known from an earlier run, with its standard error.

Both must be positive.

inline bool has_abs_integral_prior() const

Whether set_abs_integral_prior was called.

void set_integral_prior(double mean, double error)

Set the signed integral known from an earlier run, with its standard error.

bool uses_integral_prior() const

Whether this run has too few samples for an integral estimate of its own, so that EventGenerator uses the priors instead.

std::pair<double, double> integral_prior() const

The prior of the signed integral as (mean, standard error), or of the absolute one if no signed prior was set.

inline std::pair<double, double> abs_integral_prior() const

The prior of the integral of the absolute weights as (mean, standard error).

double abs_integral_estimate() const

The integral of the absolute weights: the mean of this run, combined with the prior (if any) weighted by the inverse variances.

Used to share the events between channels.

inline std::size_t batch_size() const

Current generation batch size.

inline bool needs_optimization() const

Whether a VEGAS grid or channel-weight optimization pass is still pending.

void set_target_count(std::size_t target_count)

Set the target unweighted event count; a smaller target tightens the maximum-weight estimate to the smaller truncation budget.

inline const std::unordered_set<std::string> &used_globals() const

Names of the compute-graph globals this channel’s integrand reads.

inline int event_layout_extra_flags() const

Extra EventRecord layout flags this channel’s events carry.

inline int particle_layout_extra_flags() const

Extra ParticleRecord layout flags this channel’s events carry.

inline const DataLayout &event_file_layout() const

Layout of event_file.

void unweight_file(MixMaxRandom &rand_gen)

Run a final unweighting pass over weight_file into event_file, using rand_gen.

void integrate(const GeneratorBatchJob &job)

Integrate job’s events, accumulating cross_section.

void optimize_vegas(const GeneratorBatchJob &job)

Accumulate job’s events into the VEGAS grid and channel-weight optimizers.

double channel_weight_sum(std::size_t event_count)

Sum of this channel’s weight over event_count freshly sampled events, used for multi-channel weight optimization.

void start_job(GeneratorBatchJob &job, ResultQueue &result_queue, std::optional<std::uint64_t> seed, bool is_survey, std::size_t survey_pass)

Dispatch job (a survey or generation batch) onto the thread pool, seeded from seed.

void prepare_unweight_job(GeneratorBatchJob &job) const

Snapshot max_weight into job.max_weight, at a fixed point independent of when submit_unweight_job actually dispatches it.

void submit_unweight_job(GeneratorBatchJob &job, ResultQueue &result_queue)

Submit job’s unweighting to the thread pool of its own generation context (required on GPU: unweighting does a device-to-host copy).

void start_unweight_job(GeneratorBatchJob &job, ResultQueue &result_queue)

prepare_unweight_job followed by submit_unweight_job.

std::size_t next_vegas_batch_size()

Size of the next VEGAS/channel-weight optimization batch.

void clear_events()

Discard the accumulated event and weight files.

void update_max_weight(Tensor weights)

Update max_weight from a batch of weights.

void write_events(const TensorVec &unweighted_events, double job_max_weight)

Append unweighted_events to event_file, recording job_max_weight.

void save(const std::string &file_name) const

Serialize this generator’s state to file_name; see load.

std::string to_json(bool include_estimates = false) const

The JSON text that save writes; see load_json.

With include_estimates, the current maximum weight and the integral of the absolute weights are stored as well. load_json then keeps the maximum weight fixed and uses the integral as a prior, see abs_integral_estimate.

Public Static Functions

static ChannelEventGenerator load(const std::string &channel_file, const std::vector<ContextPtr> &contexts, const std::string &event_file, const std::string &weight_file, const GeneratorConfig &config)

Reconstruct a generator previously written with save, reopening event_file and weight_file.

static ChannelEventGenerator load_json(const std::string &channel_json, const std::vector<ContextPtr> &contexts, const std::string &event_file, const std::string &weight_file, const GeneratorConfig &config)

Like load, from the JSON text produced by to_json instead of a file.