Context

class Context

Owns the trainable globals and loaded matrix elements for one device.

The state a compiled Function runs against: the named, persistent Tensor globals it reads and writes (network weights, VEGAS grids, …) and the MatrixElementApi libraries loaded via load_matrix_element. All globals and matrix elements live on the same device. Training and generation typically use two contexts, one per role, and periodically sync weights with copy_globals_from.

Public Functions

inline Context(int thread_count = -1)

A context on the CPU, with thread_count worker threads (-1 for the hardware concurrency).

inline Context(DevicePtr device, int thread_count = -1)

A context on device, with thread_count worker threads (-1 for the hardware concurrency).

Context(Context&&) = delete

Context &operator=(Context&&) = delete

Context(const Context&) = delete

Context &operator=(const Context&) = delete

const MatrixElementApi &load_matrix_element(const std::string &file, const std::string &param_card, const std::unordered_map<std::string, double> &parameters = {})

Load the UMAMI matrix element from file, initialized with param_card.

Every entry of parameters is then passed to each process instance through umami_set_parameter (real value, e.g. {"bwcutoff": 15.}, the window of the $-excluded propagators); a library that rejects one of them is an error. Caches by file: loading the same file twice returns the same MatrixElementApi.

const MatrixElementApi &add_matrix_element(UmamiFunctions functions, const std::string &name, const std::string &param_card = "", const std::unordered_map<std::string, double> &parameters = {})

Add a matrix element from the UMAMI entry points in functions, without a shared library.

name identifies it in error messages, and param_card and parameters are passed on as in load_matrix_element.

Tensor define_global(const std::string &name, DataType dtype, const SizeVec &shape, bool requires_grad = false)

Create and zero-initialize a new global named name.

Tensor global(const std::string &name)

The global tensor named name.

bool global_requires_grad(const std::string &name)

Whether the global named name accumulates a gradient during training.

void set_global_requires_grad(const std::string &name, bool value)

Set whether the global named name accumulates a gradient.

bool global_exists(const std::string &name)

Whether a global named name exists.

std::vector<std::string> global_names() const

Names of every global.

void delete_global(const std::string &name)

Remove the global named name.

void copy_globals_from(Context &context)

Overwrite every global also present in context with its value there.

Tensor reallocate_globals_contiguously(const std::vector<std::string> &names)

Repack the globals in names into one contiguous allocation, for example before handing them to an external optimizer.

const MatrixElementApi &matrix_element(std::size_t index) const

The matrix element previously loaded at position index; see load_matrix_element.

void save_globals(const std::string &file) const

Write every global to the tar archive file, as one .npy file per name.

void load_globals(const std::string &file)

Define a global from every .npy file in the tar archive file, named after the file.

inline DevicePtr device()

The device every global and matrix element of this context lives on.

inline ThreadPool &thread_pool()

The thread pool backing this context’s device-local resources.

inline std::size_t unique_seed_index()

The next value of a per-context counter, used to derive independent RNG seeds; see DerivedSeed.

Tensor cached_tensor(std::size_t size)

A scratch tensor of at least size bytes, reused from a pool when possible.

inline void reset_cache()

Drop every scratch tensor held by cached_tensor.

template<typename T>
inline ThreadResource<T> &global_resource(const std::string &name, std::function<T()> constructor, std::optional<std::function<void(T&)>> destructor = std::nullopt)

A per-thread resource named name, created with constructor on first access and torn down with destructor.

Not thread-safe: callers must acquire the reference once during single-threaded initialization (e.g. a Runtime constructor) and reuse it.