Generator manipulations

Upcoming in the next release. Use a current development build of gemc for these examples. See the installation guide for the executable and Python environment.

Eleven independent steering cards isolate vertex smearing, fixed angles, and angular sampling. Each generates a 1 GeV geantino inside the same small tube target to represent a target event. The plots below come from fresh simulations: 5,000 throws per card, checked against the generated-particle records before plotting. Every case also includes its own GEMC view of 100 events.

Browse the source example, including the geometry, complete YAML cards, and automated checks.

Quickstart

Copy the example from a development installation and generate its ASCII geometry:

cp -r "$GEMC_HOME/examples/basic/generator_manipulations" .
cd generator_manipulations
python generator_manipulations.py -f ascii
gemc uniform_z.yaml -gui

Generate events with the GUI beam-on control, then open the Analyzer. The XY smearing cards prepare one 2D Y-versus-X plot. Z smearing and fixed angles prepare three histograms; other cards prepare four plots. All cards enable accumulation across beam-on calls. Qt Charts is required for the GUI Analyzer. Run any card without -gui to produce a seeded 5,000-event CSV sample instead:

gemc uniform_z.yaml

Each card has its own output prefix. For example, uniform_z produces the generated and true-information CSV streams used to check that the target records exactly the vertices that were thrown.

Geometry and recorded quantities

The vacuum world contains one liquid hydrogen tube, centered at the origin, with radius 25 mm and full length 40 mm, displayed at 20% opacity to keep trajectories visible through it. Its flux sensitivity records particles originating inside it. Smearing represents the production vertices of target events. Geantinos do not scatter or create secondary particles; recordZeroEdep: true keeps their target hits. This gives one hit per thrown particle for these configurations.

Geantinos originating at smeared vertices inside the transparent cylindrical target — The shared tube target with 100 events from the uniform-Z card, rendered by GEMC.

Vertex plots use vx, vy, and vz from the target’s true information, in mm. These are the original track vertices. The fields avgx, avgy, and avgz instead describe the positions inside the target. Angular plots use the preserved momentum components px, py, and pz, in MeV/c.

The website figures use the pygemc Analyzer plotting functions with the variables and layout defined in each card’s ganalysis block. They are offline plots of the same data fields shown in the GUI. The website’s Z-smearing figures place X and Y above a Z histogram spanning both columns; the fixed-angle figure uses one row of three histograms. The GUI uses its single-panel or four-slot layout.

Vertex cases

The smearing cards use the displaced center (2, -3, 0) mm to show that random offsets are added to the nominal position. Z smearing uses theta = 90 degrees; XY and sphere smearing use theta = 45 degrees. All vertex-smearing cards use phi = 90 degrees. Uniform and Gaussian XY vary both transverse coordinates independently and display 2D Y-versus-X maps. Separate uniform-Z and Gaussian-Z cards isolate the longitudinal spread.

uniform: each nonzero delta_vx, delta_vy, or delta_vz is a half-width about its center.
gaussian: each delta is a standard deviation. The one-dimensional plot windows show five sigma; these display limits do not truncate generation. Gaussian Z uses sigma = 3 mm, so the target half-length contains more than six sigma. Gaussian tails are unbounded; the seeded samples are checked for containment.
sphere: points are uniform throughout a sphere of radius sqrt(delta_vx^2 + delta_vy^2 + delta_vz^2). Spreads (1, 2, 2) mm give radius 3 mm, rather than three ellipsoid axes. The coordinate projections are parabolic and the radial CDF is (r/R)^3.

Uniform z

Uniform half-width in z; the other two coordinates stay fixed.

Complete uniform_z.yaml

Particle settings

gparticle:
- name: geantino
  p: 1*GeV
  theta: 90*deg
  phi: 90*deg
  vx: 2*mm
  vy: -3*mm
  vz: 0*mm
  delta_vx: 0*mm
  delta_vy: 0*mm
  delta_vz: 20*mm
  randomVertexModel: uniform

Uniform X and Y

Independent uniform x in [0, 4] mm and y in [-6, 0] mm; z = 0 mm.

Complete uniform_xy.yaml

Particle settings

gparticle:
- name: geantino
  p: 1*GeV
  theta: 45*deg
  phi: 90*deg
  vx: 2*mm
  vy: -3*mm
  vz: 0*mm
  delta_vx: 2*mm
  delta_vy: 3*mm
  delta_vz: 0*mm
  randomVertexModel: uniform

Gaussian z

Gaussian sigma in z; the other two coordinates stay fixed.

Complete gaussian_z.yaml

Particle settings

gparticle:
- name: geantino
  p: 1*GeV
  theta: 90*deg
  phi: 90*deg
  vx: 2*mm
  vy: -3*mm
  vz: 0*mm
  delta_vx: 0*mm
  delta_vy: 0*mm
  delta_vz: 3*mm
  randomVertexModel: gaussian

Gaussian X and Y

Independent Gaussian x/y: means (2, -3) mm, sigmas (4, 5) mm; z = 0 mm.

Complete gaussian_xy.yaml

Particle settings

gparticle:
- name: geantino
  p: 1*GeV
  theta: 45*deg
  phi: 90*deg
  vx: 2*mm
  vy: -3*mm
  vz: 0*mm
  delta_vx: 4*mm
  delta_vy: 5*mm
  delta_vz: 0*mm
  randomVertexModel: gaussian

Sphere

Uniform sphere centered at (2, -3, 0) mm; radius = sqrt(1^2 + 2^2 + 2^2) = 3 mm.

Complete sphere.yaml

Particle settings

gparticle:
- name: geantino
  p: 1*GeV
  theta: 45*deg
  phi: 90*deg
  vx: 2*mm
  vy: -3*mm
  vz: 0*mm
  delta_vx: 1*mm
  delta_vy: 2*mm
  delta_vz: 2*mm
  randomVertexModel: sphere

Angular cases

The angular cards fix the vertex at the target center, (0, 0, 0) mm. randomThetaModel supports uniform, gaussian, and cosine. For uniform, delta_theta is a half-width; for gaussian, it is a standard deviation. The cosine model is uniform in cos(theta) within theta +/- delta_theta, giving a density proportional to sin(theta), restricted to [0, 180] degrees. The theta-smearing cards use delta_theta: 20*deg and nominal theta = 2 degrees. Uniform sampling spans [-18, 22] degrees; Gaussian sampling has mean 2 degrees and sigma 20 degrees. Negative theta reverses the transverse momentum: the reconstructed polar angle is nonnegative, with azimuth shifted by 180 degrees. Cosine sampling spans [0, 22] degrees because its draws are restricted to physical polar angles. Phi always uses uniform sampling with half-width delta_phi; there is no randomPhiModel.

For momentum p, the expected components are:

px = p sin(theta) cos(phi)
py = p sin(theta) sin(phi)
pz = p cos(theta)

The fixed theta and phi card sets both angles to 3 and 45 degrees, respectively, and shows only the three momentum histograms. Uniform, Gaussian, and cosine theta show px vertically against pz horizontally in their 2D plots. The cosine-theta case also gives a flat pz distribution. Fixed theta with a phi spread traces an arc in the px/py projection. The wraparound case crosses 360 degrees without a discontinuity in momentum. Generated-bank angles are stored in radians; the steering cards use explicit degrees.

Fixed theta and phi

Fixed theta = 3 deg and phi = 45 deg.

Complete fixed_theta_and_phi.yaml

Particle settings

gparticle:
- name: geantino
  p: 1*GeV
  theta: 3*deg
  delta_theta: 0*deg
  randomThetaModel: uniform
  phi: 45*deg
  delta_phi: 0*deg
  vx: 0*mm
  vy: 0*mm
  vz: 0*mm
  delta_vx: 0*mm
  delta_vy: 0*mm
  delta_vz: 0*mm
  randomVertexModel: uniform

GEMC: 100 events for Fixed theta and phi.

Uniform theta

Theta uniform on [-18, 22] deg; phi = 0 deg.

Complete uniform_theta.yaml

Particle settings

gparticle:
- name: geantino
  p: 1*GeV
  theta: 2*deg
  delta_theta: 20*deg
  randomThetaModel: uniform
  phi: 0*deg
  delta_phi: 0*deg
  vx: 0*mm
  vy: 0*mm
  vz: 0*mm
  delta_vx: 0*mm
  delta_vy: 0*mm
  delta_vz: 0*mm
  randomVertexModel: uniform

Gaussian theta

Theta Gaussian with mean 2 deg and sigma 20 deg; phi = 0 deg.

Complete gaussian_theta.yaml

Particle settings

gparticle:
- name: geantino
  p: 1*GeV
  theta: 2*deg
  delta_theta: 20*deg
  randomThetaModel: gaussian
  phi: 0*deg
  delta_phi: 0*deg
  vx: 0*mm
  vy: 0*mm
  vz: 0*mm
  delta_vx: 0*mm
  delta_vy: 0*mm
  delta_vz: 0*mm
  randomVertexModel: uniform

Cosine theta

cos(theta) uniform between cos(22 deg) and cos(0 deg); phi = 0 deg.

Complete cosine_theta.yaml

Particle settings

gparticle:
- name: geantino
  p: 1*GeV
  theta: 2*deg
  delta_theta: 20*deg
  randomThetaModel: cosine
  phi: 0*deg
  delta_phi: 0*deg
  vx: 0*mm
  vy: 0*mm
  vz: 0*mm
  delta_vx: 0*mm
  delta_vy: 0*mm
  delta_vz: 0*mm
  randomVertexModel: uniform

Uniform phi

Phi uniform on [45, 135] deg at theta = 45 deg.

Complete uniform_phi.yaml

Particle settings

gparticle:
- name: geantino
  p: 1*GeV
  theta: 45*deg
  delta_theta: 0*deg
  randomThetaModel: uniform
  phi: 90*deg
  delta_phi: 45*deg
  vx: 0*mm
  vy: 0*mm
  vz: 0*mm
  delta_vx: 0*mm
  delta_vy: 0*mm
  delta_vz: 0*mm
  randomVertexModel: uniform

Phi wraparound

Phi uniform on [330, 370] deg, crossing 360 deg, at theta = 45 deg.

Complete phi_wraparound.yaml

Particle settings

gparticle:
- name: geantino
  p: 1*GeV
  theta: 45*deg
  delta_theta: 0*deg
  randomThetaModel: uniform
  phi: 350*deg
  delta_phi: 20*deg
  vx: 0*mm
  vy: 0*mm
  vz: 0*mm
  delta_vx: 0*mm
  delta_vy: 0*mm
  delta_vz: 0*mm
  randomVertexModel: uniform

Verify and reproduce

From a configured GEMC source tree, run all 11 checks:

meson test -C build --suite generator_manipulations --print-errorlogs

The checks require every vertex inside the target and one target hit per throw. They match event IDs and vertices, compare momentum components, reconstruct theta and phi modulo 360 degrees, and test the expected probability distributions. The XY checks also verify that the transverse samples are uncorrelated. The tests generate fresh geometry and output in temporary directories, so each case also works in isolation.

To regenerate this page’s images and particle settings from the website repository:

python3 scripts/generate_example_assets.py generator_manipulations

The website’s asset guide documents the required local environments. See also the internal generator guide.