Contents Menu Expand Light mode Dark mode Auto light/dark, in light mode Auto light/dark, in dark mode Skip to content
pysrim2 0.12.1 documentation
pysrim2 0.12.1 documentation

Get started

  • First simulation
  • Installation
  • Agent guide
  • Container

Gallery

  • Gallery
  • Examples

Guides

  • Desktop app
  • DataFrames
  • run.yaml
  • Export
  • Scans
  • Beam distributions
  • Concurrent runs

Reference

  • Command line
  • API reference
    • srim
    • srim.output
    • srim.spec
    • srim.scan
    • srim.notebook
    • srim.beam
    • srim.analysis
    • core
    • srim.export
    • srim.plot
  • Citing pysrim2
  • Changes from pysrim
  • Changelog
Back to top
View this page

Gallery¶

Each picture on this page is made by the script shown under it. The scripts are in docs/gallery/, and one command rebuilds all the pictures from them. The pictures of SRIM runs use real SRIM output with fixed seeds. The live-view screenshots use illustrative values from a scripted event stream, not from a SRIM run.

Collision cascades of 4.5 MeV carbon ions in SiC (COLLISON.txt)¶

Map of the collisions of carbon ions and their recoils in SiC

Every collision of 1000 carbon ions and of the target atoms they set moving, counted by depth and lateral position. The ion tracks run along the middle; the lines that branch off are recoils. The data is the full-cascade output committed in test_files/SiC-C, so no SRIM run is needed.

"""Where the collisions of 1000 carbon ions in SiC happen: a map of the full cascades.

``COLLISON.txt`` of a full-cascade run lists every collision of the ions and their recoils.
``Collision.iter_events()`` streams it, so even a file of many gigabytes needs little memory.
The data is the SRIM output committed in ``test_files/SiC-C`` (4.5 MeV C into 1 µm of SiC,
1000 ions), so no SRIM run is needed.
"""

from pathlib import Path

import matplotlib.pyplot as plt
import numpy as np
from matplotlib.colors import LogNorm

from srim.output import Collision

TITLE = "Collision cascades of 4.5 MeV carbon ions in SiC (COLLISON.txt)"
NEEDS_SRIM = False
OUTPUT = "tracks.png"

FIXTURE = Path(__file__).resolve().parents[2] / "test_files" / "SiC-C"


def make(outdir):
    events = Collision(str(FIXTURE)).iter_events()
    depth, lateral = np.array([(e["depth_A"], e["y_A"]) for e in events]).T

    fig, ax = plt.subplots(figsize=(8, 3.5), dpi=100)
    _, _, _, image = ax.hist2d(
        depth / 10, lateral / 10, bins=(250, 100), range=((0, 1000), (-100, 100)), norm=LogNorm()
    )
    fig.colorbar(image, ax=ax, label="collisions per bin")
    ax.set_xlabel("depth (nm)")
    ax.set_ylabel("lateral position y (nm)")
    ax.set_title("4.5 MeV C into SiC, 1000 ions, full cascades")

    path = Path(outdir) / OUTPUT
    fig.savefig(path, bbox_inches="tight")
    plt.close(fig)
    return path

Where 10,000 nickel ions at 5 MeV stop in nickel (RANGE_3D.txt)¶

Heatmap of where 5 MeV nickel ions stop in nickel

The final positions of 10,000 ions of a 3D range run, counted by depth along the beam and by lateral distance from it. A quick Kinchin-Pease run. Needs SRIM.

"""Where the ions of a 3D range run stop in the target: 10,000 ions, a quick Kinchin-Pease run.

``ranges=1`` makes TRIM write ``RANGE_3D.txt``, the final position of every ion. Needs SRIM.
"""

from pathlib import Path

import matplotlib.pyplot as plt
import numpy as np
from matplotlib.colors import LogNorm

from srim import TRIM, Ion, Layer, Target

TITLE = "Where 10,000 nickel ions at 5 MeV stop in nickel (RANGE_3D.txt)"
NEEDS_SRIM = True
OUTPUT = "heatmap.png"

IONS = 10_000


def make(outdir):
    target = Target([Layer.from_formula("Ni", density=8.9, width=40000.0)])  # 4 um
    trim = TRIM(target, Ion("Ni", energy=5e6), number_ions=IONS, ranges=1, random_seed=12345)
    df = trim.run().range3d.df
    depth_um = df["depth_A"] / 1e4
    lateral_um = np.hypot(df["y_A"], df["z_A"]) / 1e4

    fig, ax = plt.subplots(figsize=(6, 4), dpi=100)
    _, _, _, image = ax.hist2d(depth_um, lateral_um, bins=60, norm=LogNorm())
    fig.colorbar(image, ax=ax, label="ions per bin")
    ax.set_xlabel("depth along the beam (µm)")
    ax.set_ylabel("lateral distance √(y² + z²) (µm)")
    ax.set_title(f"5 MeV Ni into Ni, {IONS:,} ions")

    path = Path(outdir) / OUTPUT
    fig.savefig(path, bbox_inches="tight")
    plt.close(fig)
    return path

Ionization and vacancies against depth¶

Ionization and vacancy profiles against depth

Ionization from ions and from recoils, and the vacancies, against depth for 3 MeV gold into SiC. The data is the full-cascade output committed in test_files/2.

"""Depth profiles of ionization and vacancies from a full cascade run (test_files/2)."""

from pathlib import Path

import matplotlib.pyplot as plt

from srim.output import Results

TITLE = "Ionization and vacancies against depth"
NEEDS_SRIM = False
OUTPUT = "depth_profiles.png"

FIXTURE = Path(__file__).resolve().parents[2] / "test_files" / "2"


def make(outdir):
    results = Results(str(FIXTURE))
    ioniz = results.ioniz.df
    vacancy = results.vacancy.df
    vacancy_columns = [c for c in vacancy.columns if c.startswith("vacancies_")]

    fig, (left, right) = plt.subplots(1, 2, figsize=(6, 4), dpi=100)
    left.plot(ioniz["depth_A"] / 10, ioniz["ions_eV_per_A_per_ion"], label="from ions")
    left.plot(ioniz["depth_A"] / 10, ioniz["recoils_eV_per_A_per_ion"], label="from recoils")
    left.set_xlabel("depth (nm)")
    left.set_ylabel("ionization (eV/Å/ion)")
    left.set_title("Ionization")
    left.legend(loc="upper right")

    right.plot(vacancy["depth_A"] / 10, vacancy[vacancy_columns].sum(axis=1))
    right.set_xlabel("depth (nm)")
    right.set_title("Vacancies, summed over elements")
    right.set_ylabel("vacancies (1/Å/ion)")

    fig.suptitle("3 MeV Au into SiC")
    fig.tight_layout()

    path = Path(outdir) / OUTPUT
    fig.savefig(path, bbox_inches="tight")
    plt.close(fig)
    return path

A parameter scan: mean depth against energy, one line per angle¶

Mean depth of boron ions in silicon against energy, one line per angle

The mean depth of boron ions in silicon from 10 to 50 keV, at 0 and 45 degrees. Each point is a quick SRIM run of 2000 ions, and the points run on two worker processes. Needs SRIM.

"""Mean depth of B ions in Si against the energy, one line per angle: a parameter scan.

The base run and the seed are those of ``examples/scripts/angle_energy_scan.py``; this entry
scans more energies (10 to 50 keV) at two angles (0 and 45 degrees), ten points of 2000 ions on
two worker processes, a quick Kinchin-Pease run each. Needs SRIM.
"""

import importlib.util
import tempfile
from pathlib import Path

import matplotlib.pyplot as plt

from srim.scan import Scan, run_scan

TITLE = "A parameter scan: mean depth against energy, one line per angle"
NEEDS_SRIM = True
OUTPUT = "scan_plot.png"

ROOT = Path(__file__).resolve().parents[2]

# 2000 ions per point (the example uses 50), so that the lines are smooth.
IONS = 2000


def _example(name):
    path = ROOT / "examples" / "scripts" / f"{name}.py"
    spec = importlib.util.spec_from_file_location(f"gallery_example_{name}", path)
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


def make(outdir):
    example = _example("angle_energy_scan")
    scan = Scan(
        example.base_spec(),
        grid={"ion.energy_keV": [10.0, 20.0, 30.0, 40.0, 50.0], "ion.angle_deg": [0.0, 45.0]},
        extract=["implant_summary"],
        ions=IONS,
        seed=example.SEED,
    )
    fig, ax = plt.subplots(figsize=(6, 4), dpi=100)
    with tempfile.TemporaryDirectory() as tmp:
        result = run_scan(scan, workers=2, scan_dir=Path(tmp) / "scan")
        result.plot(x="ion.energy_keV", y="mean_depth_A", ax=ax)
    handles, labels = ax.get_legend_handles_labels()
    angles = [f"{float(label.split('=')[1]):g}°" for label in labels]
    ax.legend(handles, angles, title="angle")
    ax.set_xlabel("ion energy (keV)")
    ax.set_ylabel("mean depth (Å)")
    ax.set_title("B into 1000 nm of Si")

    path = Path(outdir) / OUTPUT
    fig.savefig(path, bbox_inches="tight")
    plt.close(fig)
    return path

The live plot of a running scan (pysrim2 scan run –ui plot)¶

Terminal live plot of a running scan

The plot view of a scan while it runs: the finished points and the values so far. The values are illustrative, from a scripted event stream.

"""The live plot view of a running scan, drawn from a scripted event stream."""

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent))
from _live import screenshot  # noqa: E402  (the values are illustrative)

TITLE = "The live plot of a running scan (pysrim2 scan run --ui plot)"
NEEDS_SRIM = False
OUTPUT = "tui_plot.svg"


def make(outdir):
    return screenshot("plot", Path(outdir), OUTPUT)

The scan dashboard (–ui dashboard)¶

Terminal dashboard of a running scan

The dashboard view of the same kind of scan: the state of each point and of the workers. The values are illustrative, as in the picture above.

"""The dashboard view of a running scan, drawn from a scripted event stream."""

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent))
from _live import screenshot  # noqa: E402  (the values are illustrative)

TITLE = "The scan dashboard (--ui dashboard)"
NEEDS_SRIM = False
OUTPUT = "tui_dashboard.svg"


def make(outdir):
    return screenshot("dashboard", Path(outdir), OUTPUT)

A beam with a 1 keV Gaussian energy spread (exact mode)¶

Energy distribution of 2000 boron ions with a 1 keV Gaussian spread

The energies of 2000 boron ions that SRIM ran in exact mode, drawn over the Gaussian density the beam was defined with. Needs SRIM.

"""A beam with a Gaussian energy spread: the ions SRIM ran (exact mode), drawn over the density.

The beam is the one of ``examples/scripts/beam_energy_spread.py``: 2000 B ions at 20 keV with
a 1 keV Gaussian spread. Needs SRIM.
"""

import importlib.util
import tempfile
from pathlib import Path

import matplotlib.pyplot as plt

from srim.beam import plot_beam, run_beam

TITLE = "A beam with a 1 keV Gaussian energy spread (exact mode)"
NEEDS_SRIM = True
OUTPUT = "beam.png"

ROOT = Path(__file__).resolve().parents[2]

IONS = 2000


def _example(name):
    path = ROOT / "examples" / "scripts" / f"{name}.py"
    spec = importlib.util.spec_from_file_location(f"gallery_example_{name}", path)
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


def make(outdir):
    spec = _example("beam_energy_spread").beam_spec("exact", IONS)
    fig, ax = plt.subplots(figsize=(6, 4), dpi=100)
    with tempfile.TemporaryDirectory() as tmp:
        with run_beam(spec, output_dir=Path(tmp) / "exact") as results:
            plot_beam(results, "energy_keV", ax=ax, bins=40)
    ax.set_xlabel("ion energy (keV)")
    ax.set_ylabel("probability density (1/keV)")
    ax.set_title("B at 20 keV into 1000 nm of Si")

    path = Path(outdir) / OUTPUT
    fig.savefig(path, bbox_inches="tight")
    plt.close(fig)
    return path

The desktop app: the boron reference setup on the Geometry tab¶

The desktop app with the boron reference setup: the layers and the target to scale

The window of pysrim2 app with the boron reference case of First simulation (100 nm of gold on silicon). The target is drawn to scale beside the layer table, and the status bar says the setup is complete. The script builds the setup in code and needs the app extra; it makes no SRIM run.

"""The desktop app on the boron reference setup: the Geometry tab, with the target to scale.

The setup is the boron reference case of docs/first-simulation.md, built here in code: 200 B
ions at 20 keV and 7 degrees into 100 nm of Au on Si, seed 12345. It needs the app extra
(PySide6); the window runs offscreen, with no install or check.
"""

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent))
from _app_shots import grab_setup  # noqa: E402

TITLE = "The desktop app: the boron reference setup on the Geometry tab"
NEEDS_SRIM = False
OUTPUT = "app_setup.png"

SETUP = {
    "version": 1,
    "ion": {"symbol": "B", "energy_keV": 20.0, "angle_deg": 7.0},
    "number_ions": 200,
    "calculation": 1,
    "seed": 12345,
    "settings": {},
    "target": [
        {
            "name": "gold",
            "thickness_nm": 100.0,
            "density_g_cm3": 19.3,
            "phase": 0,
            "elements": [
                {
                    "symbol": "Au",
                    "stoich": 1.0,
                    "displacement_eV": 25.0,
                    "lattice_eV": 3.0,
                    "surface_eV": 3.0,
                }
            ],
        },
        {
            "name": "silicon",
            "thickness_nm": 1000.0,
            "density_g_cm3": 2.33,
            "phase": 0,
            "elements": [
                {
                    "symbol": "Si",
                    "stoich": 1.0,
                    "displacement_eV": 15.0,
                    "lattice_eV": 2.0,
                    "surface_eV": 4.7,
                }
            ],
        },
    ],
}


def make(outdir):
    return grab_setup(SETUP, Path(outdir) / OUTPUT)

The desktop app: the results of a finished run¶

The desktop app's Results tab with the ionization profile of 3 MeV gold in SiC

The Results tab of a finished run, with the ionization profile of 3 MeV gold in SiC. The run folder is built from the outputs of test_files/2 as a run leaves it, so no SRIM run is needed. See Desktop app for the tabs.

"""The desktop app's Results tab: the ionization profile of a finished run.

The run is 3 MeV Au into SiC, the SRIM outputs of test_files/2 (a full cascade), opened as a
run folder would be. No SRIM run is made. It needs the app extra (PySide6); the window runs
offscreen.
"""

import sys
from pathlib import Path

sys.path.insert(0, str(Path(__file__).parent))
from _app_shots import grab_results  # noqa: E402

TITLE = "The desktop app's Results tab: ionization against depth of a finished run"
NEEDS_SRIM = False
OUTPUT = "app_results.png"


def make(outdir):
    return grab_results(Path(outdir) / OUTPUT)

The agent example: 200 boron ions into gold on silicon¶

Depth of 200 boron ions in 100 nm of gold on silicon, with the mean depth marked

The depth of the ions in the reference case, with the Au/Si interface and the mean depth marked. An AI agent with the pysrim2 skill was given this prompt:

Simulate a 100 nm gold layer on a silicon wafer, implant 200 boron ions at 7 degrees and 20 keV, and give me a pandas DataFrame of implantation depth and xy straggle.

The picture is made by the same boron script that the skill ships, run with seed 12345. The gallery script calls that script’s run() function. Needs SRIM. See Agent guide for the whole agent route.

"""The agent reference case: where 200 boron ions stop in 100 nm of gold on silicon.

The run is the one of ``examples/scripts/boron_in_gold_on_silicon.py`` (20 keV, 7 degrees,
seed 12345). The histogram is drawn from ``RANGE_3D.txt``. Needs SRIM.
"""

import importlib.util
import tempfile
from pathlib import Path

import matplotlib.pyplot as plt

from srim.output import Range3D

TITLE = "The agent example: 200 boron ions into gold on silicon"
NEEDS_SRIM = True
OUTPUT = "agent_boron.png"

ROOT = Path(__file__).resolve().parents[2]
INTERFACE_A = 1000.0  # the Au layer is 100 nm = 1000 angstrom


def _example(name):
    path = ROOT / "examples" / "scripts" / f"{name}.py"
    spec = importlib.util.spec_from_file_location(f"gallery_example_{name}", path)
    module = importlib.util.module_from_spec(spec)
    spec.loader.exec_module(module)
    return module


def make(outdir):
    boron = _example("boron_in_gold_on_silicon")
    with tempfile.TemporaryDirectory() as tmp:
        summary = boron.run(200, Path(tmp) / "out")
        depth = Range3D(str(Path(tmp) / "out")).df["depth_A"]
    mean = summary["mean_depth_A"]
    fig, ax = plt.subplots(figsize=(6, 4), dpi=100)
    ax.hist(depth, bins=50, color="0.6")
    ax.axvline(INTERFACE_A, color="C1", label="Au / Si interface (100 nm)")
    ax.axvline(mean, color="C0", label=f"mean depth {mean:.0f} Å")
    ax.legend()
    ax.set_xlabel("depth below the surface (Å)")
    ax.set_ylabel("ions per bin")
    ax.set_title("20 keV B, 7°, seed 12345")

    path = Path(outdir) / OUTPUT
    fig.savefig(path, bbox_inches="tight")
    plt.close(fig)
    return path

Rebuild the pictures¶

Run from the repository root. The pictures are rebuilt on a machine with SRIM (pysrim2 install); entries that need SRIM are skipped with a message without it.

uv run --extra plot --extra tui --extra app python docs/gallery/make.py          # all entries
uv run --extra plot --extra tui --extra app python docs/gallery/make.py --list   # list the entries
uv run --extra plot --extra tui --extra app python docs/gallery/make.py heatmap  # one or more names

The app extra (PySide6) is needed for the two pictures of the desktop app; the window runs offscreen, so no display is needed.

Each committed image must stay under 300 KB.

Next
Examples
Previous
Container
Copyright © 2018, Chris Ostrouchov; 2026, pysrim2 contributors
Made with Sphinx and @pradyunsg's Furo
On this page
  • Gallery
    • Collision cascades of 4.5 MeV carbon ions in SiC (COLLISON.txt)
    • Where 10,000 nickel ions at 5 MeV stop in nickel (RANGE_3D.txt)
    • Ionization and vacancies against depth
    • A parameter scan: mean depth against energy, one line per angle
    • The live plot of a running scan (pysrim2 scan run –ui plot)
    • The scan dashboard (–ui dashboard)
    • A beam with a 1 keV Gaussian energy spread (exact mode)
    • The desktop app: the boron reference setup on the Geometry tab
    • The desktop app: the results of a finished run
    • The agent example: 200 boron ions into gold on silicon
    • Rebuild the pictures