gammalooprs/settings/

global.rs

use std::fmt;

use bincode_trait_derive::{Decode, Encode};
use eyre::{Result as EyreResult, eyre};
use linnet::half_edge::involution::{EdgeVec, Orientation};
use schemars::JsonSchema;
use serde::{Deserialize, Deserializer, Serialize};
use symbolica::prelude::*;
pub use three_dimensional_reps::MediumMode;

use crate::{
    GammaLoopContext,
    cff::{expression::OrientationSelector, orientations::GraphOrientation},
    feyngen::GenerationType,
    processes::EvaluatorSettings,
    utils::{
        DEFAULT_ESURFACE_EXISTENCE_THRESHOLD, GS, W_,
        serde_utils::{
            IsDefault, deserialize_nonnegative_finite_f64, is_default_esurface_existence_threshold,
            is_false, is_float, is_true, is_usize, show_defaults_helper,
        },
        symbolica_ext::StringSerializedAtom,
    },
    uv::UVgenerationSettings,
};

#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object, get_all, set_all))]
#[derive(Debug, Clone, Serialize, Deserialize, Encode, Decode, PartialEq, JsonSchema)]
#[trait_decode(trait = GammaLoopContext)]
#[serde(default, deny_unknown_fields)]
#[derive(Default)]
pub struct GenerationSettings {
    // Generation Time settings
    /// Symbolic simplification, contraction, optimization, and compilation controls for evaluators.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub evaluator: EvaluatorSettings,
    /// Feynman-graph generation checks and diagnostics.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub feyngen: FeyGenSettings,

    /// Optional causal-orientation pattern applied during generation.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub orientation_pattern: OrientationPattern,
    /// Choose which numerator-energy reconstructions use the shared runtime sampling scale.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub uniform_numerator_sampling_scale: UniformNumeratorSamplingScale,
    /// Code-generation backend, compiler, and optimization flags.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub compile: GammaloopCompileOptions,
    /// Controls construction of tropical subgraph power-counting tables.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub tropical_subgraph_table: TropicalSubgraphTableSettings,
    /// Generation-time selection of local threshold counterterms.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub threshold_subtraction: ThresholdSubtractionSettings,
    /// Gauge used when summing external vector-particle polarizations.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub vector_polarization_sum_gauge: VectorPolarizationSumGauge,
    /// Ultraviolet counterterm generation, prescription, and Vakint backend settings.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub uv: UVgenerationSettings,
    /// Explicit particle-name sets forced to define graph cuts.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub force_cuts: Vec<Vec<String>>,
    /// Use explicitly supplied loop-momentum bases instead of the built-in basis heuristics.
    #[serde(skip_serializing_if = "is_false")]
    pub override_lmb_heuristics: bool,
    /// Sum all generated residue branches explicitly, removing runtime orientation selectors.
    #[serde(skip_serializing_if = "is_false")]
    pub explicit_orientation_sum_only: bool,
    /// Medium for amplitude generation; non-vacuum modes require local 3D UV subtraction
    /// and disabled threshold subtraction.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub medium: MediumSettings,
}

impl GenerationSettings {
    pub fn validate_for_process(&self, generation_type: GenerationType) -> EyreResult<()> {
        if self.medium.mode == MediumMode::Vacuum && self.medium.vacuum_subtraction {
            return Err(eyre!(
                "`global.generation.medium.vacuum_subtraction = true` requires a medium mode other than `vacuum`"
            ));
        }

        if generation_type == GenerationType::CrossSection && self.medium.mode != MediumMode::Vacuum
        {
            return Err(eyre!(
                "Cross-section (`xs`) generation is not supported in thermal modes or with vacuum subtraction"
            ));
        }

        if self.medium.mode != MediumMode::Vacuum && self.threshold_subtraction.enable_thresholds {
            return Err(eyre!(
                "Threshold subtraction is not supported in thermal modes; set `global.generation.threshold_subtraction.enable_thresholds = false`"
            ));
        }

        self.validate_medium_uv_compatibility()?;

        if self.uv.local_uv_cts_from_expanded_4d_integrands && !self.explicit_orientation_sum_only {
            return Err(eyre!(
                "`global.generation.uv.local_uv_cts_from_expanded_4d_integrands = true` requires `global.generation.explicit_orientation_sum_only = true` because projected 4D counterterms have term-local CFF orientation sums"
            ));
        }

        if self.explicit_orientation_sum_only && self.orientation_pattern.pat.is_some() {
            return Err(eyre!(
                "`global.generation.explicit_orientation_sum_only = true` requires summing all generated orientations; `global.generation.orientation_pattern` must be unset"
            ));
        }

        Ok(())
    }

    pub(crate) fn validate_medium_uv_compatibility(&self) -> EyreResult<()> {
        if (self.medium.mode != MediumMode::Vacuum || self.medium.vacuum_subtraction)
            && self.uv.local_uv_cts_from_expanded_4d_integrands
        {
            return Err(eyre!(
                "`global.generation.uv.local_uv_cts_from_expanded_4d_integrands = true` is unsupported for finite-medium modes or vacuum subtraction; use local 3D subtraction instead"
            ));
        }

        Ok(())
    }
}

#[cfg(test)]
mod generation_settings_tests {
    use super::{GenerationSettings, GenerationType, MediumMode, OrientationPattern};

    #[test]
    fn cross_sections_require_vacuum_mode_without_vacuum_subtraction() {
        let mut settings = GenerationSettings::default();
        settings
            .validate_for_process(GenerationType::CrossSection)
            .unwrap();

        settings
            .validate_for_process(GenerationType::Amplitude)
            .unwrap();

        settings.threshold_subtraction.enable_thresholds = false;
        for mode in [
            MediumMode::ThermodynamicEquilibrium,
            MediumMode::ZeroTemperatureEquilibrium,
        ] {
            for vacuum_subtraction in [false, true] {
                settings.medium.mode = mode;
                settings.medium.vacuum_subtraction = vacuum_subtraction;
                settings
                    .validate_for_process(GenerationType::Amplitude)
                    .unwrap();
                let error = settings
                    .validate_for_process(GenerationType::CrossSection)
                    .unwrap_err();
                assert!(error.to_string().contains("`xs`"));
                assert!(error.to_string().contains("not supported"));
            }
        }
    }

    #[test]
    fn thermal_modes_require_threshold_subtraction_disabled() {
        for mode in [
            MediumMode::ThermodynamicEquilibrium,
            MediumMode::ZeroTemperatureEquilibrium,
        ] {
            for vacuum_subtraction in [false, true] {
                let mut settings = GenerationSettings::default();
                settings.medium.mode = mode;
                settings.medium.vacuum_subtraction = vacuum_subtraction;

                let error = settings
                    .validate_for_process(GenerationType::Amplitude)
                    .unwrap_err();
                assert!(
                    error
                        .to_string()
                        .contains("Threshold subtraction is not supported")
                );
                assert!(
                    error.to_string().contains(
                        "global.generation.threshold_subtraction.enable_thresholds = false"
                    )
                );

                settings.threshold_subtraction.enable_thresholds = false;
                settings
                    .validate_for_process(GenerationType::Amplitude)
                    .unwrap();
            }
        }
    }

    #[test]
    fn vacuum_subtraction_requires_a_medium_mode() {
        let mut settings = GenerationSettings::default();
        settings.medium.vacuum_subtraction = true;
        for generation_type in [GenerationType::Amplitude, GenerationType::CrossSection] {
            let error = settings.validate_for_process(generation_type).unwrap_err();
            assert!(error.to_string().contains("vacuum_subtraction = true"));
            assert!(error.to_string().contains("other than `vacuum`"));
        }
    }

    #[test]
    fn finite_medium_supports_only_local_3d_subtraction() {
        for (mode, vacuum_subtraction) in [
            (MediumMode::ThermodynamicEquilibrium, false),
            (MediumMode::ZeroTemperatureEquilibrium, false),
            (MediumMode::ThermodynamicEquilibrium, true),
            (MediumMode::ZeroTemperatureEquilibrium, true),
        ] {
            let mut settings = GenerationSettings::default();
            settings.medium.mode = mode;
            settings.medium.vacuum_subtraction = vacuum_subtraction;
            settings.threshold_subtraction.enable_thresholds = false;
            settings
                .validate_for_process(GenerationType::Amplitude)
                .unwrap();

            settings.explicit_orientation_sum_only = true;
            settings.uv.local_uv_cts_from_expanded_4d_integrands = true;
            let error = settings
                .validate_for_process(GenerationType::Amplitude)
                .unwrap_err();
            assert!(
                error
                    .to_string()
                    .contains("use local 3D subtraction instead")
            );
        }
    }

    #[test]
    fn projected_4d_cff_requires_an_unfiltered_explicit_orientation_sum() {
        let mut settings = GenerationSettings::default();
        settings.uv.local_uv_cts_from_expanded_4d_integrands = true;

        let error = settings
            .validate_for_process(GenerationType::Amplitude)
            .unwrap_err();
        assert!(
            error
                .to_string()
                .contains("requires `global.generation.explicit_orientation_sum_only = true`")
        );

        settings.explicit_orientation_sum_only = true;
        settings
            .validate_for_process(GenerationType::Amplitude)
            .unwrap();

        settings.orientation_pattern = OrientationPattern::from_user_pattern("(+,-)").unwrap();
        let error = settings
            .validate_for_process(GenerationType::Amplitude)
            .unwrap_err();
        assert!(
            error
                .to_string()
                .contains("`global.generation.orientation_pattern` must be unset")
        );
    }
}

#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object, get_all, set_all))]
#[derive(Debug, Clone, Serialize, Deserialize, Encode, Decode, PartialEq, JsonSchema)]
#[trait_decode(trait = GammaLoopContext)]
#[serde(default, deny_unknown_fields)]
pub struct ThresholdSubtractionSettings {
    /// Generate local threshold counterterms for eligible E-surfaces.
    #[serde(skip_serializing_if = "is_true")]
    pub enable_thresholds: bool,
    /// Test E-surface existence against the active model while generating counterterms.
    #[serde(skip_serializing_if = "is_false")]
    pub check_esurface_at_generation: bool,
    /// Dimensionless tolerance used to compare the energy-squared E-surface invariant margin
    /// against `esurface_existence_threshold * E_cm^2` during generation-time checks.
    #[serde(
        deserialize_with = "deserialize_nonnegative_finite_f64",
        skip_serializing_if = "is_default_esurface_existence_threshold"
    )]
    #[schemars(range(min = 0.0))]
    pub esurface_existence_threshold: f64,
    /// Omit threshold counterterms whose E-surface coincides with a physical cut.
    #[serde(skip_serializing_if = "is_true")]
    pub skip_thresholds_that_are_cuts: bool,
    /// Generate local threshold counterterms without their integrated counterparts.
    #[serde(skip_serializing_if = "is_false")]
    pub disable_integrated_ct: bool,
    /// Simplify existence tests by assuming all external-state energies are positive.
    #[serde(skip_serializing_if = "is_true")]
    pub assume_positive_external_energies: bool,
}

impl Default for ThresholdSubtractionSettings {
    fn default() -> Self {
        Self {
            enable_thresholds: true,
            check_esurface_at_generation: false,
            esurface_existence_threshold: DEFAULT_ESURFACE_EXISTENCE_THRESHOLD,
            skip_thresholds_that_are_cuts: true,
            disable_integrated_ct: false,
            assume_positive_external_energies: true,
        }
    }
}

#[derive(
    Debug, Clone, Copy, Serialize, Deserialize, Encode, Decode, PartialEq, Eq, JsonSchema, Default,
)]
#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object))]
pub enum VectorPolarizationSumGauge {
    #[serde(rename = "Feynman", alias = "feynman")]
    Feynman,
    #[default]
    #[serde(rename = "LightLikeAxial", alias = "light_like_axial")]
    LightLikeAxial,
}

#[derive(
    Debug, Clone, Copy, Serialize, Deserialize, Encode, Decode, PartialEq, Eq, JsonSchema, Default,
)]
#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object))]
#[serde(rename_all = "snake_case")]
pub enum UniformNumeratorSamplingScale {
    #[default]
    None,
    BeyondQuadratic,
    All,
}

#[derive(Debug, Clone, Serialize, Deserialize, Encode, Decode, PartialEq, Eq, Copy, JsonSchema)]
#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object))]
#[serde(deny_unknown_fields)]
#[derive(Default)]
pub enum CompilationOptimizationLevel {
    O0,
    O1,
    #[default]
    O2,
    O3,
}

impl From<CompilationOptimizationLevel> for usize {
    fn from(value: CompilationOptimizationLevel) -> Self {
        match value {
            CompilationOptimizationLevel::O0 => 0,
            CompilationOptimizationLevel::O1 => 1,
            CompilationOptimizationLevel::O2 => 2,
            CompilationOptimizationLevel::O3 => 3,
        }
    }
}

impl fmt::Display for CompilationOptimizationLevel {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            CompilationOptimizationLevel::O0 => f.write_str("O0"),
            CompilationOptimizationLevel::O1 => f.write_str("O1"),
            CompilationOptimizationLevel::O2 => f.write_str("O2"),
            CompilationOptimizationLevel::O3 => f.write_str("O3"),
        }
    }
}

pub const fn yes() -> bool {
    true
}

#[cfg(target_vendor = "apple")]
pub const fn default_external_compiler() -> &'static str {
    "clang++"
}

#[cfg(not(target_vendor = "apple"))]
pub const fn default_external_compiler() -> &'static str {
    "g++"
}

pub fn default_external_compiler_owned() -> String {
    default_external_compiler().to_owned()
}

pub fn is_default_external_compiler(compiler: &str) -> bool {
    show_defaults_helper(default_external_compiler() == compiler)
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize, Encode, Decode, PartialEq, Eq, JsonSchema)]
#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object, get_all, set_all))]
#[derive(Default)]
pub enum CompilationMode {
    #[serde(rename = "c++", alias = "cpp")]
    Cpp,
    #[serde(rename = "assembly")]
    Assembly,
    #[default]
    #[serde(rename = "symjit")]
    Symjit,
}

impl fmt::Display for CompilationMode {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            CompilationMode::Cpp => f.write_str("c++"),
            CompilationMode::Assembly => f.write_str("assembly"),
            CompilationMode::Symjit => f.write_str("symjit"),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, Encode, Decode, PartialEq, Eq, JsonSchema)]
#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object, get_all, set_all))]
#[serde(default, deny_unknown_fields)]
pub struct CompilationOptionsSnapshot {
    /// Optimization level for the evaluator compiler. Indirect JIT translation caps it
    /// at O2; direct JIT translation always uses O2, regardless of this setting.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub optimization_level: CompilationOptimizationLevel,
    /// Skip Symbolica's tree-based analysis by translating instructions directly to SymJIT IR.
    /// Enabled by default to reduce JIT preparation work; disable to use the tree-based
    /// translator when comparing or diagnosing backend behavior. Also applies when JIT
    /// is the fallback for external artifacts. Direct translation always uses SymJIT O2,
    /// regardless of `optimization_level`; disable it to use JIT O0 or O1.
    #[serde(skip_serializing_if = "is_true")]
    pub jit_direct_translation: bool,
    #[serde(skip_serializing_if = "is_true")]
    pub fast_math: bool,
    #[serde(skip_serializing_if = "is_true")]
    pub unsafe_math: bool,
    #[serde(skip_serializing_if = "is_default_external_compiler")]
    pub compiler: String,
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub custom: Vec<String>,
}

impl Default for CompilationOptionsSnapshot {
    fn default() -> Self {
        GammaloopCompileOptions::default().options_snapshot()
    }
}

impl fmt::Display for CompilationOptionsSnapshot {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            f,
            "{} jit_direct_translation={} fast_math={} unsafe_math={} compiler={} custom={}",
            self.optimization_level,
            self.jit_direct_translation,
            self.fast_math,
            self.unsafe_math,
            self.compiler,
            if self.custom.is_empty() {
                "[]".to_string()
            } else {
                format!("[{}]", self.custom.join(", "))
            }
        )
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, Encode, Decode, PartialEq, Eq, JsonSchema)]
pub enum FrozenCompilationMode {
    Eager,
    Symjit(CompilationOptionsSnapshot),
    Cpp(CompilationOptionsSnapshot),
    Assembly(CompilationOptionsSnapshot),
}

impl FrozenCompilationMode {
    pub fn compile_enabled(&self) -> bool {
        !matches!(self, FrozenCompilationMode::Eager)
    }

    pub fn active_backend_name(&self) -> &'static str {
        match self {
            FrozenCompilationMode::Eager => "eager",
            FrozenCompilationMode::Symjit(_) => "symjit",
            FrozenCompilationMode::Cpp(_) => "c++",
            FrozenCompilationMode::Assembly(_) => "assembly",
        }
    }

    pub fn external_options(&self) -> Option<&CompilationOptionsSnapshot> {
        match self {
            FrozenCompilationMode::Cpp(options) | FrozenCompilationMode::Assembly(options) => {
                Some(options)
            }
            FrozenCompilationMode::Eager | FrozenCompilationMode::Symjit(_) => None,
        }
    }

    pub fn requires_external_compilation(&self) -> bool {
        matches!(
            self,
            FrozenCompilationMode::Cpp(_) | FrozenCompilationMode::Assembly(_)
        )
    }

    pub(crate) fn export_settings(&self) -> ExportSettings {
        ExportSettings::new().inline_asm(match self {
            FrozenCompilationMode::Assembly(_) => InlineASM::default(),
            FrozenCompilationMode::Cpp(_)
            | FrozenCompilationMode::Symjit(_)
            | FrozenCompilationMode::Eager => InlineASM::None,
        })
    }

    pub fn to_symbolica_compile_options(&self) -> Option<CompileOptions> {
        let options = self.external_options()?;
        Some(
            CompileOptions::new()
                .optimization_level(options.optimization_level.into())
                .fast_math(options.fast_math)
                .unsafe_math(options.unsafe_math)
                .compiler(options.compiler.clone())
                .args(options.custom.clone()),
        )
    }
}

impl fmt::Display for FrozenCompilationMode {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            FrozenCompilationMode::Eager => f.write_str("eager"),
            FrozenCompilationMode::Symjit(options) => write!(
                f,
                "symjit ({}, jit_direct_translation={})",
                options.optimization_level, options.jit_direct_translation,
            ),
            FrozenCompilationMode::Cpp(options) => write!(f, "c++ ({options})"),
            FrozenCompilationMode::Assembly(options) => write!(f, "assembly ({options})"),
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, Encode, Decode, PartialEq, JsonSchema)]
#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object, get_all, set_all))]
#[serde(default, deny_unknown_fields)]
pub struct GammaloopCompileOptions {
    /// Evaluator backend: Symbolica JIT, generated C++, or generated assembly.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub compilation_mode: CompilationMode,

    /// Optimization level for the evaluator compiler. Indirect JIT translation caps it
    /// at O2; direct JIT translation always uses O2, regardless of this setting.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub optimization_level: CompilationOptimizationLevel,

    /// Skip Symbolica's tree-based analysis by translating instructions directly to SymJIT IR.
    /// Enabled by default to reduce JIT preparation work; disable to use the tree-based
    /// translator when comparing or diagnosing backend behavior. Also applies when JIT
    /// is the fallback for external artifacts. Direct translation always uses SymJIT O2,
    /// regardless of `optimization_level`; disable it to use JIT O0 or O1.
    #[serde(skip_serializing_if = "is_true")]
    pub jit_direct_translation: bool,

    /// Permit algebraic floating-point transformations that ignore strict IEEE ordering.
    #[serde(skip_serializing_if = "is_true")]
    pub fast_math: bool,

    /// Permit compiler math optimizations that may change exceptional-value behavior.
    #[serde(skip_serializing_if = "is_true")] // default true
    pub unsafe_math: bool,

    /// External C++ compiler executable used by C++ and assembly modes.
    #[serde(skip_serializing_if = "is_default_external_compiler")] // default compiler
    pub compiler: String,
    /// Additional command-line arguments passed verbatim to the external compiler.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub custom: Vec<String>,
}

impl Default for GammaloopCompileOptions {
    fn default() -> Self {
        Self {
            compilation_mode: CompilationMode::Symjit,
            optimization_level: CompilationOptimizationLevel::O2,
            jit_direct_translation: true,
            fast_math: true,
            unsafe_math: true,
            compiler: default_external_compiler_owned(),
            custom: vec![],
        }
    }
}

impl GammaloopCompileOptions {
    pub fn options_snapshot(&self) -> CompilationOptionsSnapshot {
        CompilationOptionsSnapshot {
            optimization_level: self.optimization_level,
            jit_direct_translation: self.jit_direct_translation,
            fast_math: self.fast_math,
            unsafe_math: self.unsafe_math,
            compiler: self.compiler.clone(),
            custom: self.custom.clone(),
        }
    }

    pub fn requires_external_compilation(&self) -> bool {
        matches!(
            self.compilation_mode,
            CompilationMode::Cpp | CompilationMode::Assembly
        )
    }

    pub fn frozen_mode(&self, evaluator_settings: &EvaluatorSettings) -> FrozenCompilationMode {
        if !evaluator_settings.compile {
            return FrozenCompilationMode::Eager;
        }

        let options = self.options_snapshot();
        match self.compilation_mode {
            CompilationMode::Cpp => FrozenCompilationMode::Cpp(options),
            CompilationMode::Assembly => FrozenCompilationMode::Assembly(options),
            CompilationMode::Symjit => FrozenCompilationMode::Symjit(options),
        }
    }

    pub fn to_symbolica_compile_options(&self) -> CompileOptions {
        CompileOptions::new()
            .optimization_level(self.optimization_level.into())
            .fast_math(self.fast_math)
            .unsafe_math(self.unsafe_math)
            .compiler(self.compiler.clone())
            .args(self.custom.clone())
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, Encode, Decode, PartialEq, JsonSchema)]
#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object, get_all, set_all))]
#[serde(default, deny_unknown_fields)]
#[derive(Default)]
pub struct FeyGenSettings {
    /// Check that gamma-matrix simplification is closed under the generated rewrite sequence.
    #[serde(skip_serializing_if = "is_false")]
    pub gamma_simplification_closure_check: bool,
}

#[derive(Debug, Clone, Serialize, Deserialize, Encode, Decode, PartialEq, JsonSchema)]
#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object, get_all, set_all))]
#[serde(default, deny_unknown_fields)]
pub struct TropicalSubgraphTableSettings {
    /// Abort generation instead of reporting and skipping a failed tropical table construction.
    #[serde(skip_serializing_if = "is_false")]
    pub panic_on_fail: bool,
    /// Target superficial degree used when classifying tropical subgraphs.
    #[serde(skip_serializing_if = "is_float::<1>")] // default 1.0
    pub target_omega: f64,
    /// Disable tropical subgraph table construction entirely.
    #[serde(skip_serializing_if = "is_false")]
    pub disable_tropical_generation: bool,
}

impl Default for TropicalSubgraphTableSettings {
    fn default() -> Self {
        Self {
            panic_on_fail: false,
            target_omega: 1.0,
            disable_tropical_generation: false,
        }
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, Encode, Decode, Default, PartialEq, JsonSchema)]
#[trait_decode(trait = GammaLoopContext)]
#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object))]
#[serde(default, deny_unknown_fields)]
pub struct OrientationPattern {
    /// Symbolica pattern matched against serialized causal orientations.
    #[serde(
        default,
        skip_serializing_if = "IsDefault::is_default",
        deserialize_with = "deserialize_orientation_pattern_atom"
    )]
    pub pat: Option<StringSerializedAtom>,
}

fn deserialize_orientation_pattern_atom<'de, D>(
    deserializer: D,
) -> std::result::Result<Option<StringSerializedAtom>, D::Error>
where
    D: Deserializer<'de>,
{
    let raw = Option::<String>::deserialize(deserializer)?;
    raw.map(|value| OrientationPattern::parse_user_pattern(&value))
        .transpose()
        .map(|parsed| parsed.map(StringSerializedAtom))
        .map_err(serde::de::Error::custom)
}

impl From<Atom> for OrientationPattern {
    fn from(value: Atom) -> Self {
        OrientationPattern {
            pat: Some(StringSerializedAtom(value)),
        }
    }
}

impl OrientationPattern {
    fn is_orientation_delta_atom(atom: &Atom) -> bool {
        matches!(
            atom.as_view(),
            AtomView::Fun(function)
                if function.get_symbol().get_stripped_name() == "orientation_delta"
        )
    }

    fn split_top_level_args(input: &str) -> EyreResult<Vec<String>> {
        let mut args = Vec::new();
        let mut start = 0usize;
        let mut depth = 0usize;

        for (index, ch) in input.char_indices() {
            match ch {
                '(' | '[' | '{' => depth += 1,
                ')' | ']' | '}' => {
                    if depth == 0 {
                        return Err(eyre!(
                            "Unbalanced delimiter in orientation pattern: {input}"
                        ));
                    }
                    depth -= 1;
                }
                ',' if depth == 0 => {
                    let arg = input[start..index].trim();
                    if arg.is_empty() {
                        return Err(eyre!("Empty orientation-pattern entry in pattern: {input}"));
                    }
                    args.push(arg.to_string());
                    start = index + ch.len_utf8();
                }
                _ => {}
            }
        }

        if depth != 0 {
            return Err(eyre!(
                "Unbalanced delimiter in orientation pattern: {input}"
            ));
        }

        let tail = input[start..].trim();
        if tail.is_empty() {
            if args.is_empty() {
                return Err(eyre!("Orientation pattern cannot be empty"));
            }
            return Err(eyre!("Empty orientation-pattern entry in pattern: {input}"));
        }
        args.push(tail.to_string());

        Ok(args)
    }

    fn normalize_user_pattern(pattern: &str) -> EyreResult<String> {
        let trimmed = pattern.trim();
        if trimmed.is_empty() {
            return Err(eyre!("Orientation pattern cannot be empty"));
        }

        let args = if let Some(rest) = trimmed.strip_prefix("orientation_delta") {
            let rest = rest.trim();
            if !(rest.starts_with('(') && rest.ends_with(')')) {
                return Err(eyre!(
                    "orientation_delta patterns must use parentheses, got: {pattern}"
                ));
            }
            Self::split_top_level_args(&rest[1..rest.len() - 1])?
        } else if trimmed.starts_with('(') && trimmed.ends_with(')') {
            Self::split_top_level_args(&trimmed[1..trimmed.len() - 1])?
        } else {
            Self::split_top_level_args(trimmed)?
        };

        let normalized_args = args
            .into_iter()
            .map(|arg| match arg.as_str() {
                "+" | "+1" => "1".to_string(),
                "-" | "-1" => "-1".to_string(),
                _ => arg,
            })
            .collect::<Vec<_>>()
            .join(",");

        Ok(format!("orientation_delta({normalized_args})"))
    }

    pub fn parse_user_pattern(pattern: &str) -> EyreResult<Atom> {
        let trimmed = pattern.trim();
        if trimmed.is_empty() {
            return Err(eyre!("Orientation pattern cannot be empty"));
        }

        if let Ok(parsed) = try_parse!(trimmed)
            && Self::is_orientation_delta_atom(&parsed)
        {
            return Ok(parsed);
        }

        let normalized = Self::normalize_user_pattern(pattern)?;
        try_parse!(normalized.as_str())
            .map_err(|error| eyre!("Symbolica parsing error for orientation pattern: {error}"))
    }

    pub fn from_user_pattern(pattern: &str) -> EyreResult<Self> {
        Ok(Self {
            pat: Some(StringSerializedAtom(Self::parse_user_pattern(pattern)?)),
        })
    }

    pub fn from_orientation<O: GraphOrientation>(orientation: &O) -> Self {
        orientation.orientation_delta().into()
    }

    pub fn select_pattern(&self, atom: impl AtomCore) -> Option<Atom> {
        Some(
            atom.replace(self.pat.as_ref()?.as_view().to_pattern())
                .with(function!(GS.selected, &self.pat.as_ref()?.0))
                .replace(function!(GS.orientation_delta, W_.a___))
                .min_level(0)
                .max_level(Some(0))
                .with(Atom::Zero),
        )
    }

    pub fn filter<O: GraphOrientation>(&self, orientation: &O) -> bool {
        if let Some(pat) = &self.pat {
            let a = orientation.orientation_delta();

            // println!("{a}vs{}", pat.0);

            // println!("{a}");
            a.pattern_match(&pat.to_pattern(), None, None)
                .next()
                .is_some()
        } else {
            true
        }
    }

    pub fn alt_filter<O: GraphOrientation>(&self, orientation: &O) -> bool {
        self.filter(orientation)
    }
}

impl OrientationSelector for OrientationPattern {
    fn filter_orientation(&self, orientation: &EdgeVec<Orientation>) -> bool {
        self.filter(orientation)
    }
}

#[cfg(test)]
mod orientation_pattern_tests {
    use super::OrientationPattern;
    use linnet::half_edge::involution::{EdgeVec, Orientation};
    use symbolica::atom::AtomCore;

    fn orientation(value: i8) -> Orientation {
        match value {
            1 => Orientation::Default,
            -1 => Orientation::Reversed,
            0 => Orientation::Undirected,
            _ => panic!("invalid orientation encoding"),
        }
    }

    fn edgevec(values: impl IntoIterator<Item = i8>) -> EdgeVec<Orientation> {
        EdgeVec::from_iter(values.into_iter().map(orientation))
    }

    #[test]
    fn orientation_pattern_deserialization_supports_shorthand_and_missing_wrapper() {
        let wrapped: OrientationPattern =
            toml::from_str(r#"pat = "orientation_delta(+,-,0)""#).unwrap();
        let tuple_only: OrientationPattern = toml::from_str(r#"pat = "(+,-,0)""#).unwrap();
        let bare_args: OrientationPattern = toml::from_str(r#"pat = "+,-,0""#).unwrap();

        assert_eq!(wrapped, tuple_only);
        assert_eq!(wrapped, bare_args);
        assert_eq!(
            wrapped.pat.as_ref().unwrap().to_string(),
            "orientation_delta(1,-1,0)"
        );
        assert!(wrapped.filter(&edgevec([1, -1, 0])));
        assert!(!wrapped.filter(&edgevec([1, 1, 0])));
    }

    #[test]
    fn orientation_pattern_repeated_wildcards_enforce_identical_bindings() {
        let pattern: OrientationPattern =
            toml::from_str(r#"pat = "(+,+,-,x_,-,x_,+,0,+,y_,-,+)""#).unwrap();

        assert!(pattern.filter(&edgevec([1, 1, -1, 1, -1, 1, 1, 0, 1, 0, -1, 1])));
        assert!(pattern.filter(&edgevec([1, 1, -1, 0, -1, 0, 1, 0, 1, -1, -1, 1])));
        assert!(!pattern.filter(&edgevec([1, 1, -1, 1, -1, 0, 1, 0, 1, 0, -1, 1])));
        assert!(pattern.alt_filter(&edgevec([1, 1, -1, 1, -1, 1, 1, 0, 1, 0, -1, 1])));
    }

    #[test]
    fn orientation_pattern_accepts_canonical_namespaced_roundtrip() {
        let original = OrientationPattern::from_user_pattern("(+,-,0)").unwrap();
        let canonical = original.pat.as_ref().unwrap().0.to_canonical_string();
        let reparsed = OrientationPattern::from_user_pattern(&canonical).unwrap();

        assert_eq!(original, reparsed);
        assert!(reparsed.filter(&edgevec([1, -1, 0])));
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, Encode, Decode, PartialEq, JsonSchema)]
#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object, get_all, set_all))]
#[serde(default, deny_unknown_fields)]
pub struct Parallelisation {
    /// Worker threads used by Feynman-graph generation.
    #[serde(skip_serializing_if = "is_usize::<1>")]
    pub feyngen: usize,
    /// Worker threads used to construct symbolic graph evaluators.
    #[serde(skip_serializing_if = "is_usize::<1>")]
    pub generate: usize,
    /// Worker threads used for evaluator compilation.
    #[serde(skip_serializing_if = "is_usize::<1>")]
    pub compile: usize,
    /// Worker threads used by numerical integration.
    #[serde(skip_serializing_if = "is_usize::<1>")]
    pub integrate: usize,
}

impl Default for Parallelisation {
    fn default() -> Self {
        Self {
            feyngen: 1,
            generate: 1,
            compile: 1,
            integrate: 1,
        }
    }
}

#[cfg_attr(feature = "python", pyo3::pyclass(from_py_object, get_all, set_all))]
#[derive(Debug, Clone, Serialize, Deserialize, Encode, Decode, PartialEq, JsonSchema)]
#[trait_decode(trait = GammaLoopContext)]
#[serde(default, deny_unknown_fields)]
pub struct MediumSettings {
    /// `vacuum`, `thermodynamic_equilibrium` at `runtime.general.inverse_temperature`, or its
    /// `zero_temperature_equilibrium` limit; equilibrium modes use the model's chemical potentials.
    #[serde(skip_serializing_if = "IsDefault::is_default")]
    pub mode: MediumMode,
    /// Subtract each medium weight's vacuum limit, keeping only the medium-dependent part;
    /// requires a non-vacuum mode.
    #[serde(skip_serializing_if = "is_false")]
    pub vacuum_subtraction: bool,
}

impl Default for MediumSettings {
    fn default() -> Self {
        Self {
            mode: MediumMode::Vacuum,
            vacuum_subtraction: false,
        }
    }
}