Agent guide

pysrim2 ships a skill, SKILL.md, that teaches coding agents (Claude Code and others that read SKILL.md folders) how to run SRIM through pysrim2: build a target and ion, run TRIM or SR, read the results, and run it in the Container. It includes a runnable example (boron into gold on silicon). The skill is shipped inside the wheel.

Install the skill

Install the command line and set up SRIM, the container (on macOS) and the skill:

uv tool install pysrim2
pysrim2 install            # SRIM, wine or container, and the skill
pysrim2 doctor             # everything should be [ok]

To install only the skill, run pysrim2 install skill [--agent claude|all] [--scope user|project]. It goes to the places below.

Option

Destination

default (--agent claude --scope user)

~/.claude/skills/pysrim2/

--scope project

<current folder>/.claude/skills/pysrim2/

--agent all

also ~/.agents/skills/pysrim2/

It is part of the default pysrim2 install. Re-running updates a copy pysrim2 wrote earlier; a skill folder it did not write is never overwritten unless you pass --yes. pysrim2 doctor reports an installed copy that is out of date.

The skill is for agents that use pysrim2. If you want an agent to work on pysrim2 itself, it should read AGENTS.md in the repository, which is for contributors.

Example prompts

Give the agent a task in plain language. Three examples:

  • “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.”

  • “How far do 1 MeV helium ions travel in silicon? Give me the stopping table.”

  • “Run a full-cascade TRIM calculation for 100 keV Ni into 50 nm Au / 500 nm Si / Al and plot the vacancy profile.”

What the agent does

  1. It runs pysrim2 doctor. If something fails, it follows the fix: line, or uses the container (see Container).

  2. It writes a short script with srim.Layer, Target, Ion and TRIM or SR, and runs it, natively or in the container with the script’s folder mounted at /data.

  3. It parses the results as DataFrames: results.vacancy.df, results.ioniz.df and so on (or results.to_dataframes(); collision only with include=["collision"]), the per-ion final positions in results.range3d.df (with ranges=1), and srim.analysis.implant_summary for the range and straggling in SRIM’s definitions. The columns are in DataFrames.

  4. For full cascades (calculation=2, collisions=2) it streams COLLISON.txt with results.collision.iter_events() instead of loading it, and exports in chunks with results.collision.to_parquet(path, chunk_rows=100_000) (needs pysrim2[parquet]).

  5. For a reproducible, shareable run, it writes a run.yaml (trim.to_yaml("run.yaml")) and runs it with pysrim2 run run.yaml --set ion.energy_keV=30; see the run.yaml example and run.yaml.

The result of the first prompt

For the first prompt (200 ions, random_seed=12345) the mean implantation depth is about 282 angstrom, and the lateral straggling (SRIM’s definition) is about 242 angstrom. The picture below is the depth of the ions from that run, with the Au/Si interface and the mean depth marked. The gallery entry has the script that makes it.

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

The agent can start from the boron script, which is the same file the skill ships as its example. It is in examples/scripts/ in the repository, and here it is:

"""B ions into 100 nm Au on a Si substrate: depth, lateral and radial straggling from RANGE_3D.txt.

Run natively (``python boron_in_gold_on_silicon.py``) or in the container (needs Podman ≥ 4.3)::

    podman run --rm --userns=keep-id:uid=1000,gid=1000 \
        -v "$PWD:/data:Z" ghcr.io/fsibt/pysrim2:<tag> \
        python /data/boron_in_gold_on_silicon.py

Quick Kinchin-Pease with 200 ions takes seconds (about a minute under QEMU). With
seed 12345 the mean depth is about 282 angstrom. Copies of the SRIM output files
are written to ``./output`` so they survive the container.

Per-ion final positions (``RANGE_3D.txt``) are ``results.range3d.df``; the summary
comes from ``srim.analysis.implant_summary``.
"""

import shutil
import sys
from pathlib import Path

from srim import TRIM, Ion, Layer, Target
from srim.analysis import implant_summary


def peak_vacancy_depth(results) -> float:
    """Depth (angstrom) where the total vacancy production per ion peaks."""
    vac = results.vacancy
    total = vac.knock_ons + vac.vacancies.sum(axis=1)
    return float(vac.depth[total.argmax()])


def run(number_ions: int = 200, outdir=None) -> dict:
    """Run TRIM and return SRIM-style range statistics (angstrom)."""
    target = Target(
        [
            Layer.from_formula("Au", density=19.3, width=1000.0),  # 100 nm
            Layer.from_formula("Si", density=2.33, width=10000.0),  # substrate
        ]
    )
    ion = Ion("B", energy=20e3)  # eV
    results = TRIM(
        target,
        ion,
        number_ions=number_ions,
        calculation=1,  # quick Kinchin-Pease; 2 = full cascade (much slower)
        angle_ions=7.0,
        ranges=1,  # write RANGE_3D.txt
        random_seed=12345,
    ).run()
    summary = implant_summary(results.range3d.df)
    if outdir is not None:
        outdir = Path(outdir)
        outdir.mkdir(parents=True, exist_ok=True)
        for name in ("RANGE_3D.txt", "RANGE.txt", "VACANCY.txt", "IONIZ.txt"):
            run_dir = Path(results.directory)
            for src in (run_dir / name, run_dir / "SRIM Outputs" / name):
                if src.is_file():
                    shutil.copy(src, outdir / name)
                    break
    return {
        "mean_depth_A": summary["mean_depth_A"],
        "straggle_depth_A": summary["straggle_depth_A"],
        "lateral_straggle_A": summary["lateral_straggle_A"],
        "radial_straggle_A": summary["radial_straggle_A"],
        "ions": summary["n_ions"],
        "peak_vacancy_depth_A": peak_vacancy_depth(results),
    }


if __name__ == "__main__":
    n = int(sys.argv[1]) if len(sys.argv) > 1 else 200
    for key, value in run(n, Path.cwd() / "output").items():
        print(f"{key}: {value:.1f}")

Runnable scripts for the current API, natively or in the container, are in examples/scripts; see Examples for the list.

SRIM © SRIM.com (James F. Ziegler) — free for non-commercial use only; see LEGAL.rtf.