Installation

This guide covers installing PLEIADES and its prerequisites.

Prerequisites

PLEIADES is a Python interface to SAMMY, a Fortran code for neutron resonance analysis. Depending on which backend you plan to use, you may need to install SAMMY separately.

Backend Requirements:

Local backend: Requires SAMMY installed and available in your PATH
Docker backend: Requires Docker installed and running
NOVA backend: Requires NOVA credentials (no local SAMMY installation needed)

Note

SAMMY is external software maintained by Oak Ridge National Laboratory. For SAMMY installation instructions, refer to the SAMMY documentation.

User Installation

Install from PyPI (recommended for most users):

pip install pleiades-neutron

Or from conda-forge:

conda install -c conda-forge pleiades-neutron

NOVA Backend (Optional - Currently Paused)

Note

NOVA backend support is currently paused while the NOVA API stabilizes. The installation instructions below are retained for future use.

To use the NOVA web service backend, install with the nova extra:

pip install pleiades-neutron[nova]

This installs the nova-galaxy package required for NOVA integration.

Developer Installation

For contributing to PLEIADES or running from source:

Prerequisites:

git: Version control system
pixi: Package manager (installation guide)

Steps:

Clone the PLEIADES repository:

git clone https://github.com/lanl/PLEIADES.git
cd PLEIADES

Install using Pixi:
```
pixi install
```
This creates an isolated environment with all dependencies.
Verify installation:
```
pixi run post_install_check
```
This checks if SAMMY is accessible (required for local backend only).
Configure SAMMY path (local backend only):

Add SAMMY’s bin directory to your PATH:
```
export PATH=$PATH:/path/to/sammy/bin
```
Add this to your shell configuration file (e.g., ~/.bashrc) to persist.

Development Tasks

PLEIADES provides several Pixi tasks for development:

# Run tests
pixi run test

# Build documentation
pixi run build-docs

# Format code
pixi run format

# Run linting checks
pixi run lint

# Install pre-commit hooks
pixi run pre-commit-install

Available Environments

Two Pixi environments are available:

default: Development environment with testing and linting tools
jupyter: Includes JupyterLab for interactive notebook work

Activate the Jupyter environment:

pixi shell -e jupyter

Verifying Installation

After installation, verify PLEIADES is working:

from pleiades.sammy.factory import SammyFactory

# Check available backends
available = SammyFactory.list_available_backends()
for backend, is_available in available.items():
    status = "available" if is_available else "not available"
    print(f"{backend.value}: {status}")

This will show which backends are configured and ready to use.

Troubleshooting

SAMMY not found (local backend):

Ensure SAMMY is installed and its bin directory is in your PATH. Run which sammy to verify.

Docker backend unavailable:

Ensure Docker is installed and running. Run docker info to verify.

NOVA backend unavailable:

Set the required environment variables:

export NOVA_URL="https://your-nova-server"
export NOVA_API_KEY="your-api-key"

Import errors:

Ensure you’re using Python 3.10 or later:

python --version