Introduction

The GField framework is a plugin-driven module that provides magnetic-field support for GEMC simulations. Users configure one or more magnetic fields through options (typically YAML-derived), and the framework:

translates those options into GFieldDefinition objects,
dynamically loads field plugins,
instantiates concrete GField implementations,
and creates a G4FieldManager for each field so Geant4 can integrate particle motion in the field.

The core API is intentionally small:

GField defines the field interface (evaluation + manager construction support).
GFieldDefinition carries configuration and plugin identity.
GMagneto is the owner/registry that loads fields and holds their managers.

Ownership and lifecycle

Configuration ownership: options are owned externally (e.g. by the application); the module receives them as shared pointers.
Field ownership: GMagneto owns all instantiated field objects and keeps them alive for its lifetime.
Manager ownership: GMagneto also owns the G4FieldManager objects returned by create_FieldManager().

In a typical application:

The application builds a GOptions object using gfields::defineOptions().
The application constructs GMagneto.
The application attaches a G4FieldManager to a volume by looking up the desired field name.

Architecture

Design notes

Plugin boundary: concrete fields are implemented in shared libraries and must export a C symbol named GFieldFactory.
Configuration model: field configuration is stored as strings in field_parameters to preserve unit expressions; the concrete implementation parses/caches values in load_field_definitions().
Stepping: create_FieldManager() creates the stepping components: G4Mag_UsualEqRhs, an integration stepper, a G4ChordFinder, and finally the G4FieldManager.

Available Options and their usage

This module reads the following option keys from the runtime option provider:

gmultipoles
- Type: sequence of maps
- Meaning: define one or more ideal multipole fields (each entry becomes one named field)
- Behavior:
  - each entry is translated into a GFieldDefinition
  - each definition is associated with the plugin type "multipoles"
  - the field implementation parses unit-bearing strings during field initialization
- Subkeys used by this module:
  - name (string, mandatory): unique field key used by getField()
  - integration_stepper (string): Geant4 integration stepper name
  - minimum_step (string): Geant4 length expression for the chord-finder minimum step
  - pole_number (string, mandatory): even integer >= 2 (2=dipole, 4=quadrupole, ...)
  - vx, vy, vz (string): origin coordinates (Geant4 length units)
  - rotation_angle (string): roll rotation about rotaxis (Geant4 angle units)
  - rotaxis (string, mandatory): one of X, Y, Z
  - strength (string, mandatory): field strength in Tesla (defined at 1 m reference radius for multipoles)
  - longitudinal (string/boolean-like): if true, return a uniform field aligned with rotaxis (solenoid-like)

Module verbosity

The module uses the loggers gfield and gmagneto. Typical verbosity behavior:

Level 0: high-level summary and critical configuration messages.
Level 1: field-definition and plugin-loading details (which fields were created, parsed parameters).
Level 2: per-call or fine-grained diagnostic output (e.g. detailed field evaluation logging in some implementations).
Debug: intended for intensive developer diagnostics (tight loops, repeated calls, full internal dumps).

Examples

The module includes small example programs demonstrating usage.

example_test_gfield_dipole : Minimal setup: define options, build GMagneto, query a field, and evaluate B.