Analyzing SAMMY Results

This guide covers interpreting and visualizing SAMMY output using PLEIADES analysis tools.

Overview

After SAMMY execution, output files are collected in the output directory. PLEIADES provides tools to parse and visualize these results.

SAMMY Output Files:

File	Description
`SAMMY.LPT`	Detailed log with fit iterations, chi-squared, parameters
`SAMMY.LST`	ASCII listing with calculated cross sections and data
`SAMMY.ODF`	Plot file with energy-dependent quantities
`SAMNDF.PAR`	Updated parameter file (after fitting)
`SAMNDF.INP`	Updated input file

Using ResultsManager

ResultsManager is the primary interface for loading and analyzing SAMMY results.

Loading Results

from pathlib import Path
from pleiades.sammy.results.manager import ResultsManager

# Paths to output files
lpt_file = Path("./sammy_output/SAMMY.LPT")
lst_file = Path("./sammy_output/SAMMY.LST")

# Create results manager
results_manager = ResultsManager(
    lpt_file_path=lpt_file,
    lst_file_path=lst_file,
)

# Access parsed data
data = results_manager.get_data()

print(f"Energy range: {data.energy.min():.3e} - {data.energy.max():.3e} eV")
print(f"Data points: {len(data.energy)}")

Accessing Data Arrays

The get_data() method returns an object with NumPy arrays:

data = results_manager.get_data()

# Energy array (eV)
energies = data.energy

# Experimental transmission
exp_transmission = data.transmission

# Calculated (fitted) transmission
calc_transmission = data.calculated

# Uncertainties
uncertainties = data.uncertainty

Understanding LPT Files

The LPT file contains detailed information about the fitting process. PLEIADES extracts key information using LptManager.

Fit Iterations

Access information from each fitting iteration:

# Access fit results
if results_manager.run_results.fit_results:
    for i, fit_result in enumerate(results_manager.run_results.fit_results):
        print(f"\nIteration {i+1}:")

        # Chi-squared metrics
        chi_sq = fit_result.get_chi_squared_results()
        if chi_sq.chi_squared is not None:
            print(f"  Chi-squared: {chi_sq.chi_squared:.4f}")
            print(f"  Degrees of freedom: {chi_sq.dof}")
            print(f"  Reduced chi-squared: {chi_sq.reduced_chi_squared:.6f}")

        # Physics parameters
        physics = fit_result.get_physics_data()
        if hasattr(physics, 'broadening_parameters'):
            bp = physics.broadening_parameters
            if bp.thick is not None:
                print(f"  Number density: {bp.thick:.6e} atoms/barn-cm")
            if bp.temp is not None:
                print(f"  Temperature: {bp.temp:.2f} K")

Final Fit Results

Get the final iteration results:

fit_results = results_manager.run_results.fit_results

if fit_results:
    final = fit_results[-1]
    chi = final.get_chi_squared_results()

    print(f"Final reduced chi-squared: {chi.reduced_chi_squared:.6f}")

Understanding LST Files

The LST file contains the ASCII listing of calculated and experimental transmission values. PLEIADES parses this using LstManager.

The LST data is automatically loaded when you create a ResultsManager with the lst_file_path parameter.

Plotting Results

PLEIADES provides built-in plotting functionality for visualizing transmission fits.

Basic Transmission Plot

results_manager.plot_transmission()

This creates a plot showing:

Experimental data points with error bars
Fitted (calculated) transmission curve
Legend with labels

Customized Plot

import matplotlib.pyplot as plt

fig = results_manager.plot_transmission(
    figsize=(12, 8),
    title="Au-197 Neutron Transmission Fit",
    xscale="log",           # Logarithmic energy axis
    data_color="blue",      # Experimental data color
    final_color="red",      # Fit curve color
    show_diff=True,         # Show residual plot
    plot_uncertainty=True,  # Include error bars
    show=False,             # Don't display immediately
)

plt.tight_layout()
plt.savefig("transmission_fit.png", dpi=150)
plt.show()

Plot Options

Parameter	Description	Default
`figsize`	Figure size (width, height)	`(10, 6)`
`title`	Plot title	`None`
`xscale`	X-axis scale (“linear” or “log”)	`"linear"`
`show_diff`	Show residual subplot	`False`
`plot_uncertainty`	Show error bars	`True`
`data_color`	Color for experimental data	`"blue"`
`final_color`	Color for calculated fit	`"red"`

Fit Quality Metrics

Understanding Chi-Squared

Chi-squared measures the agreement between experimental data and the fit:

\[\chi^2 = \sum_{i=1}^{N} \frac{(T_{\text{exp},i} - T_{\text{calc},i})^2}{\sigma_i^2}\]

Where:

\(T_{\text{exp}}\) is experimental transmission
\(T_{\text{calc}}\) is calculated transmission
\(\sigma\) is uncertainty
\(N\) is number of data points

Reduced Chi-Squared

Reduced chi-squared normalizes by degrees of freedom:

\[\chi^2_{\text{red}} = \frac{\chi^2}{\text{DOF}}\]

Interpretation:

\(\chi^2_{\text{red}} \approx 1\): Good fit
\(\chi^2_{\text{red}} >> 1\): Poor fit (underestimated uncertainties or bad model)
\(\chi^2_{\text{red}} << 1\): Overfitting or overestimated uncertainties

Accessing Metrics

# Get final chi-squared
final_fit = results_manager.run_results.fit_results[-1]
chi = final_fit.get_chi_squared_results()

print(f"Chi-squared: {chi.chi_squared:.2f}")
print(f"DOF: {chi.dof}")
print(f"Reduced chi-squared: {chi.reduced_chi_squared:.4f}")

Extracting Fitted Parameters

Broadening Parameters

After fitting, access updated broadening parameters:

final_fit = results_manager.run_results.fit_results[-1]
physics = final_fit.get_physics_data()

if hasattr(physics, 'broadening_parameters'):
    bp = physics.broadening_parameters
    print(f"Number density: {bp.thick:.6e} atoms/barn-cm")
    print(f"Temperature: {bp.temp:.2f} K")

Updated Parameter File

The fitted resonance parameters are written to SAMNDF.PAR. This file can be used as input for subsequent SAMMY runs:

from pleiades.sammy.interface import SammyFiles

# Use fitted parameters for next analysis
files = SammyFiles(
    input_file=Path("analysis.inp"),
    parameter_file=Path("sammy_output/SAMNDF.PAR"),  # Fitted params
    data_file=Path("new_data.twenty"),
)

Complete Analysis Example

from pathlib import Path
import matplotlib.pyplot as plt
from pleiades.sammy.results.manager import ResultsManager

# Load results
results = ResultsManager(
    lpt_file_path=Path("sammy_output/SAMMY.LPT"),
    lst_file_path=Path("sammy_output/SAMMY.LST"),
)

# Print summary
data = results.get_data()
print(f"Energy range: {data.energy.min():.2e} - {data.energy.max():.2e} eV")
print(f"Data points: {len(data.energy)}")

# Chi-squared evolution
print("\nFit Convergence:")
for i, fit in enumerate(results.run_results.fit_results):
    chi = fit.get_chi_squared_results()
    print(f"  Iteration {i+1}: chi²_red = {chi.reduced_chi_squared:.4f}")

# Final metrics
final_chi = results.run_results.fit_results[-1].get_chi_squared_results()
print(f"\nFinal reduced chi-squared: {final_chi.reduced_chi_squared:.4f}")

# Create publication-quality plot
fig = results.plot_transmission(
    figsize=(10, 8),
    title="Neutron Transmission Fit",
    xscale="log",
    show_diff=True,
    plot_uncertainty=True,
    show=False,
)

plt.savefig("fit_results.png", dpi=300, bbox_inches="tight")
plt.show()

Troubleshooting

Empty results: Ensure SAMMY completed successfully. Check SAMMY.LPT for error messages.
Missing chi-squared: Chi-squared is only calculated during fitting runs, not initial calculations. Ensure your INP file requests fitting.
No plot data: The LST file must contain the DATA column. Check that your SAMMY run produced output correctly.

Next Steps

Preparing SAMMY Input Files - Modify inputs for re-analysis
SammyFactory Workflow Guide - Run additional SAMMY iterations
Backend Selection Guide - Try different execution backends