SCONE Troubleshooting Guide

Per the official Installation page, SCONE currently requires gfortran ≥ 8.3; support for other Fortran compilers is described as pending. You need CMake ≥ 3.10 and LAPACK/BLAS. When CMake fails, the cause is usually a missing dependency or version mismatch.

First, verify your toolchain: gfortran --version and cmake --version. On Ubuntu, pkg-config --exists lapack blas should succeed if those libraries are installed. (Do not require HDF5 here—the upstream CMakeLists.txt on the main branch does not define an HDF5 toggle.)

A clean rebuild often resolves transient build issues. Remove the build/ directory, recreate it, and run CMake again with explicit compiler and library paths if needed. For detailed error messages, use make VERBOSE=1.

# Check compiler availability
gfortran --version
cmake --version

# Verify required libraries (LAPACK/BLAS)
pkg-config --exists lapack blas
echo $?  # Should return 0

# Clean build and retry
rm -rf build/
mkdir build && cd build
cmake -DCMAKE_Fortran_COMPILER=gfortran ..
make VERBOSE=1  # See detailed error messages

If CMake cannot find the Fortran compiler, specify it explicitly: cmake -DCMAKE_Fortran_COMPILER=/path/to/gfortran ... To disable MPI (matches upstream option names), use -DMPI=OFF. To disable OpenMP, use -DOPENMP=OFF. See the project CMakeLists.txt.

Geometry errors are among the most common causes of SCONE failures. Overlapping cells, gaps between regions, duplicate surface IDs, or incorrect surface sense can lead to lost particles, segmentation faults, or nonsensical results. The error message "lost particle" or "escape to undefined region" indicates that a neutron entered a region not properly defined by your cell structure.

Surface sense is critical: a minus sign before a surface ID means the cell occupies the negative half-space (inside a cylinder, for example); no sign means the positive half-space. Ensure every region of space is covered by exactly one cell, with no overlaps or gaps. Duplicate surface IDs within the same namespace will cause parsing or runtime errors.

The most effective debugging tool for geometry is the viz block. It generates BMP images of the material distribution at specified planes, allowing you to visually verify that fuel, clad, water, and other regions are correctly placed. Add a viz block, run with a low population for a quick test, and inspect the output image.

viz excerpt only — paste into a complete input; not in run_all.ps1 by itself.

// Add this viz block inside a complete input (with geometry + nuclearData).
// Run with low pop/active/inactive while iterating on geometry.

viz {
  bmpZ {
    type bmp;
    output debugZ;
    what material;
    centre (0.0 0.0 0.0);
    width (5.0 5.0);
    axis z;
    res (500 500);
  }
}

The boundary condition boundary (0 0 0 0 0 0) sets vacuum on all six faces of the problem domain. If you intend reflective boundaries, you must use different values as specified in the SCONE input manual. Verify that your boundary matches the intended physics.

// ===================================================================
// boundary (0 0 0 0 0 0) + minimal CSG pin — runnable with testLib
// Vacuum on all six global faces; cell surface sense is separate (Input Manual).
// ===================================================================
type eigenPhysicsPackage;
pop      100;
active   5;
inactive 2;
XSdata   ce;
dataType ce;

collisionOperator { neutronCE { type neutronCEstd; } }
transportOperator { type transportOperatorDT; }

inactiveTally {}

activeTally {
  fissionRate { type collisionClerk; response (fission); fission { type macroResponse; MT -6; } }
}

// ===================================================================
// GEOMETRY
// ===================================================================
geometry {
  type geometryStd;
  boundary ( 0 0 0 0 0 0 );
  graph { type shrunk; }

  surfaces {
    fuelR { id 1; type zCylinder; radius 0.39218; origin (0.0 0.0 0.0); }
  }

  cells {
    pinCell { type simpleCell; id 10; surfaces (-1); filltype mat; material UO2; }
  }

  universes {
    root { id 1; type rootUniverse; border 1; fill u<2>; }
    pin  { id 2; type cellUniverse; cells (10); }
  }
}

// ===================================================================
// NUCLEAR DATA
// ===================================================================
nuclearData {
  handles { ce { type aceNeutronDatabase; aceLibrary $SCONE_ACE; } }
  materials {
    UO2 { temp 600; composition { 92235.03 4.50e-02; } }
  }
}

This file is runnable with testLib (single UO2 material). It illustrates global boundary vs cell surface sense; see the Basics page for a multi-material pin.

Material and nuclear data problems often manifest as immediate failures when SCONE tries to load cross sections or as runtime errors when a neutron enters a cell whose material is undefined or references missing nuclides. The aceLibrary path must point to a valid ACE-format file. If the path is wrong or the file is missing, SCONE will fail during initialization.

Use an absolute path for aceLibrary to avoid ambiguity. The temperature specified in each material (temp 600) should be consistent with the temperature tables you select via each ZAID suffix in your aceLibrary file (suffix meaning depends on how that library was processed—confirm against your evaluation/processing docs). Every ZAID in your composition must exist in the library file.

For minimal testing without a full cross-section library, use the testLib bundled with SCONE: set export SCONE_ACE=IntegrationTestFiles/testLib and run the verified examples in scone-examples/verify/. These use simplified compositions compatible with the minimal test library.

Before investing in long production runs, always run a smoke test. Use very small values for pop, active, and inactive—for example, pop 100; active 5; inactive 2;—to verify that your input parses correctly and that SCONE executes without crashing. A smoke test completes in seconds and quickly reveals syntax errors, missing materials, or geometry mistakes.

// ===================================================================
// Low-population smoke test — testLib / SCONE_ACE
// Matches ReactorMC Troubleshooting page (smoke_test.inp pattern).
// ===================================================================
type eigenPhysicsPackage;
pop      100;
active   5;
inactive 2;
XSdata   ce;
dataType ce;

collisionOperator { neutronCE { type neutronCEstd; } }
transportOperator { type transportOperatorDT; }

inactiveTally {}

activeTally {
  fissionRate { type collisionClerk; response (fission); fission { type macroResponse; MT -6; } }
}

// ===================================================================
// GEOMETRY
// ===================================================================
geometry {
  type geometryStd;
  boundary ( 0 0 0 0 0 0 );
  graph { type shrunk; }

  surfaces {
    cellR { id 3; type zCylinder; radius 0.63; origin (0.0 0.0 0.0); }
  }

  cells { }

  universes {
    root { id 1; type rootUniverse; border 3; fill u<999>; }
    pin  { id 999; type pinUniverse; radii (0.39218 0.40005 0.45720 0.0); fills (UO2 Water Water Water); }
  }
}

// ===================================================================
// NUCLEAR DATA
// ===================================================================
nuclearData {
  handles { ce { type aceNeutronDatabase; aceLibrary $SCONE_ACE; } }
  materials {
    UO2   { temp 600; composition { 92235.03 4.50e-02; } }
    Water { temp 600; composition { 1001.03 6.67e-02; 8016.03 3.33e-02; } }
  }
}

Once the smoke test passes, gradually increase the population and cycle counts. Start with pop 1000 and a few active cycles to check that tallies and k-effective estimates behave sensibly. Only then scale up to production settings.

Large SCONE calculations can consume significant memory and CPU time. If you encounter segmentation faults, extremely slow execution, or out-of-memory errors, reduce the problem size first. Simplify tallies (fewer map bins, lower resolution), use fewer particles per cycle, and ensure the geometry graph is optimized with graph { type shrunk; }.

Eigenvalue pin-cell calculations with minimal compositions (e.g., UO2 and water only, without helium gap or full Zircaloy) can trigger numerical instabilities such as SIGFPE when the fission source collapses. Use full material definitions (fuel, gap, clad, water) for pin examples, or verify with fixed-source tests or bare-sphere eigenvalue runs such as scone-examples/verify/test_simple_bare_sphere.

For shared-memory runs, set OMP_NUM_THREADS. Upstream builds may also link MPI (CMake MPI=ON by default); you can disable it with -DMPI=OFF for single-node workflows. Multi-process launches use your site's MPI starter—see the official Installation page.

Monte Carlo eigenvalue calculations require adequate statistics for reliable results. Poor convergence leads to inaccurate k-effective estimates and misleading tally uncertainties. Signs of poor convergence include statistical uncertainties above one percent, k-effective values that trend or oscillate across cycles, and disagreement between different estimators (e.g., collision vs. absorption).

To improve convergence, increase pop, inactive (source settling), and active (statistics). Typical production ranges vary widely by problem size; treat pop 2k–10k, inactive 50–200, and active 500–1000 as rules of thumb only. Monitor cycle-wise k (and any diagnostics you configure, e.g. a shannonEntropyClerk tally from the Input Manual) before trusting active-cycle tallies.

When seeking help from the SCONE developers or community, provide enough context for others to reproduce the problem. Include your complete input file (sanitized if it contains proprietary data), the exact error messages and relevant output logs, your SCONE version and build configuration, and a clear description of expected versus actual behavior. The SCONE project maintains a GitHub repository and issue tracker; the official documentation on Read the Docs is the authoritative reference for syntax and features.