CAD Example

This example imports three STL organ meshes with the GEMC CAD factory and uses the dosimeter digitization to record deposited energy and dose for each organ.

Quickstart

Copy the example to your current directory. To upload the CAD definitions, run 10 events, and produce CSV output:

cp -r $GEMC_HOME/examples/basic/cad .
cd cad
./cad.py
gemc cad.yaml -n=10

Geometry

The geometry is defined declaratively in stls/cad__default.yaml and uploaded into gemc.db by cad.py.

The CAD system named stls contains:

heart_NIH3D, a blood-material heart mesh.
respiratory_NIH3D, a translucent lung mesh made with G4_LUNG_ICRP.
liver_NIH3D, a soft-tissue liver mesh.

Each entry in stls/cad__default.yaml sets the mesh file, material, color, scale, position, and identifier. The system value must match both the gsystem name in cad.yaml and the directory that contains the STL files.

See also the CAD Imports Documentation for more information.

Interactive viewer:

Physics List

FTFP_BERT is used by default, selected in the YAML file with phys_list: FTFP_BERT.

phys_list

The physics list can be selected using the option
gemc -phys_list <value>
where <value> can be a combination of the Geant4 physics constructors separated by the + sign. For example
gemc -phys_list="FTFP_BERT + G4NeutronCrossSectionXS"
To see a list of the available Geant4 constructors:
gemc -showPhysics

Generator

The particle kinematics are defined in the YAML file:

gparticle:
  - name: gamma
    p: 1250*keV
    multiplicity: 200
    theta: 0*deg
    delta_theta: 12*deg
    phi: 0*deg
    delta_phi: 180*deg
    vz: -1000*mm

The source is placed 1 m upstream of the organs and emits a broad forward cone of 1.25 MeV gamma rays.

See also the Internal Generator Documentation for more information.

Digitization

Each organ is configured as a dosimeter sensitive detector in stls/cad__default.yaml:

defaults:
  digitization: dosimeter

volumes:
  - name: heart_NIH3D
    identifier: "organ: 1"

The dosimeter digitization creates and accumulates the variables etot and dose throughout events in a run.

\[\mathrm{dose} = \frac{\mathrm{etot}}{\mathrm{mass}}\]

where etot is the total energy deposited in each event and mass is the organ mass computed from the CAD mesh and assigned material.

See the Dosimeter Documentation for more information.

Usage

Building the detector

Use the Python script cad.py to upload the CAD definitions. The script reads stls/cad__default.yaml and stores the setup in a SQLite file named gemc.db.

./cad.py

python API

Pass -h for additional command line options:

options:
  -h, --help            show this help message and exit
  -f, --factory FACTORY
						ascii, sqlite
  -v, --variation VARIATION
                        Set variation name
  -r, --run RUN         Set run number
  -sql, --dbhost DBHOST
                        SQLite filename or MYSQL host
  -pv, --pyvista        Show geometry using pyvista (needs pyvista)
  -pvb, --pvb, --pyvista-background
                        Use PyVista BackgroundPlotter (needs pyqt6 pyvistaqt)
  -pvw, --width WIDTH   Set plotter width
  -pvh, --height HEIGHT
						Set plotter height
  -pvx, --x X           Set plotter x position
  -pvy, --y Y           Set plotter y position
  -axes, --add_axes_at_zero

If you have pyvista (see also install pyvista), you can use the -pv and -pvb options to display the setup without having to run GEMC

See also the Building Geometry for more information.

Running GEMC

The file cad.yaml can be used to run the setup. Add -gui to run interactively:

gemc cad.yaml -gui

Modify cad.yaml as needed, in particular to add particles, control the number of threads, or change the output.

Running Events

CAD simulation: gamma rays traversing the imported heart, lung, and liver meshes.

Output

The gstreamer option selects the output filename and format:

gstreamer:
  - format: csv
    filename: organs

gstreamer

The gstreamer option selects the output name and format. Run gemc help gstreamer to check its documentation:

-gstreamer=<sequence> ......: define a gstreamer output

• filename: name of output file. Default value: NODFLT
• format: format of output file. Default value: NODFLT
• type: type of output fileDefault value: event


Define output formats and filenames. 
It can be used to select <events> or <frame> streams.
The file extension is added automatically based on the format.

Supported formats:
	
  - root
  - ascii
  - csv
  - json


Output types:

  - event: write events
  - stream: write frame time snapshots

Example that defines two gstreamer outputs:

 -gstreamer="[{format: root, filename: out}, {format: csv, filename: out}]"


The produced files structure depends on the accumulation method used:

  - event-based digitization (like <flux>) will have one file per 
    thread, with "_t<thread#>" appended to the filename
  - run-based digitization (like <dosimeter>) will have one output file

See also the Output Documentation for more information.

Plotting with the GEMC Analyzer

Run GEMC with 20 events first. The default YAML file writes the analyzer CSV streams.

gemc cad.yaml -n=20

Plot the accumulated dose:

gemc-analyzer organs_digitized.csv dose --kind csv

cad accumulated dose