GOST — General Optics Simulation

English | 한국어

General Optics Simulation Tool — a from-scratch C++ optics engine.

GOST is a self-contained ray-tracing geometric-optics library written in modern C++ (no external math or geometry dependencies). It traces rays through scenes built from optical surfaces — refracting, reflecting, and absorbing — and is designed to grow toward wave optics, polarization, and laser optics.

Design at a glance

• ROOT-free core. All tracing, math, and geometry live in the self-contained GOST shared library and build/run without ROOT. ROOT is used only for visualisation. See DESIGN.md §1/§8.
• Geometry ≠ physics. Where a ray hits (GSGeometry) and what happens when it does (GSInterface) are independent hierarchies, composed into an element. No GSMirrorPlane-style classes.
• Solid / Logical / Physical three-tier (Geant4/TGeo style): geometry (solid) → GSElement (logical: geometry + interface) → GSPlacement (physical: element + transform). One element can be placed many times (identical lenses, mirror pairs).
• 3D-native. There are no 2D-only code paths; a "2D optics bench" is just a scene that is symmetric about z = 0.
• Propagation is a strategy. GSSystem is pure data; GSPropagator walks it, so paraxial / wave-optics propagators can slot in later without touching the scene classes.

The authoritative architecture reference is DESIGN.md.

Build

CMake-based, C++11 (bumped to 14/17 automatically if ROOT is detected). Builds without ROOT.

mkdir build && cd build
cmake ..
make

This produces:

• libGOST — the core shared library (add_library(GOST SHARED ...)).
• Test executables (in exe/, emitted at the build root) — assertion-based suites that exit non-zero on failure: test_Transform, test_Interface, test_Geometry, test_Scene, test_Propagator, and demo_procedure (the canonical usage example).
• Tutorial executables (in tutorials/) — see below.

Only include/ and src/ are globbed into the build.

Repository layout

Path	Contents
include/ + src/	Active core code (the only sources compiled into libGOST).
exe/	Test and demo executables.
tutorials/	Guided, runnable, heavily commented walkthroughs — one per layer.
macro/vis/	Interim ROOT visualisation macros (the only ROOT-dependent code).
DESIGN.md	Architecture reference.
CLAUDE.md	Contributor / assistant working notes and conventions.
doc/Doxyfile	Doxygen configuration (run doxygen doc/Doxyfile from the repo root; output in doc/doxygen/).
rootlogon.C	ROOT macro kept for future visualisation use.

Components

• L0 math — GSVector, GSMatrix, GSTransform (rigid 4×4 homogeneous), GSPoints.
• L1 solid — GSGeometry (abstract, canonical local frame) with GSGeometryPlane, GSGeometrySphere, and GSGeometryParaboloid; apertures GSShapeCircle / GSShapeRectangle. Plane + sphere + circular aperture already give real spherical lenses and mirrors; the paraboloid gives aberration-free on-axis mirrors.
• L2 physics — GSInterface (abstract) with GSInterfaceMirror, GSInterfaceRefractive (vector Snell + total internal reflection), and GSInterfaceAbsorber.
• L3 scene — GSNamed, GSElement, GSHit, GSPlacement, GSSystem (data only).
• L4 engine — GSRay / GSRaySegment (segment chain + ray state), GSPropagator (nearest-hit scan, absorber termination, world-bound escape, max-bounce guard).

The demo_procedure example focuses a biconvex lens at z ≈ 101.93 vs the thin-lens ideal of 100 (thick-lens shift) with monotone spherical aberration.

Known L1 limitation: a sphere with a circular aperture passes both poles (two caps), so a lens surface has a phantom far cap; work around it as shown in demo_procedure.cpp. The real fix (z-bounded aperture / hemisphere solid) is future L1 work.

Tutorials

Self-contained, runnable programs that link only the core (no ROOT) and check every claimed result with assertions — so each doubles as a smoke test. Build with the project; run the binaries from the build root.

Tutorial	Topic
tut01_vector	GSVector — 3D vectors (frame & unit-vector conventions).
tut02_matrix	GSMatrix — determinant, inverse, cofactors.
tut03_transform	GSTransform — rigid transforms, point vs direction.
tut04_geometry	GSGeometry — intersection, normals, apertures.
tut05_interface	GSInterface — reflection, refraction, TIR.
tut06_scene	GSElement / GSPlacement / GSSystem — building a scene.
tut07_ray_propagator	GSRay / GSPropagator — tracing a ray through a system.
tut08_full_system	Capstone — a folded bench: fold mirror → biconvex lens → detector.
tut09_paraboloid	GSGeometryParaboloid — parabolic mirror and lens.

Visualisation

The core is deliberately ROOT-free; macro/vis/ holds ROOT macros that load the pre-built libGOST.so and draw scenes (each renders headless to a PNG via root -l -b -q). They cover geometry, interfaces, single lenses, the four classic lens types, a Keplerian telescope, a step-index optical fiber, and the paraboloid. See macro/vis/README.md for prerequisites and usage.

Roadmap

• A compiled GOSTVis ROOT visualisation target (the only ROOT-linked code), replacing the macro/vis/ macros.
• Fix the sphere two-cap aperture limitation; more solids (Cylinder).
• Medium tracking (GSMedium), ray splitters + intensity weights, detector payloads, assembly flattening, a paraxial (ABCD-matrix) propagator.
• Beyond deterministic beam tracing:
  • Wave optics — a separate wave-optics propagator (interference, diffraction, phase).
  • Polarization — per-ray polarization state (s/p, later Jones/Stokes) and Fresnel R/T.
  • Laser optics.
  • Rendering-style stochastic tracing (diffuse surfaces, camera/eye rays) and Monte Carlo sampling of interface outcomes are permitted design routes (see DESIGN.md §11).

Conventions

• Class prefix GS (General optics Simulation); member variables prefixed f (e.g. fSegments); constants prefixed k (e.g. kEpsilon).
• All public/protected API in include/ carries Doxygen comments; domain-critical facts (coordinate frame, unit-vector guarantees, pointer ownership, numeric contracts) are stated explicitly. Style rules in CLAUDE.md.