C interface
This section provides information on how to interface an existing geometry engine with Goupil, at the C level. To adapt a specific geometry engine to Goupil, one needs to create a concrete implementation of Goupil’s C interface, which is thus called an adapter herein. The description section below offers insight into how to implement an adapter, while the functions and types sections provide a technical overview.
Note
Goupil comes with a source distribution of a Geant4 adapter, which also serves as a detailed example of an adapter implementation. For instructions on how to use this adapter, see the Overview section.
Warning
Prior knowledge of Goupil’s geometry model is assumed in this section. To aid comprehension, it is advisable to first become acquainted with ExternalGeometry objects through the Python interface.
Description
The adapter’s main purpose is to provide Goupil with a Monte Carlo geometry that
has ray tracing capabilities. This geometry should be packaged in a shared
library, requiring an entry point at runtime. The entry point is defined as the
goupil_initialise function.
Note
The goupil_initialise function must be
implemented exactly as written to ensure proper location by Goupil when
loading the shared library.
The adapter must implement two crucial objects to interact with the Monte Carlo geometry. The first object, goupil_geometry_definition, is used by Goupil to build a replica of the Monte Carlo geometry using its internal representation. The adapter must ensure that the associated Monte Carlo geometry remains unchanged and active throughout the lifetime of the definition object. Conversely, when the definition object is destroyed, the Monte Carlo geometry is no longer used.
The second object, goupil_geometry_tracer, is used by Goupil to navigate through
the geometry during Monte Carlo steps. The adapter must conform to a
step-by-step algorithm, starting with a reset call, and then chaining sequences of
trace and update calls.
Note
Unlike the goupil_geometry_definition object, tracer objects are volatile. This means that multiple tracer objects may be created and destroyed during the lifetime of a definition object. However, the adapter’s implementation must ensure that the associated geometry object remains unchanged and alive throughout the lifetime of the tracers.
Goupil’s C interface defines additional types that act as containers or interfaces to containers. Please refer to the types section below for a complete list.