lcmodel-wrapper 0.2.0__tar.gz → 0.3.0__tar.gz

lcmodel_wrapper-0.3.0/NOTICE

@@ -0,0 +1,24 @@
+PyLCModel (lcmodel_wrapper)
+Copyright (c) 2024 Julian P. Merkofer and contributors
+
+Licensed under the Apache License, Version 2.0 (see LICENSE).
+
+------------------------------------------------------------------------------
+LCModel
+------------------------------------------------------------------------------
+
+LCModel is NOT part of this project's copyright. It is a separate program by
+Dr. Stephen Provencher, distributed under the BSD 3-Clause License
+(Copyright (c) 1992-2021, Stephen Provencher); see LICENSE.lcmodel for the
+full text. Home page: https://s-provencher.com/lcmodel.shtml
+
+This wrapper bundles no LCModel code or binary. At run time it may obtain one
+from these sources, and the BSD 3-Clause license applies to every one of them:
+
+  - the community binary collection at https://github.com/schorschinho/LCModel
+    (maintained by Georg Oeltzschner and contributors),
+  - binaries and the container image ghcr.io/julianmer/lcmodel built by this
+    repository's CI (.github/workflows/lcmodel-binaries.yml) from the pinned
+    upstream source, unmodified, using the compilation flags documented there;
+    LICENSE.lcmodel and this NOTICE are published alongside them,
+  - a local build from the same source via gfortran.

{lcmodel_wrapper-0.2.0 → lcmodel_wrapper-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lcmodel_wrapper
-Version: 0.2.0
+Version: 0.3.0
 Summary: Lightweight Python wrapper for LCModel MRS fitting
 Author-email: Julian Merkofer <j.p.merkofer@tue.nl>
 License: Apache-2.0
@@ -16,6 +16,7 @@ Requires-Dist: scipy>=1.10
 Requires-Dist: nibabel>=4.0
 Requires-Dist: nifti-mrs>=1.0
 Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
 Requires-Dist: pandas>=1.4; extra == "test"
 Requires-Dist: openpyxl>=3.0; extra == "test"
 Dynamic: license-file
@@ -36,7 +37,7 @@ Dynamic: license-file
 
 ## Features
 
-- **Zero-setup binaries** — the LCModel executable is resolved automatically (download, build from source, or your own path); nothing is bundled in the wheel.
+- **Zero-setup binaries** — the LCModel executable is resolved automatically (download, container image, build from source, or your own path); nothing is bundled in the wheel.
 - **Flexible input** — NumPy arrays, NIfTI-MRS, jMRUI text, and LCModel `.RAW`, in time or frequency domain.
 - **Automated control files** — generated to match your data, or templated from an existing one.
 - **Basis conversion (experimental)** — jMRUI, FSL-MRS, LCModel `.RAW`, and Osprey/FID-A basis sets to `.basis`.
@@ -50,7 +51,6 @@ Dynamic: license-file
 ```bash
 pip install lcmodel-wrapper
 ```
-Enter your API token:
 
 ### From Source
 ```bash
@@ -58,6 +58,9 @@ git clone https://github.com/julianmer/PyLCModel.git
 cd PyLCModel
 pip install -e .
 ```
+Add `--recursive` to the clone (or run `git submodule update --init`) to also fetch the
+[ISMRM 2016 fitting challenge](https://www.ismrm.org/workshops/Spectroscopy16/mrs_fitting_challenge/)
+example data used by the tests.
 
 ---
 
@@ -66,11 +69,35 @@ pip install -e .
 The LCModel program is **not** part of this package and is **not** shipped in the wheel. On first use, the binary is resolved in this order:
 
 1. an explicit `path2exec="/path/to/lcmodel"` you pass to `PyLCModel`,
-2. a previously cached download/build (under `~/.cache/lcmodel_wrapper`, or `%LOCALAPPDATA%` on Windows; override with `LCMODEL_CACHE_DIR`),
+2. a previously cached download/build (under `~/.cache/lcmodel_wrapper/<os>-<arch>/`, or `%LOCALAPPDATA%` on Windows; override the root with `LCMODEL_CACHE_DIR`),
 3. a download of the matching binary for your OS/architecture from [schorschinho/LCModel](https://github.com/schorschinho/LCModel),
-4. a build from the LCModel Fortran source via `gfortran` (source fetched on demand).
+4. a download of the binary built by this repository's CI and attached to the [GitHub release](https://github.com/julianmer/PyLCModel/releases) matching the installed package version (Linux x86_64/aarch64 fully static, macOS arm64/x86_64 with libgfortran linked statically; each verified against its published SHA-256),
+5. **a container** — if `docker` (or `podman`) is installed and running, the image `ghcr.io/julianmer/lcmodel` is pulled and a small launcher script is cached that runs LCModel from it (Linux, macOS, and Windows),
+6. a build from the LCModel Fortran source via `gfortran` (source fetched on demand).
 
-There is no git submodule and no bundled `lcmodel/` folder — keeping both the repository and the PyPI wheel small.
+Every candidate is **run once before it is accepted** — LCModel is asked to identify itself, and anything that cannot execute or does not answer is moved to `<cache>/quarantine/` so the next source gets a turn. This is what stops a wrong-architecture download from being cached and served forever. Set `LCMODEL_SKIP_VERIFY=1` to bypass the check, or `LCMODEL_VERIFY_TIMEOUT` to change its 60 s bound.
+
+The cache is keyed by architecture, so a home directory shared across a mixed-architecture cluster does not have nodes fighting over one file.
+
+### Running from a container
+
+The container is the one option that behaves identically everywhere: inside it LCModel is always the same statically linked Linux binary, so nothing depends on your macOS version, Homebrew, or which Apple-silicon generation you have (upstream's macOS builds are tied to the machine they were compiled on, which is why an M1 build does not run on an M4). Docker Desktop, OrbStack, Colima, or rootless podman all work.
+
+On Linux and macOS the launcher bind-mounts your **working directory** and your **home directory** at the same paths inside the container, so the absolute paths in the control file need no translation. On Windows it mounts the **drives** holding those two at `/host/<LETTER>` and the wrapper rewrites the file paths in the control file to match (`C:\Users\me\x.basis` → `/host/C/Users/me/x.basis`); UNC paths are not supported. The one constraint: the basis set and any absolute `save_path` must live under the working or home directory (on Windows: on one of their drives); `PyLCModel` raises a clear error otherwise.
+
+```python
+lcmodel = PyLCModel(path2basis="~/basis/press_3t.basis")        # container used automatically if needed
+lcmodel = PyLCModel(path2basis="...", allow_docker=False)        # never use a container
+```
+
+Environment knobs: `LCMODEL_NO_DOCKER=1` disables the rung, `LCMODEL_DOCKER_IMAGE` overrides the image (e.g. a locally built one), `LCMODEL_PULL_TIMEOUT` bounds the pull (default 900 s), and `LCMODEL_RELEASE_TAG` selects which release (and matching image tag) steps 4 and 5 use instead of the default `v<package version>`. Delete `<cache>/lcmodel-container` to make the resolver try the native sources again.
+
+You can also use the image directly, without Python:
+```bash
+docker run --rm -i -v "$PWD:$PWD" -w "$PWD" ghcr.io/julianmer/lcmodel:latest < control.file
+```
+
+No LCModel code or binary is bundled — keeping both the repository and the PyPI wheel small. (The only git submodule in this repository is the optional example data under `example_data/`.)
 
 ---
 
@@ -130,9 +157,11 @@ This wrapper (the Python code) is released under the **Apache License 2.0** (see
 
 ## Acknowledgements
 
+- LCModel source code: created and made [available](https://s-provencher.com/lcmodel.shtml) free of charge (Stephen Provencher).
 - LCModel binaries: [schorschinho/LCModel](https://github.com/schorschinho/LCModel) (Georg Oeltzschner and contributors)
 - Basis conversion reference: [MRS Basis Set Conversion Toolbox](https://github.com/igweckay/MRS-Basis-Set-Conversion-Toolbox) (Kay Igwe)
-- NIfTI-MRS: [spec2nii](https://github.com/wtclarke/spec2nii), [NIfTI-MRS Pyhton tools](https://github.com/wtclarke/nifti_mrs_tools) (Will Clarke)
+- NIfTI-MRS: [spec2nii](https://github.com/wtclarke/spec2nii), [NIfTI-MRS Python tools](https://github.com/wtclarke/nifti_mrs_tools) (Will Clarke)
+- Example data: [ISMRM 2016 MRS Fitting Challenge](https://www.ismrm.org/workshops/Spectroscopy16/mrs_fitting_challenge/) (Małgorzata Marjańska, Dinesh Deelchand, Roland Kreis), mirrored via [wtclarke/mrs_fitting_challenge](https://github.com/wtclarke/mrs_fitting_challenge)
 
 ---
 

{lcmodel_wrapper-0.2.0 → lcmodel_wrapper-0.3.0}/README.md

@@ -14,7 +14,7 @@
 
 ## Features
 
-- **Zero-setup binaries** — the LCModel executable is resolved automatically (download, build from source, or your own path); nothing is bundled in the wheel.
+- **Zero-setup binaries** — the LCModel executable is resolved automatically (download, container image, build from source, or your own path); nothing is bundled in the wheel.
 - **Flexible input** — NumPy arrays, NIfTI-MRS, jMRUI text, and LCModel `.RAW`, in time or frequency domain.
 - **Automated control files** — generated to match your data, or templated from an existing one.
 - **Basis conversion (experimental)** — jMRUI, FSL-MRS, LCModel `.RAW`, and Osprey/FID-A basis sets to `.basis`.
@@ -28,7 +28,6 @@
 ```bash
 pip install lcmodel-wrapper
 ```
-Enter your API token:
 
 ### From Source
 ```bash
@@ -36,6 +35,9 @@ git clone https://github.com/julianmer/PyLCModel.git
 cd PyLCModel
 pip install -e .
 ```
+Add `--recursive` to the clone (or run `git submodule update --init`) to also fetch the
+[ISMRM 2016 fitting challenge](https://www.ismrm.org/workshops/Spectroscopy16/mrs_fitting_challenge/)
+example data used by the tests.
 
 ---
 
@@ -44,11 +46,35 @@ pip install -e .
 The LCModel program is **not** part of this package and is **not** shipped in the wheel. On first use, the binary is resolved in this order:
 
 1. an explicit `path2exec="/path/to/lcmodel"` you pass to `PyLCModel`,
-2. a previously cached download/build (under `~/.cache/lcmodel_wrapper`, or `%LOCALAPPDATA%` on Windows; override with `LCMODEL_CACHE_DIR`),
+2. a previously cached download/build (under `~/.cache/lcmodel_wrapper/<os>-<arch>/`, or `%LOCALAPPDATA%` on Windows; override the root with `LCMODEL_CACHE_DIR`),
 3. a download of the matching binary for your OS/architecture from [schorschinho/LCModel](https://github.com/schorschinho/LCModel),
-4. a build from the LCModel Fortran source via `gfortran` (source fetched on demand).
+4. a download of the binary built by this repository's CI and attached to the [GitHub release](https://github.com/julianmer/PyLCModel/releases) matching the installed package version (Linux x86_64/aarch64 fully static, macOS arm64/x86_64 with libgfortran linked statically; each verified against its published SHA-256),
+5. **a container** — if `docker` (or `podman`) is installed and running, the image `ghcr.io/julianmer/lcmodel` is pulled and a small launcher script is cached that runs LCModel from it (Linux, macOS, and Windows),
+6. a build from the LCModel Fortran source via `gfortran` (source fetched on demand).
 
-There is no git submodule and no bundled `lcmodel/` folder — keeping both the repository and the PyPI wheel small.
+Every candidate is **run once before it is accepted** — LCModel is asked to identify itself, and anything that cannot execute or does not answer is moved to `<cache>/quarantine/` so the next source gets a turn. This is what stops a wrong-architecture download from being cached and served forever. Set `LCMODEL_SKIP_VERIFY=1` to bypass the check, or `LCMODEL_VERIFY_TIMEOUT` to change its 60 s bound.
+
+The cache is keyed by architecture, so a home directory shared across a mixed-architecture cluster does not have nodes fighting over one file.
+
+### Running from a container
+
+The container is the one option that behaves identically everywhere: inside it LCModel is always the same statically linked Linux binary, so nothing depends on your macOS version, Homebrew, or which Apple-silicon generation you have (upstream's macOS builds are tied to the machine they were compiled on, which is why an M1 build does not run on an M4). Docker Desktop, OrbStack, Colima, or rootless podman all work.
+
+On Linux and macOS the launcher bind-mounts your **working directory** and your **home directory** at the same paths inside the container, so the absolute paths in the control file need no translation. On Windows it mounts the **drives** holding those two at `/host/<LETTER>` and the wrapper rewrites the file paths in the control file to match (`C:\Users\me\x.basis` → `/host/C/Users/me/x.basis`); UNC paths are not supported. The one constraint: the basis set and any absolute `save_path` must live under the working or home directory (on Windows: on one of their drives); `PyLCModel` raises a clear error otherwise.
+
+```python
+lcmodel = PyLCModel(path2basis="~/basis/press_3t.basis")        # container used automatically if needed
+lcmodel = PyLCModel(path2basis="...", allow_docker=False)        # never use a container
+```
+
+Environment knobs: `LCMODEL_NO_DOCKER=1` disables the rung, `LCMODEL_DOCKER_IMAGE` overrides the image (e.g. a locally built one), `LCMODEL_PULL_TIMEOUT` bounds the pull (default 900 s), and `LCMODEL_RELEASE_TAG` selects which release (and matching image tag) steps 4 and 5 use instead of the default `v<package version>`. Delete `<cache>/lcmodel-container` to make the resolver try the native sources again.
+
+You can also use the image directly, without Python:
+```bash
+docker run --rm -i -v "$PWD:$PWD" -w "$PWD" ghcr.io/julianmer/lcmodel:latest < control.file
+```
+
+No LCModel code or binary is bundled — keeping both the repository and the PyPI wheel small. (The only git submodule in this repository is the optional example data under `example_data/`.)
 
 ---
 
@@ -108,9 +134,11 @@ This wrapper (the Python code) is released under the **Apache License 2.0** (see
 
 ## Acknowledgements
 
+- LCModel source code: created and made [available](https://s-provencher.com/lcmodel.shtml) free of charge (Stephen Provencher).
 - LCModel binaries: [schorschinho/LCModel](https://github.com/schorschinho/LCModel) (Georg Oeltzschner and contributors)
 - Basis conversion reference: [MRS Basis Set Conversion Toolbox](https://github.com/igweckay/MRS-Basis-Set-Conversion-Toolbox) (Kay Igwe)
-- NIfTI-MRS: [spec2nii](https://github.com/wtclarke/spec2nii), [NIfTI-MRS Pyhton tools](https://github.com/wtclarke/nifti_mrs_tools) (Will Clarke)
+- NIfTI-MRS: [spec2nii](https://github.com/wtclarke/spec2nii), [NIfTI-MRS Python tools](https://github.com/wtclarke/nifti_mrs_tools) (Will Clarke)
+- Example data: [ISMRM 2016 MRS Fitting Challenge](https://www.ismrm.org/workshops/Spectroscopy16/mrs_fitting_challenge/) (Małgorzata Marjańska, Dinesh Deelchand, Roland Kreis), mirrored via [wtclarke/mrs_fitting_challenge](https://github.com/wtclarke/mrs_fitting_challenge)
 
 ---
 

{lcmodel_wrapper-0.2.0 → lcmodel_wrapper-0.3.0}/lcmodel_wrapper/__init__.py

@@ -4,18 +4,25 @@ LCModel itself is a separate program by Dr. Stephen Provencher, distributed unde
 BSD 3-Clause License (see LICENSE.lcmodel). This package only wraps it.
 """
 
-from .core import PyLCModel
+from ._version import __version__
+from .core import PyLCModel, LCModelError
 from .basis import read_basis, LCModelBasis
+from .binaries import verify_executable
 from .convert import ensure_basis, convert_to_basis, detect_format
-from . import binaries, io, control, coord, convert
+from .io import from_nifti_mrs, load_signals
+from . import binaries, container, io, control, coord, convert
 
 __all__ = [
     "PyLCModel",
+    "LCModelError",
+    "verify_executable",
     "read_basis",
     "LCModelBasis",
     "ensure_basis",
     "convert_to_basis",
     "detect_format",
+    "from_nifti_mrs",
+    "load_signals",
     "binaries",
     "io",
     "control",

lcmodel_wrapper-0.3.0/lcmodel_wrapper/_version.py

@@ -0,0 +1,4 @@
+# Single source of truth for the package version. pyproject.toml reads it at build time,
+# and binaries.py derives the GitHub release / container image tag ("v<version>") from
+# it, so every wheel pairs with the LCModel artifacts built alongside it.
+__version__ = "0.3.0"

{lcmodel_wrapper-0.2.0 → lcmodel_wrapper-0.3.0}/lcmodel_wrapper/basis.py

@@ -6,9 +6,9 @@
 #                                                                                                  #
 # Created: 26/06/26                                                                                #
 #                                                                                                  #
-# Purpose: Lightweight parser for LCModel ".basis" files. Replaces the previous dependency on       #
+# Purpose: Lightweight parser for LCModel ".basis" files. Replaces the previous dependency on      #
 #          fsl_mrs for reading basis metadata. It extracts only what the wrapper needs to build    #
-#          control files and to align fitted concentrations: the field strength (HZPPPM), dwell       #
+#          control files and to align fitted concentrations: the field strength (HZPPPM), dwell    #
 #          time (BADELT), number of points (NDATAB) and the ordered metabolite names (METABO).     #
 #                                                                                                  #
 ####################################################################################################