Skip to content

Installation

pynxtools-spm is a Python package published on PyPI. This tutorial walks you through installing it, either as a standalone package or together with NOMAD.

Who is this tutorial for?

This tutorial is for anyone who wants to convert Scanning Probe Microscopy (SPM) data into NeXus files with pynxtools-spm:

  • experimentalists who want to run the reader from the command line on their own STM, STS, or AFM files,
  • users of a NOMAD Oasis who want the SPM reader available inside their Oasis,
  • developers who want to extend the reader orchestra with a new vendor file format.

What should you know before this tutorial?

You should be comfortable with a terminal and with Python virtual environments. If either is new to you, these are good starting points:

What you will know at the end of this tutorial?

You will know

  • how to create a virtual environment for pynxtools-spm,
  • how to install pynxtools-spm, either standalone or as a plugin of pynxtools,
  • how to install pynxtools-spm in development (editable) mode,
  • how to install pynxtools-spm together with NOMAD,
  • how to verify that the spm reader is available.

Steps

1. Create and activate a virtual environment

pynxtools-spm requires Python 3.10 or newer (tested up to 3.13); we recommend Python 3.12. Create a dedicated virtual environment so that the installation does not interfere with other Python projects. We recommend uv, an extremely fast Python package and project manager, but the venv module of the standard library works as well.

uv creates the virtual environment and installs the requested Python version in one step.

uv venv .venv --python=3.12

Note that the Python version has to be installed beforehand.

python3 -m venv .venv

Both commands create the environment in a directory called .venv. Activate it:

source .venv/bin/activate

Note

Ensure that the virtual environment is activated in all the following steps.

2. Install the pynxtools-spm package

Install the latest stable release from PyPI to use pynxtools-spm as a standalone package:

uv pip install pynxtools-spm

pip install pynxtools-spm

Alternatively, install it as a plugin of the pynxtools package, which pulls in pynxtools-spm through the spm extra:

uv pip install pynxtools[spm]

pip install pynxtools[spm]

You can also install the latest development version directly from GitHub:

uv pip install git+https://github.com/FAIRmat-NFDI/pynxtools-spm.git

pip install git+https://github.com/FAIRmat-NFDI/pynxtools-spm.git

Note

Every installation method also installs pynxtools as a dependency with a suitable version (pynxtools>=0.15.0).

3. Install in development mode (optional)

If you want to contribute to the code repository, e.g. to extend the reader orchestra with a new vendor file format, clone the repository and install it in editable mode together with the dev and docs extras:

git clone https://github.com/FAIRmat-NFDI/pynxtools-spm.git
cd pynxtools-spm

uv pip install -e ".[dev,docs]"

pip install -e ".[dev,docs]"

Then install the pre-commit hooks and create a branch to work on:

pre-commit install
git checkout -b <branch_name>

The docs extra installs MkDocs and its plugins, so that you can build this documentation locally with mkdocs serve (the build additionally requires the tree command line utility).

4. Install pynxtools-spm with NOMAD

To use pynxtools-spm in NOMAD, install it into the same Python environment as the nomad-lab package. NOMAD discovers pynxtools-spm automatically through its Python entry points, so no further configuration is needed. It also picks up the three example uploads (STS, STM, and AFM) that the package ships.

First install NOMAD (see the NOMAD installation guide), then install pynxtools-spm:

uv pip install nomad-lab --extra-index-url https://gitlab.mpcdf.mpg.de/api/v4/projects/2187/packages/pypi/simple
uv pip install pynxtools[spm]

pip install nomad-lab --extra-index-url https://gitlab.mpcdf.mpg.de/api/v4/projects/2187/packages/pypi/simple
pip install pynxtools[spm]

Note

Installing pynxtools-spm with NOMAD does not provide any additional advantage unless you deploy NOMAD, called NOMAD Oasis, on your premises or in the cloud. For installation and configuration details, see NOMAD Oasis.

5. Verify the installation

The reader is used through the pynx convert command line interface of pynxtools. Check that the command is available and that spm is listed among the installed readers:

pynx convert --help

The --reader option of the printed help lists the installed readers; spm must be one of them. A minimal conversion looks like this:

pynx convert --nxdl NXstm --reader spm --output output.nxs eln_data.yaml nanonis_stm_file.sxm config.json

Further reading