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 ( |
|
|
|
|
also |
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¶
It runs
pysrim2 doctor. If something fails, it follows thefix:line, or uses the container (see Container).It writes a short script with
srim.Layer,Target,IonandTRIMorSR, and runs it, natively or in the container with the script’s folder mounted at/data.It parses the results as DataFrames:
results.vacancy.df,results.ioniz.dfand so on (orresults.to_dataframes();collisiononly withinclude=["collision"]), the per-ion final positions inresults.range3d.df(withranges=1), andsrim.analysis.implant_summaryfor the range and straggling in SRIM’s definitions. The columns are in DataFrames.For full cascades (
calculation=2,collisions=2) it streamsCOLLISON.txtwithresults.collision.iter_events()instead of loading it, and exports in chunks withresults.collision.to_parquet(path, chunk_rows=100_000)(needspysrim2[parquet]).For a reproducible, shareable run, it writes a
run.yaml(trim.to_yaml("run.yaml")) and runs it withpysrim2 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.

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.