cryosweep

Analysis of Quantum Design PPMS and MPMS measurement files (.dat) — a Qt-free analysis core with a JSON contract, a command-line interface, and a desktop GUI built on the same analyzers.

One file in, physics out: cryosweep detects which measurement it is looking at, separates the sweeps, fits the appropriate models, and reports what it found — including when it cannot report something, and why.

That last clause is the point. In the status bar above, cryosweep reports θ_D drifting 160 % across fields — the lattice should be field-independent — and a Sommerfeld coefficient γ that has gone negative. Neither is handed back as a result; both are flagged as physics that does not hold.

The physics behind each — the models, the fitted quantities, and the criteria the detectors use — is documented in docs/physics-reference.md.

Install

Python 3.11 or newer (developed and tested on 3.14). Check with python3 -V.

To run cryosweep on your data:

python3 -m venv ~/cryosweep
~/cryosweep/bin/pip install 'cryosweep[gui]'
~/cryosweep/bin/cryosweep-gui

That is plain pip installing the published wheel from PyPI into a directory of its own. To uninstall, delete ~/cryosweep. To type cryosweep instead of the full path, add alias cryosweep=~/cryosweep/bin/cryosweep to your shell profile. (On Windows the executables are in Scripts\ rather than bin/.)

If python3 -V printed something older than 3.11, name a newer one explicitly — python3.13 -m venv ~/cryosweep — or install one from python.org/downloads. Its macOS installer is universal, so it covers Intel Macs as well, which Homebrew no longer supports.

If you already use uv or pipx, one line does the same: uv tool install 'cryosweep[gui]'.

To use cryosweep inside your own project, script, or agent:

pip install cryosweep

This gives you the analysis core and the cryosweep command line, with no Qt. Add the desktop app with pip install 'cryosweep[gui]'.

The GUI is optional because the analysis core and CLI are Qt-free by design, and Qt is by far the heaviest dependency here — leaving it out keeps an agent or CI install a quarter of the size. Installing without it still gives you every analyzer; only cryosweep-gui needs the extra, and it says so if you run it.

If pip refuses

No matching distribution found for cryosweep — your pip belongs to a Python older than 3.11. pip filtered out every release and then reported "none", which reads as though the project does not exist; the real reason is one line higher in its output (Ignored the following versions that require a different python version). Check with python3 -V and use the venv route above.

error: externally-managed-environment — your Python is managed by Homebrew or your distribution and refuses installs into itself (PEP 668). This is not a cryosweep restriction. Use the venv route above.

command not found: cryosweep after a successful install — it went into a venv that is not on your PATH. Call it by full path, or add the alias above.

From a clone, for development:

python3 -m venv .venv          # python3 must be 3.11+; see above
.venv/bin/pip install -e '.[gui]'

Quickstart

The examples/ folder has a runnable file per probe, so you can try everything before pointing it at your own data (examples/README.md says what each file shows and which tab/inputs to use — the Hall examples in particular open on the Resistivity tab first, because Hall measurements share the resistivity file format).

Those files ship with the repository rather than the wheel, so after a pip install fetch one first — or clone the repo and run the commands as written:

curl -O https://raw.githubusercontent.com/Vova2B/cryosweep/main/examples/heat_capacity.dat
cryosweep analyze heat_capacity.dat

cryosweep analyze examples/magnetization_vsm.dat
cryosweep analyze examples/heat_capacity.dat
cryosweep analyze examples/thermal_transport.dat
cryosweep report examples/resistivity_superconductor.dat
cryosweep-gui

The first fits Curie-Weiss and reports θ = −10 K; report prints a Markdown summary instead of JSON; cryosweep-gui opens the desktop app.

Some measurements need inputs the file does not carry. MPMS files hold no molar mass or sample mass, so the analyzer gates rather than guessing — supply them and it proceeds:

cryosweep analyze examples/magnetization_mpms.dat --molar-mass 200 --mass-mg 10

Hall measurements use the same file format as ordinary resistivity — only the wiring differs — so the Hall analyzer is invoked explicitly, with the channel and the sample thickness:

cryosweep hall examples/hall_field_sweeps.dat \
    --hall-channel 1 --thickness 0.5 --thickness-unit mm --long-channel 2

which reports R_H = -2.500e-07 m^3/C.

Built to be driven by a program

Every command prints one JSON object on stdout (logs go to stderr) and sets a meaningful exit code, so cryosweep is usable from a script, a pipeline, or an LLM agent without screen scraping:

Exit codes distinguish no result from a result you should look at: 0 ok, 10 gated (a required input is missing — the payload names the flag), 11 low confidence, 2 bad input. Codes 10 and 11 still print a full JSON envelope. Output is byte-stable for the same input, so it diffs and caches cleanly. A ready-made agent guide ships in skill/cryosweep/SKILL.md.

Example data

Everything in examples/ is written by tools/make_examples.py.

Eight of the ten files are synthetic, generated by the same builders that produce the test fixtures. The numbers are physically consistent and each file places a feature where it exercises the relevant analyzer — but they are not measurements of any real material.

Two are anonymized subsets of real measurements — magnetization_vsm_multifield.dat and heat_capacity_multifield.dat — because no synthetic file reproduces what real multi-field data does to the segmentation and window-selection paths. They are decimated, and everything that identified the sample, the operator or the instrument has been replaced: sample material and comment, all five instrument serial numbers, the acquisition date (the absolute Time Stamp column is rebased to zero, since it decodes to the measurement instant), the calibration free text in the Comment column, and the formula weight and sample mass, which are neutral values chosen only so the fits report a plausible moment. The generators carry an assert_no_identity_leak post-condition that refuses to write the file if any token of the source identity survives. The measured shapes are real; the sample metadata is not, and no scientific conclusion should be drawn from any file here.

Regenerate with (the two real-derived files are skipped, and left untouched, on any machine without the private source data):

.venv/bin/python tools/make_examples.py

Tests

QT_QPA_PLATFORM=offscreen .venv/bin/python -m pytest

Run it from the repository root — some tests build fixture paths relative to the working directory and launch the CLI as a subprocess.

The suite ships with synthetic .dat fixtures only. Tests that need real measurement files, or the maintainer's local reference gallery, skip when those are absent, so a fresh clone is green with no data at all. To exercise the optional real-data tests against your own files, create real_data_map.json in the repository root mapping logical keys to paths.

File format and provenance

The .dat files this program reads are produced by Quantum Design instrument software and retain their original ; Copyright …, Quantum Design, Inc. header lines; those are part of the format and are preserved rather than stripped. The format is read, not redistributed.

This project is not affiliated with, endorsed by, or supported by Quantum Design, Inc. "PPMS" and "MPMS" are used only to identify the instruments and file formats cryosweep is compatible with. PPMS is a registered trademark of Quantum Design, Inc.

Licence

cryosweep is released under the PolyForm Noncommercial License 1.0.0.

Free for research and education — universities, public research institutes, national laboratories, government and nonprofit organizations, and individuals, regardless of how the work is funded. Use it, modify it, redistribute it, publish results with it.

Commercial use requires a licence. If you are a company, see COMMERCIAL.md — it is a short email to info@cryosweep.org.

Third-party dependency licences, and what the LGPL requires of the Qt binding, are recorded in THIRD-PARTY-LICENSES.md.

Known issues

Known defects are listed in KNOWN-ISSUES.md. Most are display or ergonomics issues found by inspecting every rendered example, and each of those names the example file that reproduces it. The items that change a fitted number or an exported value are listed at the top of that file — among them a temperature-setpoint binning bug in the Hall analyzer that could fabricate a carrier-density point, and the derived-quantity fallback that let it reach the CSV, both found on real data and now reproduced by examples/hall_mixed_sweeps.dat so the test suite can hold them closed. Items 39–42 are still open; all three concern what a Hall figure shows, not any number.

Versioning

Semantic versioning. While the version is 0.x the interfaces are not frozen: the CLI JSON envelope, the exit codes and the CSV columns may change between releases. Tagging 1.0.0 is what freezes them.

Plot appearance, GUI layout and the internal Python API are not covered by that promise at any version — figures are expected to improve, and doing so is not a breaking change.

Project documents

• CHANGELOG.md — what is in each release
• ROADMAP.md — what is planned for 1.0, with measured costs where they were measured
• KNOWN-ISSUES.md — defects found, all fixed except items 39–42, each with what reproduces it and what caused it
• CONTRIBUTING.md and CLA.md — how to contribute, and the one-time agreement
• SECURITY.md — reporting a vulnerability
• CODE_OF_CONDUCT.md

Contributing

Bug reports, files that break the loader, and pull requests are welcome — see CONTRIBUTING.md. Because the project is dual-licensed, a pull request needs a one-time Contributor License Agreement; you keep your copyright, and a bot walks you through it on your first PR.

Citing

If cryosweep contributes to work you publish, please cite it — see CITATION.cff.