Quick Start

This guide demonstrates a minimal PLEIADES workflow to execute SAMMY in under 5 minutes.

Basic Workflow

PLEIADES uses a factory pattern to create SAMMY runners that abstract the execution backend (local or Docker; NOVA backend is currently paused).

from pathlib import Path
from pleiades.sammy.factory import SammyFactory
from pleiades.sammy.interface import SammyFiles

# 1. Define your input files
files = SammyFiles(
    input_file=Path("path/to/input.inp"),
    parameter_file=Path("path/to/params.par"),
    data_file=Path("path/to/data.dat"),
)

# 2. Create a runner (auto-selects best available backend)
runner = SammyFactory.auto_select(
    working_dir=Path("./sammy_work"),
    output_dir=Path("./sammy_output"),
)

# 3. Execute SAMMY
try:
    runner.prepare_environment(files)
    result = runner.execute_sammy(files)

    if result.success:
        print(f"SAMMY completed in {result.runtime_seconds:.2f}s")
        runner.collect_outputs(result)
    else:
        print(f"SAMMY failed: {result.error_message}")
        print(result.console_output)

finally:
    runner.cleanup()

Understanding the Components

SammyFiles

SammyFiles is a container for the three required SAMMY input files:

  • input_file: The SAMMY input file (.inp)

  • parameter_file: The parameter file (.par)

  • data_file: The experimental data file (.dat)

from pleiades.sammy.interface import SammyFiles

files = SammyFiles(
    input_file=Path("ex012a.inp"),
    parameter_file=Path("ex012a.par"),
    data_file=Path("ex012a.dat"),
)

# Validate files exist
files.validate()

SammyFactory

SammyFactory creates configured runners. The simplest approach is auto_select(), which chooses the best available backend:

from pleiades.sammy.factory import SammyFactory

# Auto-select best backend
runner = SammyFactory.auto_select(
    working_dir=Path("./work"),
)

Backend priority: local (fastest) > docker (portable). NOVA backend is currently paused.

Execution Pipeline

The runner workflow has three stages:

  1. prepare_environment: Validates files and sets up the execution environment

  2. execute_sammy: Runs SAMMY and returns results

  3. collect_outputs: Moves output files to the output directory

# Stage 1: Prepare
runner.prepare_environment(files)

# Stage 2: Execute
result = runner.execute_sammy(files)

# Stage 3: Collect (only on success)
if result.success:
    runner.collect_outputs(result)

# Always cleanup
runner.cleanup()

Checking Results

SammyExecutionResult contains execution details:

result = runner.execute_sammy(files)

# Check success
if result.success:
    print(f"Execution ID: {result.execution_id}")
    print(f"Runtime: {result.runtime_seconds:.2f} seconds")
else:
    print(f"Error: {result.error_message}")
    print(f"Console output:\n{result.console_output}")

Output Files

After successful execution and collect_outputs(), standard SAMMY output files are available in the output directory:

  • SAMMY.LPT: Log file

  • SAMMY.LST: ASCII listing with detailed results

  • SAMMY.ODF: Plot file with calculated cross sections

  • SAMNDF.PAR: Updated parameter file

  • SAMNDF.INP: Updated input file

Next Steps