.. _installation: ============ Installation ============ Install ``pysrim2`` with `uv `_ or pip. Python 3.11 or newer is required. The import name is ``srim``. pysrim2 has two parts that are installed separately, and most users want both: the library (``import srim``, used in your own Python code) and the command line (``pysrim2 install``, which sets up SRIM itself). The library, depending on how you work: .. code-block:: bash uv add pysrim2 # in a uv project uv venv && source .venv/bin/activate && uv pip install pysrim2 # uv venv python -m venv .venv && source .venv/bin/activate && pip install pysrim2 # pip venv uv run --with pysrim2 my_simulation.py # one-off script, nothing installed The command line (it does not make ``import srim`` available to your own Python):: uv tool install pysrim2 && pysrim2 install If the original ``pysrim`` is installed, remove it first, because both packages provide the ``srim`` module: ``uv remove pysrim && uv add pysrim2`` in a uv project, ``uv pip uninstall pysrim && uv pip install pysrim2`` in a uv venv, or ``pip uninstall pysrim && pip install pysrim2`` with pip. .. admonition:: SRIM licence SRIM © SRIM.com (James F. Ziegler) — free for non-commercial use only; see ``LEGAL.rtf``. pysrim2 never ships SRIM; the installer downloads it and keeps Ziegler's ``LEGAL.rtf`` next to every copy. Commercial users must get SRIM from `srim.org `_ themselves. You do not need SRIM if you only analyse existing output files. Quick start ----------- .. code-block:: bash uv tool install pysrim2 # the pysrim2 command; or: pip install pysrim2 pysrim2 install --dry-run # show every step and the exact commands, change nothing pysrim2 install # do it pysrim2 doctor # check the result With no component names, ``pysrim2 install`` picks the right set for your platform (see below) and also installs the :doc:`agent skill `. Steps that need administrator rights ask for confirmation first (or run with ``--yes``); ``--dry-run`` never changes anything. See :doc:`cli` for all options and exit codes. Windows (native) ---------------- ``pysrim2 install`` runs two steps: ``srim`` downloads SRIM-2013 into ``%LOCALAPPDATA%\pysrim2\srim``, and ``vb5`` puts the Visual Basic 5 runtime and the OCX controls TRIM needs next to it. Registering the OCX controls (``regsvr32``) needs administrator rights. pysrim2 does not elevate by itself: run ``pysrim2 install vb5`` from an elevated (Administrator) terminal. The confirmation prompt (or ``--yes``) is not a UAC prompt. Linux (native, through wine) ---------------------------- The default set is ``wine``, ``srim`` and ``skill``. The ``wine`` step is two parts: 1. *wine packages.* It installs wine with 32-bit support, ``xvfb-run``, ``cabextract``, ``unzip`` and ``curl`` through your package manager (``apt``, ``dnf``, ``zypper`` or ``pacman``; Fedora and Arch are untested). This needs ``sudo`` and asks first. On other distributions install them yourself, see the `WineHQ download page `_. 2. *private wine prefix.* A 32-bit prefix under ``~/.local/share/pysrim2/wine`` with the VB5 runtime and OCX controls. pysrim2 never touches ``~/.wine`` and ignores ``$WINEPREFIX``; the prefix variable is only set in the environment of the child processes it starts. SRIM runs headless through ``xvfb-run`` on a 1024x768x24 virtual screen, so no display is needed. macOS ----- Native SRIM is not supported on macOS. Use the :doc:`container`; running ``pysrim2 install`` uses Docker if it is already running (with the seccomp profile on Docker 29 and newer, see :doc:`container`). If there is no container runtime it installs Podman, starts a Podman machine and pulls the image. It never installs Docker Desktop, which needs a paid subscription for larger organisations and a GUI installation with administrator rights. Desktop app ----------- The optional desktop app (``pysrim2 app``) guides the SRIM setup in a window. It needs the ``app`` extra (PySide6, matplotlib, the notebook tools marimo and JupyterLab, and nbconvert for the notebook PDF export; PySide6 alone is a download of over 100 MB, so the app is not part of the default install). Install it into the pysrim2 you already use with ``pysrim2 install app``, which needs no administrator rights and also downloads the Chromium that the PDF export prints with, then start the app with ``pysrim2 app``. See :doc:`app` for the setup, the status bar and the settings. Where things live ----------------- pysrim2 keeps its files in one data directory: ``%LOCALAPPDATA%\pysrim2`` on Windows, ``~/Library/Application Support/pysrim2`` on macOS and ``${XDG_DATA_HOME:-~/.local/share}/pysrim2`` elsewhere. These environment variables override the defaults: ``PYSRIM2_HOME`` The data directory. ``PYSRIM2_SRIM_DIR`` The directory holding ``TRIM.exe``. If unset, pysrim2 uses ``/srim``, then an existing ``/tmp/srim``. ``PYSRIM2_WINEPREFIX`` The private wine prefix (default ``/wine``). ``TRIM().run()`` and ``SR().run()`` use this SRIM directory when you do not pass one. Runs happen in private copies of this directory (see :class:`srim.rundir.RunDir`); the installed directory is not written to. Installing SRIM by hand ----------------------- If you prefer, extract SRIM yourself into any directory that contains ``TRIM.exe`` and point ``PYSRIM2_SRIM_DIR`` (or the ``srim_directory`` argument of ``run()``) at it. pysrim2 never writes into such a directory. The archive pysrim2 installs is the `srim-2013 release `_ (``srim.2013.zip``, SHA-256 ``f425c4715d5a849c1f521a8fc14aff58d41066fa4ca773546690a220ff3acecf``, with ``LEGAL.rtf`` and ``SRIM-NOTICE.txt`` as separate assets). A checksum mismatch is a hard error and nothing is installed. On Linux you still need the wine packages and prefix: ``pysrim2 install wine``. Troubleshooting --------------- Start with ``pysrim2 doctor``: every failing check has a ``fix:`` line. **The install seems stuck.** Long sub-steps print a progress line when they start (creating the wine prefix, winetricks, the VB5 runtime, the SRIM download); the last line tells you where it is. Wine setup is bounded: a ``wineserver`` that does not exit within 60 s is stopped. Press Ctrl-C to abort; the private prefix's wine processes are stopped. **An old winetricks.** pysrim2 always downloads and uses its own pinned, checksum-verified winetricks and ignores any winetricks on your ``PATH`` (old copies do not know the OCX verbs it needs). **Mono, Gecko and controller drivers.** They are disabled for the private prefix (the Wine Mono/Gecko prompts and the USB, controller and Bluetooth drivers can hang or crash headless setups). SRIM does not use them. **"X connection to :N broken" and Mesa/EGL warnings.** Harmless; pysrim2 filters them from ``TRIM.run()`` and ``SR.run()`` output. **A run fails.** ``SRIMProcessError`` carries SRIM's stderr; ``SRIMRunError`` means SRIM wrote no result (old output is deleted before each run, so a crash never returns a previous run's data).