Skip to content

Prepare for separate steps for each simulator #116

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
grzanka merged 2 commits into from
Nov 16, 2025
Merged

Prepare for separate steps for each simulator #116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aa01852
Mention Geant4 in docs, add tabs for each simulator
kmichalikk Nov 14, 2025
8f68b09
Fix copilot issues
kmichalikk Nov 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
169 changes: 86 additions & 83 deletions docs/geometry.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,14 +30,14 @@ For blank project, you can select which simulator you want to use by clicking th

![Simulator Dropdown](assets/geometry/select_simulator.gif)

> [!NOTE]
> The COMMON option represents the set of features supported by both FLUKA and SHIELDHIT-12A. You can switch from COMMON
> to either of these simulators.
!!! note
The COMMON option represents the set of features supported by both FLUKA and SHIELDHIT-12A. You can switch from COMMON
to either of these simulators.

> [!NOTE]
> You can modify the title and description by clicking the title in the header bar.
>
> ![Edit project info](assets/geometry/edit_project_info.gif)
!!! note
You can modify the title and description by clicking the title in the header bar.
![Edit project info](assets/geometry/edit_project_info.gif)

### Example project

Expand All @@ -60,121 +60,124 @@ In the following sections we will go through generation of simple geometry. It w
- lead collimator with 2cm radius hole and 1cm thickness
- world filled with air

### World filled with air
=== "SHIELD-HIT12A / FLUKA"

Lets 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 FIGURES section in GEOMETRY tab.
### World filled with air

![Add Figure from Object Menu](assets/geometry/menu_object_add.png)
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 FIGURES section in GEOMETRY tab.

![Add Figure from FIGURES section](assets/geometry/figures_add.png)
![Add Figure from Object Menu](assets/geometry/menu_object_add.png)

Lets create a box spanning from -2 to 10 in z direction and from -5 to 5 in x and y direction.
We do this by providing box center (named "Position") and its dimensions (named "X/Y/Z side").
In our case the position will be (4,0,0) and dimensions 12cm x 10cm x 10cm.
Note that basic dimensions units in YAPTIDE are centimeters.
Let's also assign a meaningful name to the created figure.
![Add Figure from FIGURES section](assets/geometry/figures_add.png)

![Object details](assets/geometry/object_details.png)
Let's create a box spanning from -2 to 10 in z direction and from -5 to 5 in x and y direction.
We do this by providing box center (named "Position") and its dimensions (named "X/Y/Z side").
In our case the position will be (4,0,0) and dimensions 12cm x 10cm x 10cm.
Note that basic dimensions units in YAPTIDE are centimeters.
Let's also assign a meaningful name to the created figure.

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.
![Object details](assets/geometry/object_details.png)

### Large phantom
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.

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.
The dimensions are given in such way that the water phantom is fully contained in the world box.
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.
The dimensions are given in such way that the water phantom is fully contained in the world box.

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.
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/duplicate.png)
![Duplicate WorldBox](assets/geometry/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 and dimensions) will be copied as well.
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 and dimensions) will be copied as well.

![Duplicated WorldBox](assets/geometry/duplicated.png)
![Duplicated WorldBox](assets/geometry/duplicated.png)

Now lets adjust the dimensions of the newly created figure to 8cm x 8cm x 8cm, as the position can stay the same.
Also the name needs an update to `PhantomBox`.
Note that the two figures are visible in the 3-D projection window, while only current one is visible in the cross-sections.
Now let's adjust the dimensions of the newly created figure to 8cm x 8cm x 8cm, as the position can stay the same.
Also the name needs an update to `PhantomBox`.
Note that the two figures are visible in the 3-D projection window, while only current one is visible in the cross-sections.

![PhantomBox](assets/geometry/phantom_box.png)
![PhantomBox](assets/geometry/phantom_box.png)

### Collimator
### Collimator

Finally lets add two cylinders representing outer envelope and inner hole inside the collimator.
The cylinders have thickness of 1cm and are radius of 4 and 2 cm respectively.
Both are centered around (0,0,0) point.
You can use drag operation by clicking and dragging on the 3-D projection view. This would help to adjust the view, so the collimator is visible.
Finally, let's add two cylinders representing the outer envelope and inner hole inside the collimator.
The cylinders have thickness of 1cm and are radius of 4 and 2 cm respectively.
Both are centered around (0,0,0) point.
You can use drag operation by clicking and dragging on the 3-D projection view. This would help to adjust the view, so the collimator is visible.

![Cylinders](assets/geometry/cylinders.png)
![Cylinders](assets/geometry/cylinders.png)

## Adding new zone
## Adding new zone

With the figures defined above, we can construct the zones which will be used in the simulation.
Here we follow the naming of SHIELD-HIT12A, as Fluka calls the zones "regions".
With the figures defined above, we can construct the zones which will be used in the simulation.
Here we follow the naming of SHIELD-HIT12A, as Fluka calls the zones "regions".

Lets start with adding a zone which will represent the large box filled with air.
This can be done in a similar way as adding the figures, either from upper left menu in the Editor tab
or by going to Geometry tab in right menu and expanding ZONES section in GEOMETRY tab.
Let's start with adding a zone which will represent the large box filled with air.
This can be done in a similar way as adding the figures, either from upper left menu in the Editor tab
or by going to Geometry tab in right menu and expanding ZONES section in GEOMETRY tab.

![Add Boolean Zone from Object Menu](assets/geometry/menu_boolean_zone_add.png)
![Add Boolean Zone from ZONES section](assets/geometry/boolean_zone_add.png)

![Add Boolean Zone from Object Menu](assets/geometry/menu_boolean_zone_add.png)
![Add Boolean Zone from ZONES section](assets/geometry/boolean_zone_add.png)
!!! note
A special "World Zone" which represents the whole simulation environment is defined by default, and can't be removed.

> [!NOTE]
> A special "World Zone" which represents the whole simulation environment is defined by default, and can't be removed.
### Air zones

### Air zones
Zones describe a volume of space by combining multiple figures using boolean operations to define shape,
and define physical material that the volume is made of.

Zones describe a volume of space by combining multiple figures using boolean operations to define shape,
and define physical material that the volume is made of.
!!! warning
Defining zone operations requires special considerations. Each point in space should belong to exactly
one Zone so that it is clear for the simulator which material the particle is going through.
This means that the volume enclosing another volume with different material needs to have a cutout that will fit the inner volume.

> [!IMPORTANT]
> Defining zone operations requires special considerations. Each point in space should belong to exactly
> one Zone so that it is clear for the simulator which material the particle is going through.
> This means that the volume enclosing another volume with different material needs to have a cutout that will fit the inner volume.
Let's expand ZONE OPERATIONS and define the MainAirZone and CollimatorAirZone.
Together they represent the air that fills the empty space around the phantom and the collimator.
To get precisely the air volume, we need to subtract both the phantom and the collimator.
- For the phantom, it only requires subtracting the phantom figure.
- For the collimator, we need to subtract the whole outer cylinder, and add back the inner cylinder. The "adding back"
is performed with second zone.

Let's expand ZONE OPERATIONS and define the MainAirZone and CollimatorAirZone.
Together they represent the air that fills the empty space around the phantom and the collimator.
To get precisely the air volume, we need to subtract both the phantom and the collimator.
- For the phantom, it only requires subtracting the phantom figure.
- For the collimator, we need to subtract the whole outer cylinder, and add back the inner cylinder. The "adding back"
is performed with second zone.
Defining the MainAirZone is shown below:

Defining the MainAirZone is shown below:
![Defining zone operations for MainZone](assets/geometry/zone_operations.gif)

![Defining zone operations for MainZone](assets/geometry/zone_operations.gif)
CollimatorAirZone is then simply:

CollimatorAirZone is then simply:
![Collimator air zone](assets/geometry/collimator_air_zone.png)

![Collimator air zone](assets/geometry/collimator_air_zone.png)
Zones are visualized in the 3D view by solid colors. We can see the cutouts for the phantom and the collimator.

Zones are visualized in the 3D view by solid colors. We can see the cutouts for the phantom and the collimator.
![Zone in 3D view](assets/geometry/zone_vis.png)

![Zone in 3D view](assets/geometry/zone_vis.png)
!!! note
To better see what's inside the zone, you can set the Opacity under MATERIAL section.
![Custom opacity](assets/geometry/custom_opacity.png)

> [!NOTE]
> To better see what's inside the zone, you can set the Opacity under MATERIAL section.
> ![Custom opacity](assets/geometry/custom_opacity.png)
### Water phantom zone

### Water phantom zone
We repeat the same thing for water phantom zone. Let's add new zone and assign the "PhantomBox" as the figure.
There is no need to assign the material as we stay with default "Liquid Water" material.

We repeat the same thing for water phantom zone. Let's add new zone and assign the "PhantomBox" as the figure.
There is no need to assign the material as we stay with default "Liquid Water" material.
Under the MATERIAL section, instead of Opacity, we change the color and inspect the zone in the 3D view.

Under the MATERIAL section, instead of Opacity, we change the color and inspect the zone in the 3D view.
![Phantom Zone](assets/geometry/phantom_zone.png)

![Phantom Zone](assets/geometry/phantom_zone.png)
### Collimator zone

### Collimator zone
The collimator is a lead ring that is created by subtracting inner cylinder from outer cylinder.
We name the zone appropriately and set the material.

The collimator is a lead ring that is created by subtracting inner cylinder from outer cylinder.
We name the zone appropriately and set the material.
![Collimator Zone](assets/geometry/collimator_zone.png)

![Collimator Zone](assets/geometry/collimator_zone.png)
These are the basic steps for defining geometry for CSG-based simulators.

These are the basic steps for defining geometry for CSG-based simulators.
=== "🚧 Geant4"

Under development
20 changes: 11 additions & 9 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,10 +5,11 @@

The YAPTIDE platform provides an easy way to work with particle transport simulations.
Most popular particle transport codes, like Geant4, TOPAS, MCNP require preparation of the input text files and running the simulation in a terminal.
The FLUKA code has an graphical user interface, called Flair, but it requires Linux (or Windows with WSL) to run.
The FLUKA code has a graphical user interface, called Flair, but it requires Linux (or Windows with WSL) to run.

The YAPTIDE platform provides a way to define a simulation in a web browser without the need to install any software. This is possible without any login or registration.
Having access to the computing resources (i.e. by registering in the [PlGrid](https://portal.plgrid.pl/) platform or deploying the project locally) allows to run the simulation in a parallel way using our web platform. The results of simulation can be visualized in the web browser or downloaded to the local computer.
The YAPTIDE platform provides a consistent graphical user interface for three simulation toolkits: SHIELD-HIT12A, FLUKA, and Geant4.
Without any login or registration, it allows to define simulations, browse the results of already finished simulations, and export ready-to-run input files that can be passed directly to the simulator.
For users with access to the computing resources (i.e. registered in the [PlGrid](https://portal.plgrid.pl/) platform or having deployed the project locally) it allows to submit jobs to the simulators.

## How to use the platform

Expand All @@ -17,15 +18,16 @@ Having access to the computing resources (i.e. by registering in the [PlGrid](ht
![Demo landing page](assets/demo.png)

Demo version of the platform is hosted on the GitHub pages as [yaptide.github.io](https://yaptide.github.io/web_dev).
This version is free for use and doesn't require to register or login.
In demo version the platform works as an online editor for simulation input and results browser. The following functionalities are available:
This version is free for use and doesn't require registration or login.
The following functionalities are available:

- defining and visualizing simulation geometry and materials
- defining scoring geometry, scored quantities and advanced scoring options (like filtering)
- defining particle source
- specifying simulation settings (like physics parameters)
- generating files with simulation input (to be executed on user resources)
- browsing results of simulation (previously calculated using YAPTIDE platform or other software)
- running the simulation with Geant4 directly on users' machines


### Full version
Expand All @@ -34,8 +36,8 @@ In demo version the platform works as an online editor for simulation input and

Full version is hosted in the PlGrid infrastructure and requires registration and login. To access the platform visit [yaptide.c3.plgrid.pl](https://yaptide.c3.plgrid.pl).

You'll be able to execute your simulations in the cloud (few machines in C3 PlGrid Cloud) or HPC resources (Ares supercomputer in ACK Cyfronet).
You'll be able to execute your SHIELD-HIT12A and FLUKA simulations in the cloud (few machines in C3 PlGrid Cloud) or HPC resources (Ares supercomputer in ACK Cyfronet).

> [!NOTE]
> The platform requires registration and allows the access for selected group of users
> with account in the PLGrid infrastructure. To register in the platform, please contact the administrator.
!!! note
The platform requires registration and allows the access for selected group of users
with account in the PLGrid infrastructure. To register in the platform, please contact the administrator.
Loading
Loading