Getting Started

Developer installation

Pixi configuration

Create your pixi environment using the pyproject.toml used by the build servers. From the root of the source, type the following:

pixi install

To update your environment with changes from the pyproject.toml, type:

pixi install

Note

For more information on the available tasks, type pixi run --list.

Note

For more details, please see the pixi documentation.

Note

To install pixi, please see the installation guide.

IDE configuration (optional)

The following is for configuring VSCode as the IDE but other IDEs may have similar configuration options.

VSCode can be configured to use the pixi environment by adding the following to the project’s .vscode/settings.json file:

{
    "python.defaultInterpreterPath": ".pixi/envs/default/bin/python"
}

Local Mantid development (optional)

SNAPRed supports development with a local Mantid build instead of the conda-distributed packages. This is useful for developers who need to make simultaneous changes to both SNAPRed and Mantid.

Prerequisites

  • A local Mantid build directory (e.g., from building Mantid from source)

  • Access to the Mantid source directory

Note: The Python interface files are automatically accessed from the source directory, eliminating the need to manually copy them to the build directory.

Setup

  1. Configure the build and source paths in pyproject.toml:

    [tool.pixi.feature.local-mantid.activation.env]
MANTID_BUILD_DIR = "/path/to/your/mantid/build"
MANTID_BUILD_SRC = "/path/to/your/mantid/source"

    Examples:

    • Build: /home/username/mantid/build, Source: /home/username/mantid/source

    • Build: /usr/local/mantid/build, Source: /usr/local/mantid/source

    • Build: /opt/mantid/build, Source: /opt/mantid/source

  2. Install the local-mantid environment:

    pixi install --environment local-mantid

Usage

Test the local Mantid configuration:

pixi run test-local-mantid

Comprehensive test (including workbench components):

pixi run test-local-mantid-full

Debug environment variables:

pixi run debug-local-mantid-env

Comprehensive test suite (recommended for troubleshooting):

pixi run test-local-mantid-comprehensive

Start SNAPRed with local Mantid:

pixi run snapred-local-module

Enter development shell:

pixi shell

How it works

The local-mantid environment:

  • Uses the mantid-developer package directly - This automatically includes all the same build tools, libraries, and dependencies that Mantid developers use, ensuring perfect compatibility and automatic updates when the mantid-developer environment changes

  • Automatically accesses Python interface from source - The MANTID_BUILD_SRC variable points directly to the source directory, eliminating the need to manually copy Python interface files

  • Handles package conflicts via environment variables - While mantid-developer installs conda versions of mantid, mantidworkbench, and mantidqt, our environment variables ensure your local build takes precedence:

    • PYTHONPATH: Points to local Python interface from source directory first, then build directory

    • LD_LIBRARY_PATH: Points to local shared libraries first

    • MANTIDPATH: Points to local build directory

    • MANTID_DATA_PATH: Points to local data directory

    • MANTID_FRAMEWORK_PATH: Points to local framework libraries

This approach exactly mirrors the typical developer workflow of using the mantid-developer environment, but automatically stays in sync with any dependency changes made by the Mantid team.

Troubleshooting

Import errors:

  • Ensure the source directory path is correct and contains Framework/PythonInterface/mantid/

  • Run pixi run debug-local-mantid-env to verify environment variables

Library errors:

  • Check that ${MANTID_BUILD_DIR}/lib contains the required shared libraries

  • Verify the build completed successfully

Path conflicts (workbench still using site-packages):

  • Run pixi run test-local-mantid-comprehensive for a complete diagnosis

  • Run pixi run test-local-mantid-full to verify all components are using local build

  • Check that both MANTID_BUILD_DIR and MANTID_BUILD_SRC are set correctly

  • Ensure the environment variables are taking precedence by checking the output of debug-local-mantid-env

Starting the gui

The gui can be started either by using the defined entrypoint

pixi run snapred

or by executing the entry in the module (which is what the entrypoint is defined as)

pixi run python -m snapred

Other common operations

Running tests

The unit test framework can be run using

pixi run test

Note that the tests currently have a fixture that tests for the presence of a directory containing “large” test files.

Integration tests

Integration tests require additional setup and test data. These tests are more comprehensive and test the full workflow of the application.

To run integration tests locally:

# Run integration tests with the integration test environment
env=tests/resources/integration_test pixi run pytest -m integration

# Run with verbose output to see detailed test progress
env=tests/resources/integration_test pixi run pytest -m integration -v

# Run with xvfb for headless GUI testing (Linux only)
xvfb-run --server-args="-screen 0 1280x1024x16" -a env=tests/resources/integration_test pixi run pytest -m integration

# Run specific integration test files
env=tests/resources/integration_test pixi run pytest tests/integration/test_diffcal.py -m integration

Note

Integration tests may take significantly longer to run than unit tests as they test complete workflows.

Note

Some integration tests require specific test data files and may be skipped if the data is not available.

Warning

Integration tests may create temporary files and workspaces. Ensure you have adequate disk space and permissions.

GUI tests

GUI tests can be run to test the graphical user interface:

# Run GUI tests with headless display (Linux)
env=tests/resources/headcheck.yml xvfb-run --server-args="-screen 0 1280x1024x16" --auto-servernum pixi run snapred --headcheck

# On systems with a display, you can run without xvfb
env=tests/resources/headcheck.yml pixi run snapred --headcheck

Building documentation

The documentation can be built using

pixi run build-docs

For development, you can use auto-rebuilding documentation that updates on file changes:

pixi run docs-autobuild

Then visit http://localhost:8000 to view the documentation.

You can also serve the built documentation locally:

pixi run docs-serve

Sphinx has been configured to turn warnings into errors to make it more clear that there are issues with the documentation.

Cleaning build artifacts

To clean all build artifacts:

pixi run clean-all

Or clean specific artifacts:

# Clean documentation build artifacts
pixi run clean-docs

# Clean PyPI build artifacts
pixi run clean-pypi

# Clean conda build artifacts
pixi run clean-conda