Getting Started

Installation

Clone the repository and install in a virtual environment:

git clone <repo-url> tracketch
cd tracketch
python -m venv .venv
source .venv/bin/activate
pip install -e ".[numba]"

This installs tracketch with the Numba-accelerated Dijkstra backend, which works on any Linux machine.

Note

tracketch depends on libamtrack and is currently Linux only.

Note

This release currently supports only 2D axisymmetric simulations (straight tracks).

Optional: C++ Dijkstra backend

For ~100x faster arrival-time computation:

pip install -e ".[numba,cpp]"
cd tracketch/wavefront/dijkstra/cpp
python setup_dijkstra.py build_ext --inplace

Quick example

import matplotlib.pyplot as plt
from tracketch import TrackSimulator

# 270 MeV/u carbon-12 hitting CR-39
sim = TrackSimulator(
    particle_name="12C",
    start_energy_MeV_u=270.0,
)

# Plot track shape after 1 and 3 hours of etching
fig, ax = plt.subplots()
for t in [1.0, 3.0]:
    r, z = sim.get_iso_time_contour(etching_time_h=t)
    ax.plot(r, z, label=f"{t} h")
    ax.plot(-r, z, color=ax.lines[-1].get_color())

ax.set_xlabel("r / um")
ax.set_ylabel("z / um")
ax.invert_yaxis()
ax.legend(title="Etch time")
ax.set_aspect("equal")
plt.tight_layout()
plt.show()

The TrackSimulator automatically computes the dose map, etch-rate map, and arrival-time map on construction. See Examples for more detailed scripts.

Etch-rate model selection

tracketch uses one shared default etch-rate calibration model, "Doerschel_etching", for all particle species.

• The etch-rate model is not selected from particle_name.

• particle_name only controls stopping power / dose-map physics.

• You can provide a custom etch model explicitly when needed.

from tracketch import TrackSimulator, load_etchrate_model

etch_model = load_etchrate_model("my_custom_model")

sim = TrackSimulator(
   particle_name="12C",
   start_energy_MeV_u=270.0,
   etch_model=etch_model,
)

Particles and stopping-power sources

Particle names follow the "<A><symbol>" convention, where A is the mass number and symbol is the element symbol – for example "12C", "1H", "56Fe".

The stopping-power source is chosen with the stopping_power_source parameter:

"SRIM" (default)

Uses tabulated SRIM data. Only the following ten particles are supported:

import tracketch
print(tracketch.SRIM_PARTICLES)
# ('1H', '2H', '3H', '4He', '7Li', '9Be', '11B', '12C', '14N', '16O')

Requesting any other particle raises a ValueError with a hint to switch to "libamtrack".

Note

All three hydrogen isotopes are supported: "1H" (proton), "2H" (deuteron), "3H" (triton). The CSDA range scales linearly with mass number A; LET at the same MeV/u is identical across isotopes.

"libamtrack"

Uses the PSTAR/ASTAR parametrisation via libamtrack. Accepts any nuclide recognised by libamtrack, including heavy ions such as "56Fe" or "238U".

from tracketch import TrackSimulator

# Heavy ion -- switch to libamtrack for stopping power
sim = TrackSimulator(
    particle_name="56Fe",
    start_energy_MeV_u=1000.0,
    stopping_power_source="libamtrack",
)

Target material

Two materials are supported:

import tracketch
print(tracketch.MATERIALS)   # ('CR39', 'water')

Pass the name as material_name="CR39" (default, density 1.31 g/cm^3) or material_name="water" (density 1.00 g/cm^3). An unknown name raises a ValueError.

Simulation grid

The simulation uses a 2-D cylindrical grid in (r, z). The radial axis is log-spaced (to resolve the narrow dose core near r = 0); the depth axis is uniform. Default values:

Parameter	Default	Description
r_min_um	1e-4 um	Inner radial boundary (start of log-spaced axis)
r_max_um	20 um	Outer radial boundary
z_max_um	40 um	Maximum depth along the ion path
n_points_r	400	Number of radial grid points
n_points_z	100	Number of depth grid points

All five parameters can be passed directly to TrackSimulator:

from tracketch import TrackSimulator

sim = TrackSimulator(
    particle_name="12C",
    start_energy_MeV_u=270.0,
    r_max_um=40,     # wider radial window
    z_max_um=80,     # deeper track
    n_points_r=600,  # finer radial resolution
    n_points_z=200,  # finer depth resolution
)

Increasing resolution improves accuracy at the cost of compute time. For publication-quality results consider doubling both n_points_r and n_points_z. For quick exploration the defaults are a good starting point.

Note

Enabling parallel dose-map computation with n_jobs=-1 reduces wall time for large grids (>=50 000 total cells) or when using stopping_power_source="libamtrack". For the default 400 x 100 grid the inter-process overhead outweighs the gain; leave n_jobs=1 (the default) in that case.

Building the documentation

cd docs
make html

Then open _build/html/index.html in a browser.