Deborah.Miriam.EnsembleUtils

Deborah.Miriam.EnsembleUtils.build_dummy_param — Function

build_dummy_param(
    cfg::TOMLConfigMiriam.FullConfigMiriam, 
    ens::String,
    jobid::Union{Nothing, String}=nothing
) -> Params{Float64}

Construct a dummy Params{Float64} object from config and ensemble name.

Arguments

cfg::TOMLConfigMiriam.FullConfigMiriam: Configuration object containing lattice input metadata.
ens::String: Ensemble name string containing encoded $\kappa$ (must match k13580 format).
jobid::Union{Nothing, String}: Optional job ID for logging.

Returns

Params{Float64}: Lattice parameter object with extracted $\kappa$ value from ensemble name.

source

Deborah.Miriam.EnsembleUtils.build_ensemble_array_from_trace — Function

build_ensemble_array_from_trace(
    grouped_data::Dict{String, Dict{String, NamedTuple}},
    cfg::TOMLConfigMiriam.FullConfigMiriam,
    jobid::Union{Nothing, String}=nothing
) -> Tuple{Ensemble.EnsembleArray{Float64}, Vector{String}}

Build an EnsembleArray{Float64} (collection of EnsembleStruct) and the corresponding ensemble-name list from grouped trace data.

Arguments

grouped_data::Dict{String, Dict{String, NamedTuple}}: Outer dictionary keyed by ensemble name (e.g., "L8T4b1.60k13570"). Each inner dictionary maps trace prefixes (e.g., "Y_tr", "Y_bc", "Y_ul", "YP_bc", "YP_ul"; "Y_info" is ignored) to a NamedTuple with fields:
- values::Vector{Vector{Float64}} — rows of rescaled $\text{Tr} \, M^{-n}$ (length 4 or 5)
- values_raw::Vector{Vector{Float64}} — rows of un-rescaled raw $\text{Tr} \, M^{-n}$ (length 4 or 5)
- conf_nums::Vector{Int} — configuration numbers
cfg::TOMLConfigMiriam.FullConfigMiriam: Configuration used to determine the ensemble set and to build dummy parameters.
jobid::Union{Nothing, String}: Optional job identifier for structured logging.

Returns

(ensemble_array, key_list):
- ensemble_array::EnsembleArray{Float64}: Holds one Deborah.Miriam.Ensemble.EnsembleStruct per ensemble. Each struct includes:
  - trMi (rescaled, rows of length 5; a placeholder may be appended by the loader),
  - trMi_raw (un-rescaled, rows of length 5; a placeholder may be appended by the loader),
  - source_tags (0: Y_tr, 1: Y_bc/YP_bc, 2: Y_ul/YP_ul),
  - secondary_tags (0: Y_lb, 1: Y_ul), and aligned conf_nums.
- key_list::Vector{String}: The list of ensemble names sorted lexicographically (as in sort(cfg.data.ensembles)).

Notes

Internally calls flatten_trace_blocks which concatenates all prefixes (except "Y_info"), appends a placeholder 5th component when needed for both rescaled and un-rescaled traces, and sorts rows by configuration number.
Missing or malformed inputs are reported via Deborah.Sarah.JobLoggerTools.error_benji / Deborah.Sarah.JobLoggerTools.warn_benji in the upstream loader/flattening routines.

source

Deborah.Miriam.EnsembleUtils.dS — Method

dS(
    ens::Ensemble.EnsembleStruct{T}, 
    paramT::Ensemble.Params{T}, 
    i::Int
) -> T

Compute the total action shift $\Delta S$ between an ensemble configuration and a target parameter set. Currently only includes the fermionic part dSf, which may involve mass ($\kappa$) reweighting.

Arguments

ens::Ensemble.EnsembleStruct{T}: Source ensemble with original parameters and trace data
paramT::Ensemble.Params{T}: Target parameters (includes kappa)
i::Int: Gauge configuration index.

Returns

T: Total action difference $\Delta S$ (currently equal to dSf)

source

Deborah.Miriam.EnsembleUtils.dSf — Method

dSf(
    ens::Ensemble.EnsembleStruct{T}, 
    cswT::T, 
    kappaT::T, 
    i::Int
) -> T

Compute the fermionic action shift from mass reweighting only. Currently ignores clover term variation (cswT) and delegates to dSf_m.

Arguments

ens::Ensemble.EnsembleStruct{T}: Ensemble data containing trace moments trMi
cswT::T: Target clover coefficient (unused)
kappaT::T: Target hopping parameter
i::Int: Gauge configuration index.

Returns

dSf_m: Estimated shift in fermionic action from mass difference only

source

Deborah.Miriam.EnsembleUtils.dSf_m — Method

dSf_m(
    ens::Ensemble.EnsembleStruct{T}, 
    kappaT::T, 
    i::Int
) -> T

Compute the derivative of the fermion action $S_f$ with respect to the mass parameter $m$, expanded around the original $\kappa$ in the ensemble and evaluated at a target $\kappa$.

Arguments

ens::Ensemble.EnsembleStruct{T}: Ensemble containing trace moments trMi
kappaT::T: Target hopping parameter ($\kappa$) for reweighting
i::Int: Gauge configuration index.

Returns

T: Estimated value of $\Delta S_f$ for gauge configuration index i

Notes

Fermion Action Shift via Mass Taylor Expansion

Evaluates the mass-dependent shift in the fermion action $\Delta S_f$, expanded around the original $\kappa$ of the ensemble and evaluated at a target $\kappa$.

Mass Shift

The hopping-mass shift is defined as:

\[\delta m = \frac{1}{2} \left( \frac{1}{\kappa} - \frac{1}{\kappa_{\text{target}}} \right)\]

Taylor Expansion of Fermion Action

The action shift is approximated by:

\[\Delta S_f (\kappa_{\text{target}}) \approx \frac{(\delta m)^1}{1} \left[\text{Tr}\,M^{-1}\right]\left(\kappa\right) + \frac{(\delta m)^2}{2} \left[\text{Tr}\,M^{-2}\right]\left(\kappa\right) + \frac{(\delta m)^3}{3} \left[\text{Tr}\,M^{-3}\right]\left(\kappa\right) + \frac{(\delta m)^4}{4} \left[\text{Tr}\,M^{-4}\right]\left(\kappa\right)\]

Each trace term is obtained from the stored vector ens.trMi[i] in the ensemble:

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

In this context, we assume that all $\text{Tr} \, M^{-n} \; (n=1,2,3,4)$ have already been properly rescaled. (For the rescaling process in Deborah.Miriam, see Deborah.Miriam.MultiEnsembleLoader.generate_trMi_vector or Deborah.Miriam.Cumulants.calc_Q. Note, however, that the rescaling convention in Deborah.Esther is slightly different; to check it, see Deborah.Esther.TraceRescaler.rescale_trace.)

source

Deborah.Miriam.EnsembleUtils.flatten_trace_blocks — Function

flatten_trace_blocks(
    trace_dict::Dict{String, NamedTuple},
    jobid::Union{Nothing, String}=nothing
) -> Tuple{Vector{Vector{Float64}}, Vector{Vector{Float64}}, Vector{UInt8}, Vector{UInt8}, Vector{Int}}

Flatten per-prefix trace blocks into unified arrays (sorted by configuration) suitable for Deborah.Miriam.Ensemble.EnsembleStruct.

Arguments

trace_dict::Dict{String, NamedTuple}: Mapping from trace prefix (e.g., "Y_tr", "Y_bc", "Y_ul", "YP_bc", "YP_ul"; "Y_info" is ignored) to a NamedTuple with fields:
- .values::Vector{Vector{Float64}} — per-configuration rescaled trace vectors (length 4 or 5).
- .values_raw::Vector{Vector{Float64}} — per-configuration un-rescaled raw trace vectors (length 4 or 5).
- .conf_nums::Vector{Int} — per-configuration IDs.
jobid::Union{Nothing, String}: Optional job ID for logging.

Returns

Vector{Vector{Float64}} (trMi): Flattened rescaled trace rows (each of length 5). If an input row has length 4, a placeholder fifth component is appended as val[1]^5 (do not use this placeholder as a physical observable).
Vector{Vector{Float64}} (trMi_raw): Flattened un-rescaled raw trace rows (each of length 5). If an input row has length 4, a placeholder fifth component is appended as val_raw[1]^5.
Vector{UInt8} (source_tags): Fine-grained source code per row
- 0 → "Y_tr"
- 1 → "Y_bc", "YP_bc"
- 2 → "Y_ul", "YP_ul"
Vector{UInt8} (secondary_tags): Coarse class tag per row
- 0 → "Y_lb" (originated from "Y_tr", "Y_bc", "YP_bc")
- 1 → "Y_ul" (originated from "Y_ul", "YP_ul")
Vector{Int} (conf_nums): Configuration numbers aligned with the outputs; rows are globally sorted by configuration.

Notes

Concatenates all prefixes present in trace_dict except "Y_info", then sorts by configuration number.
Replacement prefixes ("YP_*") map to the same source/secondary classes as their non-replacement counterparts.
.values, .values_raw, and .conf_nums must have equal lengths per prefix; mismatches and unknown prefixes raise errors via Deborah.Sarah.JobLoggerTools.error_benji.

source

Deborah.Miriam.EnsembleUtils.secondary_source_to_tag — Function

secondary_source_to_tag(
    prefix::String,
    jobid::Union{Nothing, String}=nothing
) -> UInt8

Map a trace prefix to a secondary class tag used for coarse grouping.

Arguments

prefix::String: Trace data prefix (e.g., "Y_tr", "Y_bc", "YP_ul").
jobid::Union{Nothing, String}: Optional job ID for logging.

Returns

UInt8: Encoded secondary tag
- 0 → "Y_lb" (for "Y_tr", "Y_bc", "YP_bc")
- 1 → "Y_ul" (for "Y_ul", "YP_ul")

Throws

Raises an error via Deborah.Sarah.JobLoggerTools.error_benji if prefix is unknown.

source

Deborah.Miriam.EnsembleUtils.source_to_tag — Function

source_to_tag(
    prefix::String,
    jobid::Union{Nothing, String}=nothing
) -> UInt8

Map a trace prefix string to its source tag (compact UInt8 code).

Arguments

prefix::String: Trace data prefix (e.g., "Y_tr", "Y_bc", "YP_ul").
jobid::Union{Nothing, String}: Optional job ID for logging.

Returns

UInt8: Encoded source tag
- 0 → "Y_tr"
- 1 → "Y_bc", "YP_bc"
- 2 → "Y_ul", "YP_ul"

Throws

Raises an error via Deborah.Sarah.JobLoggerTools.error_benji if prefix is unknown.

Notes

Replacement prefixes ("YP_bc", "YP_ul") are mapped to the same source classes as their non-replacement counterparts.

source

Deborah.Miriam.EnsembleUtils.trMiT — Method

trMiT(
    ens::Ensemble.EnsembleStruct{T}, 
    paramT::Ensemble.Params{T}, 
    i::Int
) -> Vector{T}

Evaluate the trace moment trMi at index i, reweighted to a different $\kappa$ value.

Arguments

ens::Ensemble.EnsembleStruct{T}: Original ensemble containing trace moments
paramT::Ensemble.Params{T}: Target parameter with new $\kappa$ value
i::Int: Gauge configuration index

Returns

Vector{T}: Reweighted trace moment vector of same length as ens.trMi[i]

Notes

Trace Moment Shift via Taylor Expansion

Evaluates the trace moment vector ens.trMi[i] at a shifted $\kappa$ value using a 4th-order Taylor expansion in the hopping mass.

Input Format

Each original trace moment is assumed to be of the form:

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

Here, the first entry is the rescaling factor, and the remaining entries represent trace moments of the inverse Dirac operator raised to powers 1 through 4.

Mass Shift

The mass shift is defined by:

\[\delta m = \frac{1}{2} \left( \frac{1}{\kappa} - \frac{1}{\kappa_{\text{target}}} \right)\]

Shifted Output

The reweighted trace moments are computed via:

\[\begin{aligned} \texttt{ret[1]} &= 12 N_f V \\ \texttt{ret[2]} &= \left[\text{Tr}\,M^{-1}\right]\left(\kappa_{\text{target}}\right)=\left[\text{Tr}\,M^{-1}\right]\left(\kappa\right)+\delta m\;\left[\text{Tr}\,M^{-2}\right]\left(\kappa\right)+\left(\delta m\right)^{2}\;\left[\text{Tr}\,M^{-3}\right]\left(\kappa\right)+\left(\delta m\right)^{3}\;\left[\text{Tr}\,M^{-4}\right]\left(\kappa\right)\\ \texttt{ret[3]} &= \left[\text{Tr}\,M^{-2}\right]\left(\kappa_{\text{target}}\right)=\left[\text{Tr}\,M^{-2}\right]\left(\kappa\right)+2\;\left(\delta m\right)\;\left[\text{Tr}\,M^{-3}\right]\left(\kappa\right)+3\;\left(\delta m\right)^{2}\;\left[\text{Tr}\,M^{-4}\right]\left(\kappa\right)\\ \texttt{ret[4]} &= \left[\text{Tr}\,M^{-3}\right]\left(\kappa_{\text{target}}\right)=\left[\text{Tr}\,M^{-3}\right]\left(\kappa\right)+3\;\left(\delta m\right)\;\left[\text{Tr}\,M^{-4}\right]\left(\kappa\right)\\ \texttt{ret[5]} &= \left[\text{Tr}\,M^{-4}\right]\left(\kappa_{\text{target}}\right)=\left[\text{Tr}\,M^{-4}\right]\left(\kappa\right) \end{aligned}\]

This corresponds to a 4th-order Taylor reweighting of trace observables in the hopping parameter $\kappa$.

source

Deborah.Miriam.EnsembleUtils.trMi_rawT — Method

trMi_rawT(
    ens::Ensemble.EnsembleStruct{T},
    paramT::Ensemble.Params{T},
    i::Int
) -> Vector{T}

Utility variant of trMiT that operates on un-rescaled raw trace moments. (For details on un-rescaling, see Deborah.Miriam.MultiEnsembleLoader.generate_trMi_raw_vector; for details on rescaling, see Deborah.Miriam.MultiEnsembleLoader.generate_trMi_vector.)

It reads ens.trMi_raw[i] (typically [1.0, trM1, trM2, trM3, trM4]) and applies the same $\kappa$-shift logic as trMiT. The first entry is preserved as-is.

Arguments

ens::Ensemble.EnsembleStruct{T}: Source ensemble providing ens.trMi_raw[i].
paramT::Ensemble.Params{T}: Target parameters
i::Int: Configuration index into ens.trMi_raw[i].

Returns

Vector{T}: Reweighted raw trace vector with the same length as ens.trMi_raw[i]. The first component is passed through unchanged (commonly $1.0$), and entries $2,3,4,5$ are the raw traces.

Notes

When paramT.kappa == ens.param.kappa, this returns a value-identical copy of ens.trMi_raw[i].
Intended as a lightweight companion to trMiT for pipelines that keep raw (un-rescaled) traces.
See also: trMiT.

source