added deploy to docker hub personal space

maureeungaro · maureeungaro · commit 3010bbf758cb · 2026-06-18T15:55:21.000-04:00
diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -205,6 +205,11 @@ jobs:
       matrix: ${{ fromJSON(needs.discover.outputs.matrix_manifest) }}
     env:
       TAG4: ${{ format('{0}-{1}-{2}', matrix.gemc_tag, matrix.image, matrix.image_tag) }}
+      # Docker Hub mirror target. Steps are skipped automatically when the
+      # DOCKERHUB_USERNAME secret is not configured (e.g. on forks).
+      # Override the namespace with the DOCKERHUB_REPO repo variable.
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_REPO: ${{ vars.DOCKERHUB_REPO || 'docker.io/maureeungaro/gemc' }}
     steps:
       - name: Checkout repository
         uses: actions/checkout@v6
@@ -218,6 +223,14 @@ jobs:
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
+      - name: Log in to Docker Hub
+        if: ${{ env.DOCKERHUB_USERNAME != '' }}
+        uses: docker/login-action@v4
+        with:
+          registry: docker.io
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
       - name: Set up Buildx
         uses: docker/setup-buildx-action@v4
 
@@ -243,6 +256,17 @@ jobs:
             docker buildx imagetools create -t "$BASE_TAG" "$AMD_TAG"
           fi
 
+      - name: Mirror manifest to Docker Hub
+        if: ${{ env.DOCKERHUB_USERNAME != '' }}
+        shell: bash
+        run: |
+          # Copy the already-built multi-arch manifest from GHCR to Docker Hub
+          # registry-to-registry (no pull, no rebuild).
+          SRC="${{ needs.discover.outputs.image }}:${{ env.TAG4 }}"
+          DST="${DOCKERHUB_REPO}:${{ env.TAG4 }}"
+          echo "Mirroring $SRC -> $DST"
+          docker buildx imagetools create -t "$DST" "$SRC"
+
       - name: Download logs artifacts (all arches)
         if: ${{ always() }}
         uses: actions/download-artifact@v7
@@ -274,6 +298,37 @@ jobs:
           path: ${{ env.MANIFEST_SUMMARY_FILE }}
           if-no-files-found: warn
 
+  # Push the Docker Hub overview README once per deploy. Skipped automatically
+  # when the DOCKERHUB_USERNAME secret is absent (e.g. on forks).
+  dockerhub_readme:
+    name: Update Docker Hub description
+    needs: manifest
+    if: ${{ always() && needs.manifest.result == 'success' }}
+    runs-on: ubuntu-latest
+    env:
+      DOCKERHUB_USERNAME: ${{ secrets.DOCKERHUB_USERNAME }}
+      DOCKERHUB_REPO: ${{ vars.DOCKERHUB_REPO || 'docker.io/maureeungaro/gemc' }}
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ github.event.workflow_run.head_sha }}
+
+      - name: Resolve Docker Hub repository path
+        if: ${{ env.DOCKERHUB_USERNAME != '' }}
+        shell: bash
+        run: echo "DH_REPO_PATH=${DOCKERHUB_REPO#docker.io/}" >> "$GITHUB_ENV"
+
+      - name: Push README to Docker Hub
+        if: ${{ env.DOCKERHUB_USERNAME != '' }}
+        uses: peter-evans/dockerhub-description@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          repository: ${{ env.DH_REPO_PATH }}
+          short-description: "Database-driven Geant4 Monte-Carlo simulation framework (GEMC)"
+          readme-filepath: ./ci/dockerhub/README.md
+
   final:
     name: Deploy - summary
     if: >-
diff --git a/ci/dockerhub/README.md b/ci/dockerhub/README.md
@@ -0,0 +1,108 @@
+# GEMC — Geant4 Monte-Carlo simulation framework
+
+**GEMC** (the *GEant Monte-Carlo*) is a database-driven [Geant4](https://geant4.web.cern.ch) application for
+detector and radiation-transport simulations. Detector descriptions live outside the compiled C++ application:
+you define geometry, materials, optics, sensitive detectors, and run configuration in Python or data files, and
+GEMC loads them at run time to execute the full Geant4 pipeline.
+
+These images ship a ready-to-run GEMC development environment — the compiled `gemc` simulator, the bundled
+`pygemc` Python tools, and all Geant4 dependencies — so you can simulate without managing a local Geant4 build.
+
+- 🏠 Homepage & docs: https://gemc.github.io/home/
+- 📦 Source: https://github.com/gemc/src
+- 🐍 Python API (`pygemc`): https://pypi.org/project/pygemc/
+
+> These images are mirrored from the canonical GitHub Container Registry build at `ghcr.io/gemc/src`.
+> The two registries carry identical content and tags; use whichever is closer to your infrastructure.
+
+<br/>
+
+## Quick start
+
+```shell
+docker run -it --rm -v "$PWD":/work docker.io/maureeungaro/gemc:dev-ubuntu-24.04 bash
+```
+
+Inside the container the `gemc` binary and the `pygemc` Python environment are already on the `PATH`:
+
+```shell
+gemc -v                         # version sanity check
+gemc-system-template -s counter # scaffold a minimal detector system
+cd counter && ./counter.py      # build geometry (writes gemc.db)
+gemc counter.yaml               # run the simulation
+gemc-analyzer counter_t0_digitized.csv totEdep --kind csv --bins 50
+```
+
+<br/>
+
+## Supported tags
+
+Tags follow the pattern `<gemc-version>-<os>-<os-version>` and are multi-architecture
+(`linux/amd64` + `linux/arm64`, except Arch Linux which is `amd64`-only).
+
+| OS         | Example tag          | Architectures    |
+|------------|----------------------|------------------|
+| AlmaLinux  | `dev-almalinux-10`   | `amd64`, `arm64` |
+| Arch Linux | `dev-archlinux-latest` | `amd64`        |
+| Debian     | `dev-debian-13`      | `amd64`, `arm64` |
+| Fedora     | `dev-fedora-44`      | `amd64`, `arm64` |
+| Ubuntu     | `dev-ubuntu-24.04`   | `amd64`, `arm64` |
+| Ubuntu     | `dev-ubuntu-26.04`   | `amd64`, `arm64` |
+
+The `dev` prefix tracks the latest `main`; versioned release tags follow the same scheme.
+
+<br/>
+
+## What's inside
+
+- The compiled `gemc` Geant4 simulator
+- The bundled `pygemc` Python environment (geometry building, PyVista preview, VTK.js export, analyzer)
+- Geant4, CLHEP, Xerces-C, and the supporting toolchain
+
+Key GEMC features:
+
+- Python-first detector definition through `pygemc`
+- Geometry/material storage in SQLite or GEMC ASCII databases; imports from GDML and CAD meshes
+- Built-in sensitive-detector digitizations: `flux`, `gPhotonDetector`, `dosimeter`, `particle_counter`
+- C++ plugin infrastructure for custom digitization, fields, particle readers, and output streamers
+- Output streamers for ASCII, CSV, JSON, JLAB SRO, and optional ROOT
+- Magnetic-field support, including a built-in multipole field plugin
+- Interactive Geant4/Qt visualization and off-screen image generation
+
+<br/>
+
+## Mounting your work
+
+The examples above mount the current directory at `/work`. Use a bind mount to keep geometry scripts, steering
+cards, and output on the host:
+
+```shell
+docker run -it --rm -v "$PWD":/work -w /work docker.io/maureeungaro/gemc:dev-ubuntu-24.04 bash
+```
+
+For the interactive Geant4/Qt GUI and Apptainer recipes, see the
+[installation page](https://gemc.github.io/home/installation/).
+
+<br/>
+
+## Documentation & support
+
+- [Installation guide](https://gemc.github.io/home/installation/)
+- [Quickstart tutorial](https://gemc.github.io/home/documentation/quickstart/)
+- [Examples gallery](https://gemc.github.io/home/examples/)
+- [Issue tracker](https://github.com/gemc/src/issues)
+
+<br/>
+
+## Citation
+
+If you use GEMC in scientific work, please cite:
+
+> M. Ungaro, "Geant4 Monte-Carlo (GEMC) A database-driven simulation program," EPJ Web of Conferences 295,
+> 05005 (2024). https://doi.org/10.1051/epjconf/202429505005
+
+## License
+
+GEMC is distributed under the project license (see the [source repository](https://github.com/gemc/src/blob/main/LICENSE.md)).
+The images also contain separately licensed third-party components, including Geant4, CLHEP, Qt, ROOT, SQLite, and
+Assimp.
diff --git a/gemc.cc b/gemc.cc
@@ -47,9 +47,13 @@ int main(int argc, char* argv[]) {
 	// random engine set by options
 	gemc::start_random_engine(gopts, log);
 
+	// GUI runs are interactive and short-lived; use the serial run manager to avoid repeatedly
+	// starting task workers from the Qt event loop on each Run button click.
+	const auto runManagerType = gui ? G4RunManagerType::SerialOnly : G4RunManagerType::Default;
+
 	// init geant4 run manager with then number of threads coming from options. always fails if unavailable
 	auto runManager = std::unique_ptr<G4RunManager>(
-		G4RunManagerFactory::CreateRunManager(G4RunManagerType::Default, true, nthreads));
+		G4RunManagerFactory::CreateRunManager(runManagerType, true, nthreads));
 
 	// Pre-load streamer plugins before Geant4 creates worker threads. Sanitized Linux
 	// builds can fail late dlopen() calls from workers with static TLS exhaustion.
diff --git a/gemc/eventDispenser/eventDispenser.cc b/gemc/eventDispenser/eventDispenser.cc
@@ -14,11 +14,22 @@
 #include <utility>
 
 // geant4
+#include "G4GeometryManager.hh"
 #include "G4UImanager.hh"
 #include "G4RunManager.hh"
 
 using namespace std;
 
+namespace {
+void closeOpenGeometryBeforeBeamOn(const std::shared_ptr<GLogger>& log) {
+	auto* geometryManager = G4GeometryManager::GetInstanceIfExist();
+	if (!geometryManager || geometryManager->IsGeometryClosed()) { return; }
+
+	log->info(1, "Geometry is open before BeamOn; closing it before event processing.");
+	geometryManager->CloseGeometry();
+}
+}
+
 // Constructor summary:
 // - Reads configuration (number of events, run number, optional run-weight file).
 // - Builds runWeights/runEvents/listOfRuns when weights are provided.
@@ -188,6 +199,7 @@ int EventDispenser::processEvents() {
 		// Dispatch all events for this run in a single call.
 		// The command string is a standard Geant4 UI command: \c /run/beamOn <N>.
 		log->info(1, "Processing ", nevents, " events in one go");
+		closeOpenGeometryBeforeBeamOn(log);
 		g4uim->ApplyCommand("/run/beamOn " + to_string(nevents));
 		// Take the screenshot after BeamOn returns. At this point G4VisManager::EndOfRun()
 		// has already joined the vis subthread (ARM64 offset 0xa35f8: bl thread::join), so
diff --git a/gemc/gfields/examples/field_points.txt b/gemc/gfields/examples/field_points.txt
@@ -0,0 +1,3 @@
+# x y z field-query points
+0*cm 0*cm 0*cm
+10*cm, 0*cm, 0*cm
diff --git a/gemc/gfields/gfield_options.cc b/gemc/gfields/gfield_options.cc
@@ -153,6 +153,37 @@ std::vector<GFieldDefinition> get_GFieldDefinition(const std::shared_ptr<GOption
 		gfield_defs.push_back(gfield_def);
 	}
 
+	// Generic plugin-backed fields:
+	// Each "gfields" entry names a field, selects a plugin through "type", and carries an arbitrary
+	// set of scalar parameters that are forwarded verbatim to the plugin via field_parameters. This
+	// lets external plugins (e.g. clas12 mapped fields) be configured without changing this parser.
+	auto gfields_node = gopts->getOptionNode("gfields");
+	for (auto gfields_item : gfields_node) {
+		GFieldDefinition gfield_def = GFieldDefinition();
+
+		// Core identity and integration configuration (the schema-defined keys).
+		gfield_def.name = gopts->get_variable_in_option<std::string>(
+			gfields_item, "name", goptions::NODFLT);
+		gfield_def.type = gopts->get_variable_in_option<std::string>(
+			gfields_item, "type", goptions::NODFLT);
+		gfield_def.integration_stepper = gopts->get_variable_in_option<std::string>(
+			gfields_item, "integration_stepper", GFIELD_DEFAULT_INTEGRATION_STEPPER);
+		gfield_def.minimum_step = gutilities::getG4Number(gopts->get_variable_in_option<std::string>(
+			gfields_item, "minimum_step", GFIELD_DEFAULT_MINIMUM_STEP));
+
+		// Every remaining (scalar) key is forwarded to the plugin as a string parameter.
+		// Nested maps/sequences are not supported here: plugin parameters must be scalar values.
+		for (auto it = gfields_item.begin(); it != gfields_item.end(); ++it) {
+			auto key = it->first.as<std::string>();
+			if (key == "name" || key == "type" || key == "integration_stepper" || key == "minimum_step") {
+				continue;
+			}
+			gfield_def.add_map_parameter(key, it->second.as<std::string>());
+		}
+
+		gfield_defs.push_back(gfield_def);
+	}
+
 	return gfield_defs;
 }
 
@@ -184,6 +215,22 @@ GOptions defineOptions() {
 	};
 	goptions.defineOption("gmultipoles", "define the e.m. gmultipoles", gmultipoles, help);
 
+	std::string gfields_help;
+	gfields_help = "Adds a generic, plugin-backed electromagnetic field to the simulation. \n \n";
+	gfields_help += "The 'type' selects the plugin shared library named gfield<type>Factory. \n";
+	gfields_help += "Any additional scalar keys are forwarded verbatim to that plugin as string \n";
+	gfields_help += "parameters (so the plugin alone decides which parameters it understands). \n \n";
+	gfields_help += "Mandatory keys: name, type. \n \n";
+	gfields_help += "Example (clas12 binary mapped field from the clas12-systems plugin): \n";
+	gfields_help += "-gfields=\"[{name: clas12, type: clas12bin, solenoid: solenoid_map, torus: torus_map}]\"\n";
+	std::vector<GVariable> gfields = {
+		{"name", goptions::NODFLT, "Field name (unique key used by GMagneto maps)"},
+		{"type", goptions::NODFLT, "Field type; selects the plugin shared library gfield<type>Factory"},
+		{"integration_stepper", GFIELD_DEFAULT_INTEGRATION_STEPPER, "Geant4 integration stepper name (string)"},
+		{"minimum_step", GFIELD_DEFAULT_MINIMUM_STEP, "Minimum step for the G4ChordFinder (Geant4 length units)"}
+	};
+	goptions.defineOption("gfields", "define a generic plugin-backed e.m. field", gfields, gfields_help);
+
 	goptions.defineOption(
 		GVariable("fieldAt", UNINITIALIZEDSTRINGQUANTITY, "query all configured fields at x y z"),
 		"Evaluate all configured electromagnetic fields at one absolute coordinate.\n \n"
diff --git a/releases/0.4.md b/releases/0.4.md
@@ -2,15 +2,17 @@
 
 This version includes:
 
-
+- Field query options to print configured magnetic-field values at absolute coordinates.
 
 
 
 <br/>
 
 # Release notes
 
-
+- Added `-fieldAt="x y z"` and `-fieldMapPoints=file.txt` to evaluate configured gfield maps at
+  absolute coordinates with unit-bearing input, printing coordinates and field components with
+  `G4BestUnit`.
 
 <br/>
 
@@ -22,13 +24,13 @@ This version includes:
 
 ## Examples
 
-
+- Added gfield example coverage for direct coordinate queries and ASCII point-list input.
 
 <br/>
 
 ## Tests
 
-
+- Added gfield tests for `-fieldAt` and `-fieldMapPoints` query workflows.
 
 <br/>
 
@@ -77,3 +79,8 @@ Both x86_64 and ARM64 platforms are supported.
 <br/>
 
 ## Detailed list of changes and fixes
+
+- Added gfield query mode: `-fieldAt="x y z"` accepts one unit-bearing coordinate triplet, while
+  `-fieldMapPoints=file.txt` reads one `x y z` triplet per non-comment ASCII line. Query mode loads
+  the configured field definitions, prints one result row per field and point, and exits before normal
+  simulation setup.

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+# x y z field-query points`
	`2`	`+0cm 0cm 0*cm`
	`3`	`+10cm, 0cm, 0*cm`