yaptide · grzanka · Dec 17, 2025 · Dec 14, 2025 · Dec 14, 2025 · Dec 14, 2025
diff --git a/docs/assets/geometry/geant4_collimator_details.png b/docs/assets/geometry/geant4_collimator_details.png
diff --git a/docs/assets/geometry/geant4_cutout_details.png b/docs/assets/geometry/geant4_cutout_details.png
diff --git a/docs/assets/geometry/geant4_duplicate.png b/docs/assets/geometry/geant4_duplicate.png
diff --git a/docs/assets/geometry/geant4_duplicated.png b/docs/assets/geometry/geant4_duplicated.png
diff --git a/docs/assets/geometry/geant4_hierarchy_move.gif b/docs/assets/geometry/geant4_hierarchy_move.gif
diff --git a/docs/assets/geometry/geant4_rename.png b/docs/assets/geometry/geant4_rename.png
diff --git a/docs/assets/geometry/geant4_rename_input.png b/docs/assets/geometry/geant4_rename_input.png
diff --git a/docs/assets/geometry/geant4_water_phantom_details.png b/docs/assets/geometry/geant4_water_phantom_details.png
diff --git a/docs/assets/geometry/geant4_world_details.png b/docs/assets/geometry/geant4_world_details.png
diff --git a/docs/assets/geometry/hierarchy_add.png b/docs/assets/geometry/hierarchy_add.png
diff --git a/docs/assets/running/dataset_download_cached.png b/docs/assets/running/dataset_download_cached.png
diff --git a/docs/assets/running/dataset_download_not_cached.png b/docs/assets/running/dataset_download_not_cached.png
diff --git a/docs/assets/running/geant4_dataset_download_options.png b/docs/assets/running/geant4_dataset_download_options.png
diff --git a/docs/assets/running/start_from_input_files.png b/docs/assets/running/start_from_input_files.png
diff --git a/docs/assets/scoring/geant4_apply_filter.png b/docs/assets/scoring/geant4_apply_filter.png
diff --git a/docs/assets/scoring/geant4_detector_details.png b/docs/assets/scoring/geant4_detector_details.png
diff --git a/docs/assets/scoring/geant4_detector_details_slabyz.png b/docs/assets/scoring/geant4_detector_details_slabyz.png
diff --git a/docs/assets/scoring/geant4_filter_protons.png b/docs/assets/scoring/geant4_filter_protons.png
diff --git a/docs/assets/scoring/geant4_quantity_fluence.png b/docs/assets/scoring/geant4_quantity_fluence.png
diff --git a/docs/assets/settings/geant4_beam_adjustments.png b/docs/assets/settings/geant4_beam_adjustments.png
diff --git a/docs/geometry.md b/docs/geometry.md
@@ -82,6 +82,8 @@ In the following sections we will go through generation of simple geometry. It w
     The figure is created and its cross-sections in YX, XZ and ZY planes visible in the 3 windows in the center of the screen. 
     The 3-D projection is visible as well.
 
+    ### Water phantom
+
     Let's now add a box which will represent a water phantom in which the simulated beam will stop.
     This box will be placed inside the world box and will be 8cm x 8cm x 8cm in size.
     We are going to place it at (4,0,0) position as well.
@@ -178,6 +180,75 @@ In the following sections we will go through generation of simple geometry. It w
 
     These are the basic steps for defining geometry for CSG-based simulators.
 
-=== "🚧 Geant4"
+=== "Geant4"
+
+    ### World filled with air
+
+    Let's start with adding a box filled with air with dimensions large enough to fit the other object we would like to simulate.
+    There are two ways to add a box, either selecting `Object > Box` in Menu Bar, or clicking `+ BOX` in HIERARCHY section in GEOMETRY tab.
+
+    ![Add Figure from Object Menu](assets/geometry/menu_object_add.png)
+
+    ![Add Figure from FIGURES section](assets/geometry/hierarchy_add.png)
+
+    !!! warning
+        For Geant4, there should be only one volume at the root level, with position set to (0, 0, 0).
+
+    Let's create a box with dimensions 12cm x 10cm x 10cm, filled with air.
+    First, expand the details to see the values for DIMENSIONS and MATERIAL and the INFORMATION section to set the name.
+    Note that basic dimensions units in YAPTIDE are centimeters.
+    Let's also assign a color for the figure to differentiate it from others.
+
+    ![Configure World volume](assets/geometry/geant4_world_details.png)
+
+    ### Water phantom
+
+    Let's now add a box which will represent a water phantom in which the simulated beam will stop.
+    This box will be placed in the center of the world box and will be 8cm x 8cm x 8cm in size.
+    The dimensions are given in such way that the water phantom is fully contained in the world box.
+
+    !!! warning
+        Each Geant4 volume must be fully contained within its parent volume.
+
+    This time we're going to demonstrate how to duplicate existing figure, and then modify its dimensions.
+    Right-click on the WorldBox entry visible in the FIGURES section and click Duplicate.
+
+    ![Duplicate WorldBox](assets/geometry/geant4_duplicate.png)
+
+    The newly created figure will inherit the name from the duplicated object. An `_1` suffix will be added to the name to keep all the names unique.
+    All other properties (like position, dimensions and material) will be copied as well.
+
+    ![Duplicated WorldBox](assets/geometry/geant4_duplicated.png)
+
+    We can rename the figure from the context menu.
+
+    ![Rename World_1 to WaterPhantom](assets/geometry/geant4_rename.png)
+
+    ![Rename input](assets/geometry/geant4_rename_input.png)
+
+    Since Geant4 requires a mother-daughter volume relationship in the form of a tree structure, we move the WaterPhantom
+    under the World by dragging and dropping the label in the HIERARCHY.
+
+    ![Drag and drop in hierarchy](assets/geometry/geant4_hierarchy_move.gif)
+
+    Now let's adjust the dimensions of the new figure to 8cm x 8cm x 8cm and set the material to water.
+    Note that the two figures are now visible in the 3-D projection window and all three cross-sections.
+
+    ![WaterPhantom](assets/geometry/geant4_water_phantom_details.png)
+
+    ### Collimator
+
+    The collimator is a figure with central cutout that we want to suspend in the air, at the front of the phantom.
+    In this geometry representation we cannot cut out material, but as did with the phantom, we can replace the insides.
+    With that in mind, we first create a filled cylinder of lead, and then add an inner cylinder that will add
+    the surrounding material back - air in this case.
+
+    First, let's create an outer lead cylinder.
+
+    ![Collimator](assets/geometry/geant4_collimator_details.png)
+
+    Let's now add the insides filled with air.
+
+    ![Collimator cutout](assets/geometry/geant4_cutout_details.png)
 
-    Under development
+    These are the basic steps for defining geometry for simulators using nested volumes.
diff --git a/docs/running.md b/docs/running.md
@@ -61,12 +61,31 @@ The Simulations Page consists of 3 main sections:
     !!! note
         Large Batch Jobs may stay longer in `PENDING` state, waiting for the resources to be available.
 
-=== "🚧 Geant4"
+=== "Geant4"
 
-    Under development
+    In order to run the simulation, Geant4 needs to sample information from datasets.
+    You can choose to download them all (`FULL DATASETS`) before starting the simulation
+    (you will not be able to start the simulation before the datasets are loaded),
+    or to download the necessary files on demand (`PARTIAL DATASETS`).
 
-When the parameters are set, click `START SIMULATION` to send it to the YAPTIDE server.
-After successful submission, the simulation is in PENDING state.
+    ![Dataset download options](assets/running/geant4_dataset_download_options.png)
+
+    !!! note
+        Using `FULL DATASETS` is a recommended way. After download, the files are stored in the browser even after closing the page
+        and can be loaded back nearly instantly.
+
+    For dataset management there exist an additional Dataset Download panel. If the files have not been downloaded yet,
+    the `START DOWNLOAD` button is presented. If the application detects that the datasets are present in the browser cache,
+    the `LOAD FROM CACHE` button is shown instead.
+
+    ![Datasets not cached](assets/running/dataset_download_not_cached.png)
+
+    ![Datasets cached](assets/running/dataset_download_cached.png)
+
+    After loading the datasets, you are clear to start the simulation.
+
+When the conditions are met, and the parameters are configured, click `START SIMULATION`.
+After successful submission to local or remote worker, the simulation is in PENDING state.
 The simulation will start automatically when the resources are available, then it will change to RUNNING state,
 and you will be able to see the progress of the simulation by observing the progress bar.
 
@@ -79,6 +98,19 @@ The simulation is also present in the pinned "Last 5 simulations" section.
 
 When the simulation finishes, it will automatically navigate to Results page and display the results.
 
+### Running from input files
+
+The default source for the simulation data is the active editor project. Under the hood, the project is converted into
+input files that the specific simulator understands. You may want to modify the files directly, and start the simulation
+with the modified input.
+
+Navigate to Input Files panel, select `GENERATE FROM EDITOR` to get the files that would be submitted.
+You can modify them to your needs. When you are ready, click `RUN WITH THESE INPUT FILES`. You will see the Run form
+switches from `EDITOR PROJECT DATA` to `INPUT FILES DATA` and the files are listed. Click `START SIMULATION` to start
+with the modified files.
+
+![Running from input files](assets/running/start_from_input_files.png)
+
 ### Viewing results
 
 Once all tasks are completed, the status of the simulation will change to `COMPLETED` and you will be able to see the results of the simulation.

diff --git a/docs/scoring.md b/docs/scoring.md
@@ -24,26 +24,58 @@ Detectors can be added either by selecting `Object > Detector` in Menu Bar or cl
 
 ### Narrow cylinder along the beam axis
 
-Let's start with adding a cylinder with radius of 1cm and length of 12cm along the beam axis, spanning from -2cm to 12cm along Z axis.
-By pressing `+ DETECTOR` button a new item will be added to the list of detectors. Change the settings as follows:
+=== "SHIELD-HIT12A"
+
+    Let's start with adding a cylinder with radius of 1cm and length of 12cm along the beam axis, spanning from -2cm to 10cm along Z axis.
+    By pressing `+ DETECTOR` button a new item will be added to the list of detectors. Change the settings as follows:
+
+    - Rename the detector to `AlongBeamAxis`.
+    - Set the position in PLACEMENT section. To get correct span we set center to (0,0,4) cm.
+    - Select the geometry type. For this example, use Cyl for cylinder geometry. Change the depth and radius as below.
+    - Under GRID, change the number of bins. We divide the detector into 120 bins along the Z axis, so that each bin is 1mm long.
+
+    ![Setting up new detector](assets/scoring/detector_details.png)
+
+=== "🚧 FLUKA"
+
+    Under development
+
+=== "Geant4"
+
+    Let's start with adding a cylinder with radius of 1cm and length of 12cm along the beam axis, spanning from -6cm to 6cm along Z axis.
+    By pressing `+ DETECTOR` button a new item will be added to the list of detectors. Change the settings as follows:
 
-- Rename the detector to `AlongBeamAxis`.
-- Set the position in PLACEMENT section. To get correct span we set center to (0,0,4) cm.
-- Select the geometry type. For this example, use Cyl for cylinder geometry. Change the depth and radius as below.
-- Under GRID, change the number of bins. We divide the detector into 120 bins along the Z axis, so that each bin is 1mm long.
+    - Rename the detector to `AlongBeamAxis`.
+    - Select the geometry type. For this example, use Cyl for cylinder geometry. Change the depth and radius as below.
+    - Under GRID, change the number of bins. We divide the detector into 120 bins along the Z axis, so that each bin is 1mm long.
 
-![Setting up new detector](assets/scoring/detector_details.png)
+    ![Setting up new detector](assets/scoring/geant4_detector_details.png)
 
 When selected, the detector should be visible in the 3D and cross-section views.
 
 ### Slab in YZ plane
 
-Lets add a 1mm thick slab detector in YZ plane, spanning from -2cm to 12cm in Z direction and -5cm to 5cm in Y direction.
+=== "SHIELD-HIT12A"
+
+    Lets add a 1mm thick slab detector in YZ plane, spanning from -2cm to 10cm in Z direction and -5cm to 5cm in Y direction.
+
+    We select the detector type to be `Mesh` and set the center to (0,0,4) cm and dimensions to 0.1 x 10 x 10 cm.
+    This time the bins are defined in Y and Z directions, so we set 100 bins in Y and 120 bins in Z directions to get 1x1mm bins.
+
+    ![Setting up second detector](assets/scoring/detector_details_slabyz.png)
+
+=== "🚧 FLUKA"
+
+    Under development
+
+=== "Geant4"
 
-We select the detector type to be `Mesh` and set the center to (0,0,4) cm and dimensions to 0.1 x 10 x 12 cm.
-This time the bins are defined in Y and Z directions, so we set 100 bins in Y and 120 bins in Z directions to get 1x1mm bins.
+    Lets add a 1mm thick slab detector in YZ plane, spanning from -6cm to 6cm in Z direction and -5cm to 5cm in Y direction.
 
-![Setting up second detector](assets/scoring/detector_details_slabyz.png)
+    We select the detector type to be `Mesh` and set the dimensions to 0.1 x 10 x 10 cm.
+    This time the bins are defined in Y and Z directions, so we set 100 bins in Y and 120 bins in Z directions to get 1x1mm bins.
+
+    ![Setting up second detector](assets/scoring/geant4_detector_details_slabyz.png)
 
 ## Scoring output
 
@@ -77,9 +109,9 @@ Let's start by defining a scoring for depth dose profile in cylinder detector al
 This can be done by expanding the `AlongBeamAxis` item in the Outputs list by clicking on `+` icon.
 We can see that the output has already a first scoring quantity added, named `Quantity`.
 
-=== "SHIELD-HIT12A"
+![Default quantity](assets/scoring/default_quantity.png)
 
-    ![Default quantity](assets/scoring/default_quantity.png)
+=== "SHIELD-HIT12A"
 
     By default, scoring of dose was selected, so we stay with this, just adding a meaningful name: `Dose`.
 
@@ -90,9 +122,12 @@ We can see that the output has already a first scoring quantity added, named `Qu
 
     Under development
 
-=== "🚧 Geant4"
+=== "Geant4"
 
-    Under development
+    By default, scoring of dose (in Gy) was selected, so we stay with this, just adding a meaningful name: `Dose`.
+
+    We are planning to simulate the interaction of beam of protons with the phantom, and with such scoring we could see the
+    characteristic Bragg peak.
 
 ### Fluence profile in YZ plane
 
@@ -111,9 +146,12 @@ on the fluence of protons. Such thickness should be enough to stop most complete
 
     Under development
 
-=== "🚧 Geant4"
+=== "Geant4"
 
-    Under development
+    To score the fluence, we need to change the scoring quantity to `Fluence` and add a meaningful name.
+    We select default quantity in `YZSlab` item, define proper name and quantity type:
+
+    ![Defining Fluence quantity](assets/scoring/geant4_quantity_fluence.png)
 
 !!! note
     Quantity type supports typing letters to filter the list of available quantities.
@@ -149,6 +187,15 @@ In this case, to limit the scoring to protons only, we need to add a filter.
 
     Under development
 
-=== "🚧 Geant4"
+=== "Geant4"
 
-    Under development
+    We define a filter in the FILTERS section of the SCORING tab.
+    By pressing `+ FILTER`, new filter will be added to the list of filters.
+    We adjust the name of the filter to `Protons`, set the type to particle and select Proton.
+
+    ![Rule for protons](assets/scoring/geant4_filter_protons.png)
+
+    Finally, we apply the filter by selecting the Filter checkbox in the `Fluence` item in the list of `YZSlab` quantities.
+    Then we choose `Protons` from the drop-down list of filters.
+
+    ![Alt text](assets/scoring/geant4_apply_filter.png)
diff --git a/docs/settings.md b/docs/settings.md
@@ -21,9 +21,15 @@ Finally, particle type and number of primaries can be set.
 
     Under development
 
-=== "🚧 Geant4"
+=== "Geant4"
 
-    Under development
+    In our case we will move the beam to be located in front of the collimator by setting the beam position to (0,0,-6) cm.
+    The energy is adjusted to 70 MeV with 1% of energy spread, this way we can stop the beam using 1cm of lead.
+    Beam shape is set to a circular shape with 3cm radius (to be larger than the collimator hole).
+
+    ![Setting up beam](assets/settings/geant4_beam_adjustments.png)
+
+    Rest of parameters are left with default values.
 
 # Physics settings
 
@@ -36,6 +42,6 @@ Physics settings are defined in the `Physics` area just below the `Beam` definit
 
     ![Alt text](assets/settings/physics_settings.png)
 
-=== "🚧 Geant4"
+=== "Geant4"
 
-    Under development
+    Currently unsupported