From d44f8176ebce98e0e157da485d5f1088d112f9ec Mon Sep 17 00:00:00 2001 From: witNie Date: Fri, 10 Apr 2026 00:58:58 +0200 Subject: [PATCH 1/9] Add documentation for particle properties and usage examples --- docs/python/API/particles.md | 76 ++++++++++++++++++++++++++++++++++++ 1 file changed, 76 insertions(+) create mode 100644 docs/python/API/particles.md diff --git a/docs/python/API/particles.md b/docs/python/API/particles.md new file mode 100644 index 0000000..689b03c --- /dev/null +++ b/docs/python/API/particles.md @@ -0,0 +1,76 @@ +# Particles + +The library provides a comprehensive particle system for particle transport calculations, including predefined particles commonly used in particle therapy and radiation physics. + +## Overview + +Each particle is characterized by physical properties, including particle number, symbol, and charge state. + +## Particle Properties + +Each Particle object has the following properties: + +- **id** (`int`): Unique identifier for the particle +- **element_name** (`str`): Name of the particle element +- **A** (`int`): Mass number +- **Z** (`float`): Atomic number +- **I_eV_per_Z** (`float`): Ionization energy per proton +- **density_g_cm3** (`float`): Density \[g/cm3\] +- **element_acronym** (`str`): Acronym of the particle element +- **atomic_weight** (`float`): Atomic weight - average mass of element’s isotopes + +## Using Particles + +### Creating Particle Objects +There are a few ways a particle object can be created: +- Using predefined particle constants + + ```python + carbon = pyamtrack.particles.C + ``` + +- Using a particle code (A*1000 + Z) + ```python + carbon = pyamtrack.particles.Particle.from_number(6012) + ``` +- Using nuclide notation string (e.g., "12C") + ```python + carbon = pyamtrack.particles.Particle.from_string("12C") + ``` + +- Using atomic number (Z) directly + ```python + carbon = pyamtrack.particles.Particle(6) + ``` + Warning!!! Particle created this way will have A parameter set to None. It should represent only the atomic nucleus. + +### Passing particles as function arguments + +Aside from passing the particle object as an argument + +```python +import pyamtrack.stopping as stp +import pyamtrack.particles + +particle_carbon = particles.C +results_carbon = stp.stopping_power(energies, particle=particle_carbon, material=1) +``` + +There are other ways: +- Nuclide notation string (e.g., "12C") + ```python + import pyamtrack.stopping as stp + import pyamtrack.particles + + particle_carbon = "12C" + results_carbon = stp.stopping_power(energies, particle=particle_carbon, material=1) + ``` + +- Particle code (A*1000 + Z) + ```python + import pyamtrack.stopping as stp + import pyamtrack.particles + + particle_carbon = 6012 + results_carbon = stp.stopping_power(energies, particle=particle_carbon, material=1) + ``` \ No newline at end of file From 7305c56bde7ce35bea3890b9dea753af34cd716c Mon Sep 17 00:00:00 2001 From: witNie Date: Fri, 10 Apr 2026 01:02:18 +0200 Subject: [PATCH 2/9] fixed typo and changed porting status for particles module --- docs/python/function-status.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/python/function-status.md b/docs/python/function-status.md index 8408c29..403c2ac 100644 --- a/docs/python/function-status.md +++ b/docs/python/function-status.md @@ -24,7 +24,7 @@ Functions for accessing and manipulating particle data. | Python Module | Status | C/C++ Source | |-----------------|--------|--------------| -| `particle` | ❌ Not Ported | [AT_ParticleData.h](https://github.com/libamtrack/library/blob/master/include/AT_DataParticle.h#L82) | +| `particles` | ✅ Fully Ported | [AT_ParticleData.h](https://github.com/libamtrack/library/blob/master/include/AT_DataParticle.h#L82) | ## Material Data From 11f6a7e127c28e62603bb1fffbaf47b78e4c72cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Witold=20Nie=C4=87?= Date: Fri, 10 Apr 2026 22:09:04 +0200 Subject: [PATCH 3/9] Update docs/python/function-status.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Witold Nieć --- docs/python/function-status.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/python/function-status.md b/docs/python/function-status.md index 403c2ac..be4df0c 100644 --- a/docs/python/function-status.md +++ b/docs/python/function-status.md @@ -24,7 +24,7 @@ Functions for accessing and manipulating particle data. | Python Module | Status | C/C++ Source | |-----------------|--------|--------------| -| `particles` | ✅ Fully Ported | [AT_ParticleData.h](https://github.com/libamtrack/library/blob/master/include/AT_DataParticle.h#L82) | +| [`particles`](API/particles.md) | ✅ Fully Ported | [AT_ParticleData.h](https://github.com/libamtrack/library/blob/master/include/AT_DataParticle.h#L82) | ## Material Data From e582892051d404702447bbc73b2355dcc760c7f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Witold=20Nie=C4=87?= Date: Fri, 10 Apr 2026 22:11:39 +0200 Subject: [PATCH 4/9] Update docs/python/API/particles.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Witold Nieć --- docs/python/API/particles.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/python/API/particles.md b/docs/python/API/particles.md index 689b03c..1342942 100644 --- a/docs/python/API/particles.md +++ b/docs/python/API/particles.md @@ -26,6 +26,7 @@ There are a few ways a particle object can be created: - Using predefined particle constants ```python + import pyamtrack.particles carbon = pyamtrack.particles.C ``` From ac1ac971589f7e8058de654bfaeb7d18cbbc94a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Witold=20Nie=C4=87?= Date: Fri, 10 Apr 2026 22:14:02 +0200 Subject: [PATCH 5/9] Update docs/python/API/particles.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Witold Nieć --- docs/python/API/particles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/python/API/particles.md b/docs/python/API/particles.md index 1342942..070cbb8 100644 --- a/docs/python/API/particles.md +++ b/docs/python/API/particles.md @@ -4,7 +4,7 @@ The library provides a comprehensive particle system for particle transport calc ## Overview -Each particle is characterized by physical properties, including particle number, symbol, and charge state. +Each particle is characterized by physical properties, including its identifier, element name and acronym, mass number (`A`), and atomic number (`Z`). ## Particle Properties From 018bc1f13a4b9d2ac32a7163d0d80492be0dcf09 Mon Sep 17 00:00:00 2001 From: witNie Date: Fri, 10 Apr 2026 22:17:18 +0200 Subject: [PATCH 6/9] Fix particle code description in documentation --- docs/python/API/particles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/python/API/particles.md b/docs/python/API/particles.md index 070cbb8..3ce5015 100644 --- a/docs/python/API/particles.md +++ b/docs/python/API/particles.md @@ -30,7 +30,7 @@ There are a few ways a particle object can be created: carbon = pyamtrack.particles.C ``` -- Using a particle code (A*1000 + Z) +- Using a particle code (Z*1000 + A) ```python carbon = pyamtrack.particles.Particle.from_number(6012) ``` From bed88d5ef1aac87d7922e2a71bee79834b1b0c1d Mon Sep 17 00:00:00 2001 From: witNie Date: Fri, 10 Apr 2026 22:19:40 +0200 Subject: [PATCH 7/9] Improve clarity in particle function argument documentation --- docs/python/API/particles.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/python/API/particles.md b/docs/python/API/particles.md index 3ce5015..134762d 100644 --- a/docs/python/API/particles.md +++ b/docs/python/API/particles.md @@ -47,7 +47,7 @@ There are a few ways a particle object can be created: ### Passing particles as function arguments -Aside from passing the particle object as an argument +You can pass a `Particle` object directly as an argument: ```python import pyamtrack.stopping as stp @@ -57,7 +57,7 @@ particle_carbon = particles.C results_carbon = stp.stopping_power(energies, particle=particle_carbon, material=1) ``` -There are other ways: +But there are other ways: - Nuclide notation string (e.g., "12C") ```python import pyamtrack.stopping as stp From d16cca999d0bc961b57cbb548815834b32e48f27 Mon Sep 17 00:00:00 2001 From: witNie Date: Fri, 10 Apr 2026 22:22:21 +0200 Subject: [PATCH 8/9] Refactor import statement for particle module in documentation --- docs/python/API/particles.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/python/API/particles.md b/docs/python/API/particles.md index 134762d..ae5437d 100644 --- a/docs/python/API/particles.md +++ b/docs/python/API/particles.md @@ -51,8 +51,7 @@ You can pass a `Particle` object directly as an argument: ```python import pyamtrack.stopping as stp -import pyamtrack.particles - +from pyamtrack import particles particle_carbon = particles.C results_carbon = stp.stopping_power(energies, particle=particle_carbon, material=1) ``` From ec97b1991c677e788af116fa075b4ee645e1b0d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Witold=20Nie=C4=87?= Date: Fri, 10 Apr 2026 22:24:32 +0200 Subject: [PATCH 9/9] Update docs/python/API/particles.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Signed-off-by: Witold Nieć --- docs/python/API/particles.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/python/API/particles.md b/docs/python/API/particles.md index ae5437d..e216492 100644 --- a/docs/python/API/particles.md +++ b/docs/python/API/particles.md @@ -43,7 +43,7 @@ There are a few ways a particle object can be created: ```python carbon = pyamtrack.particles.Particle(6) ``` - Warning!!! Particle created this way will have A parameter set to None. It should represent only the atomic nucleus. + Warning: A particle created this way has `A=None`, so no specific isotope is selected. It represents the element or atomic nucleus identified only by `Z`, unlike isotope-specific inputs such as `"12C"` or `6012`. ### Passing particles as function arguments