Deborah.Miriam.MultiEnsembleLoader

generate_trMi_raw_vector(
    trM_raw::Vector{Float64}
) -> Vector{Float64}

Construct a length-5 vector containing a dummy scaling entry and the unscaled trace values (trMi_raw) for one configuration.

Arguments

• trM_raw::Vector{Float64}: Unscaled trace values of length 4 (raw[1] to raw[4]).

Returns

• Vector{Float64} of length 5:
  • trMi_raw[1] = 1.0 (placeholder factor)
  • trMi_raw[2] to trMi_raw[5] = direct copy of trM_raw[1:4] (no rescaling).

Notes

• This utility is a companion to generate_trMi_vector but omits all $\kappa$ and volume rescaling. It simply places the raw values alongside a constant leading entry.

generate_trMi_vector(
    trM_raw::Vector{Float64},
    nf::Int,
    ns::Int,
    nt::Int,
    kappa::Float64
) -> Vector{Float64}

Convert raw trace values into scaled traces (trMi) for one configuration.

Arguments

• trM_raw::Vector{Float64}: Unscaled trace values of length 4 (raw[1] to raw[4])
• nf::Int: Number of quark f`lavors
• ns::Int: Spatial lattice extent
• nt::Int: Temporal lattice extent
• kappa::Float64: Hopping parameter

Returns

• Vector{Float64} of length 5, representing scaled trace moments:
  • trMi[1] = $12 \, N_{\text{f}} \, V$ ($V = N_S^3 \times N_T$)
  • trMi[2] to trMi[5]: scaled raw values with κ weighting

Notes

• The scaling factor follows the rule: trMi[j+1] = trM_raw[j] $\times ( 12 \, N_{\text{f}} \, V ) \, ( 2 \, \kappa )^j$ for $j = 1,2,3,4$

• In the end, we have

\[\texttt{trMi[i]} = \left\{ \; 12 N_f V ,\; 2\kappa N_f\, \text{Tr}\, M^{-1} ,\; (2\kappa)^2 N_f\, \text{Tr}\, M^{-2} ,\; (2\kappa)^3 N_f\, \text{Tr}\, M^{-3} ,\; (2\kappa)^4 N_f\, \text{Tr}\, M^{-4} \;\right\}\]

load_grouped_trace_data(
    cfg::TOMLConfigMiriam.FullConfigMiriam,
    paths::PathConfigBuilderMiriam.MiriamPathConfig;
    jobid::Union{Nothing, String}=nothing,
    replace_bc::Bool=false,
    replace_ul::Bool=false,
    take_only_lb::Bool=false,
) -> Dict{String, Dict{String, NamedTuple}}

Load and organize trace data from disk into a nested dictionary structure, grouped by ensemble and trace type.

Arguments

• cfg::TOMLConfigMiriam.FullConfigMiriam: Parsed TOML configuration containing labels, training targets, and bootstrap setup.
• paths::PathConfigBuilderMiriam.MiriamPathConfig: Auto-generated paths for accessing trace data on disk.

Keyword Arguments

• jobid::Union{Nothing, String}=nothing: Optional job identifier to distinguish multiple runs.
• replace_bc::Bool=false: If true, substitute "YP_bc" in place of "Y_bc" for file reads and keys.
• replace_ul::Bool=false: If true, substitute "YP_ul" in place of "Y_ul" for file reads and keys.
• take_only_lb::Bool=false: If true, only pick labeled-side traces ("Y_tr" and "Y_bc" or "YP_bc" depending on replace_bc) and skip all unlabeled-side traces ("Y_ul"/"YP_ul") regardless of replace_ul.

Behavior

• When take_only_lb = false (default):
  • The loader reads, in order: "Y_tr", then ("YP_bc" if replace_bc else "Y_bc"), then ("YP_ul" if replace_ul else "Y_ul").
• When take_only_lb = true:
  • The loader reads only "Y_tr" and ("YP_bc" if replace_bc else "Y_bc"), and does not read any Y_UL files even if replace_ul = true.
• Per-prefix data are sorted by configuration number before being stored.
• Missing files are skipped with a warning.

Returns

• Dict{String, Dict{String, NamedTuple}}: A nested dictionary:
  • Outer keys: Ensemble names (e.g., "L8T4b1.60k13570").
  • Inner keys: Trace labels (e.g., "Y_tr", "Y_bc", "Y_ul"; or "YP_bc", "YP_ul" when replacements are enabled and not suppressed by take_only_lb).
  • Values: NamedTuple with fields:
    • values::Vector{Vector{Float64}}: Scaled trMi vectors of length 5 per configuration ($\left[ 12 \, N_{\text{f}} \, V \,,\; \left( 2 \, \kappa \right)^1 \, N_{\text{f}} \, \text{Tr} \, M^{-1} \,, \cdots \,, \; \left( 2 \, \kappa \right)^4 \, N_{\text{f}} \, \text{Tr} \, M^{-4} \right]$).
    • values_raw::Vector{Vector{Float64}}: Unscaled trMi_raw vectors of length 5 per configuration (typically $\left[ 1.0 \,,\; \text{Tr} \, M^{-1} \,,\; \cdots ,\; \text{Tr} \, M^{-4} \right]$).
    • indices::Vector{Int}: Sequential indices 1:N aligned with values.
    • conf_nums::Vector{Int}: Configuration numbers aligned with values.

Additionally, each ensemble contains a "Y_info" entry:

• "Y_info" => ( ... ) with fields:
  • tags::Vector{String}: Row-wise original tags such as "LB-TR[j]", "LB-BC[j]", or "UL[j]".
  • secondary_tags::Vector{String}: Row-wise secondary tags for coarse grouping: "Y_lb" when the row came from "Y_tr", "Y_bc", or "YP_bc"; "Y_ul" when the row came from "Y_ul" or "YP_ul". (If take_only_lb=true, this vector will naturally contain only "Y_lb".)
  • indices::Vector{Int}: Source indices j (i.e., which TrMi slot contributed).
  • conf_nums::Vector{Int}: Corresponding configuration numbers.
  • values::Vector{Float64}: (Reserved/empty placeholder in this loader.)
  • values_raw::Vector{Float64}: (Reserved/empty placeholder in this loader.)

parse_kappa_from_ensemble_name(
    ens::String,
    jobid::Union{Nothing, String}=nothing
) -> Float64

Extract the $\kappa$ value from an ensemble name string.

Arguments

• ens::String: Ensemble name containing a pattern like kXXXXX (e.g., "L8T4b1.60k13580")
• jobid::Union{Nothing, String}: Optional job identifier for logging.

Returns

• Float64: Parsed $\kappa$ value, interpreted as "0.XXXXX"

Throws

• ErrorException if the pattern k\d+ is not found in the input string.