src/api/simphony.h

0001 /**
0002  * @file simphony.h
0003  * Provides the public interface to the process-wide Simphony geometry and GPU runtime.
0004  *
0005  * Initialize once before simulating or saving geometry. The runtime supports
0006  * one geometry and one pending event; there is no shutdown or geometry-replacement
0007  * operation. State-changing calls are serialized, but callers must also
0008  * coordinate access to shared Geant4 and lower-level simulation state.
0009  */
0010
0011 #pragma once
0012
0013 #include <filesystem>
0014
0015 #include "SensorIdentifier.h"
0016
0017 class G4VPhysicalVolume;
0018
0019 namespace simphony
0020 {
0021 /** Selects the GPU availability policy for initialize(). */
0022 enum class GpuRequirement
0023 {
0024     /** Require a GPU backend; fail if no CUDA-capable GPU is available. */
0025     Required,
0026     /** Create a GPU backend if available; otherwise convert geometry only. */
0027     Optional,
0028     /** Convert geometry without attempting GPU backend initialization. */
0029     Disabled,
0030 };
0031
0032 /** Specifies geometry translation and GPU initialization options. */
0033 struct GeometryOptions
0034 {
0035     /**
0036      * Borrowed sensor identifier, or nullptr to use the default identifier.
0037      *
0038      * @note A supplied identifier must remain valid for the runtime's lifetime.
0039      */
0040     SensorIdentifier* sensor_identifier = nullptr;
0041
0042     /** GPU availability policy; a GPU is required by default. */
0043     GpuRequirement gpu = GpuRequirement::Required;
0044 };
0045
0046 /**
0047  * Translates a Geant4 world and initializes the selected backend.
0048  *
0049  * Repeating this call with the same world pointer, sensor identifier pointer,
0050  * and GPU policy is a no-op. Geometry is not saved automatically.
0051  *
0052  * If geometry translation or backend creation throws, its exception propagates
0053  * and subsequent initialize() calls are rejected because lower-level global
0054  * state may be partially populated. Restart the process to try again.
0055  * Validation failures before runtime construction can be retried.
0056  *
0057  * @param world non-null, fully constructed world. Ownership remains with the
0058  * caller; keep the geometry alive and unchanged for the runtime's lifetime.
0059  * @param options translation options, copied by the runtime without taking
0060  * ownership of the sensor identifier.
0061  * @throws std::invalid_argument if world is nullptr.
0062  * @throws std::logic_error if already initialized with different inputs or a
0063  * previous geometry/backend initialization failed.
0064  * @throws std::runtime_error if a required GPU is unavailable or runtime
0065  * creation reports failure.
0066  */
0067 void initialize(
0068     const G4VPhysicalVolume* world,
0069     const GeometryOptions&   options = {});
0070
0071 /**
0072  * Queries initialization status.
0073  *
0074  * @return whether initialize() has completed successfully.
0075  */
0076 bool is_initialized() noexcept;
0077
0078 /**
0079  * Queries GPU backend availability.
0080  *
0081  * @return whether this runtime has a GPU backend. False before initialization
0082  * and after geometry-only initialization; this is not a hardware probe.
0083  */
0084 bool has_gpu() noexcept;
0085
0086 /**
0087  * Simulates an event using the GPU backend and its prepared event inputs.
0088  *
0089  * @param event_id non-negative event identifier forwarded to the backend.
0090  * @param reset if true, clean up the event before returning. If false (the
0091  * default), retain event data for retrieval and call reset(event_id) afterward,
0092  * before simulating another event.
0093  * @throws std::invalid_argument if event_id is negative.
0094  * @throws std::logic_error if uninitialized, no GPU backend exists, or a previous
0095  * event is awaiting reset.
0096  */
0097 void simulate(int event_id, bool reset = false);
0098
0099 /**
0100  * Cleans up the event retained by simulate(event_id, false).
0101  *
0102  * @param event_id non-negative identifier of the pending event; must match the
0103  * simulate() call.
0104  * @throws std::invalid_argument if event_id is negative.
0105  * @throws std::logic_error if uninitialized, no GPU backend exists, no event is
0106  * pending, or event_id does not match the pending event.
0107  * @note This resets event data, not the runtime or its geometry.
0108  */
0109 void reset(int event_id);
0110
0111 /**
0112  * Saves the initialized geometry, with or without a GPU backend.
0113  *
0114  * @param directory non-empty destination for origin.gdml and the CSGFoundry/
0115  * export, including associated simulation data. Use a fresh destination to
0116  * avoid mixing files from different exports.
0117  * @throws std::invalid_argument if directory is empty.
0118  * @throws std::logic_error if the runtime is uninitialized.
0119  */
0120 void save_geometry(const std::filesystem::path& directory);
0121 } // namespace simphony