API Reference

StructureFactorResult

单个动量点处结构因子分析结果的结构体。

字段

• k_point::Tuple{Float64, Float64}: 实际使用的k点坐标
• mean_real::Float64: 实部平均值
• err_real::Float64: 实部误差
• mean_imag::Float64: 虚部平均值
• err_imag::Float64: 虚部误差
• formatted_real::String: 格式化后的实部字符串
• formatted_imag::String: 格式化后的虚部字符串

AFMCorrelationRatio(shift_point::Tuple{<:Real,<:Real}, Q_point::Tuple{<:Real,<:Real}=(0.0, 0.0),
                 filename::String="afm_sf_k.bin", source_file::String="spsm_k.bin", filedir::String=pwd();
                 force_rebuild::Bool=false, startbin::Int=2, endbin::Union{Int,Nothing}=nothing,
                 outlier_mode::Symbol=:dropmaxmin, outlier_param::Real=0,
                 orbital_columns::Vector{Tuple{Int,Int}}=[(3,4), (5,6), (7,8), (9,10)],
                 orbital_labels::Vector{String}=["AA", "BA", "AB", "BB"],
                 auto_digits::Bool=true, k_point_tolerance::Float64=1e-6, verbose::Bool=true)

Calculate the correlation ratio R_{m^2} for antiferromagnetic structure factor, used to quantify disorder-order transitions.

Formula

R{m^2} = 1 - SAFM(Q+δq) / S_AFM(Q) where δq is a small shift in reciprocal space

Parameters

• shift_point: Momentum space shift (δqx, δqy)
• Q_point: Antiferromagnetic vector Q (default: (0.0, 0.0))
• filename: Structure factor file name (default: "afmsfk.bin")
• source_file: Source file to generate structure factor if not exists (default: "spsm_k.bin")
• filedir: File directory (default: current directory)
• force_rebuild: Force rebuild structure factor file even if exists (default: false)
• startbin: Starting bin (default: 2)
• endbin: Ending bin (default: all bins)
• outlier_mode: :dropmaxmin or :iqrfence (default: :dropmaxmin)
• outlier_param: parameter for the selected outlier mode (default: 0, meaning no trimming/fence)
• orbital_columns: Orbital column indices (default: [(3,4), (5,6), (7,8), (9,10)])
• orbital_labels: Orbital labels (default: ["AA", "BA", "AB", "BB"])
• auto_digits: Whether to automatically determine significant digits (default: true)
• k_point_tolerance: Tolerance for matching k-points (default: 1e-6)
• verbose: Whether to output detailed information (default: true)

Returns

A named tuple with the following fields:

• Q_point: Antiferromagnetic vector Q
• shift_point: Momentum space shift (δqx, δqy)
• Q_shifted: Shifted k-point
• S_AFM_Q: Antiferromagnetic structure factor at Q
• err_S_AFM_Q: Error of the antiferromagnetic structure factor at Q
• S_AFM_Q_shifted: Antiferromagnetic structure factor at the shifted point
• err_S_AFM_Q_shifted: Error of the antiferromagnetic structure factor at the shifted point
• correlation_ratio: Calculated correlation ratio
• err_correlation_ratio: Error of the correlation ratio
• formatted_correlation_ratio: Formatted correlation ratio result

Example

# Calculate correlation ratio with (0.25,0) shift
result = AFMCorrelationRatio((0.25, 0.0))
println("Correlation Ratio: $(result.formatted_correlation_ratio)")

AFMStructureFactor(k_point::Tuple{<:Real,<:Real}=(0.0, 0.0), 
                  filename::String="afm_sf_k.bin", filedir::String=pwd();
                  force_rebuild::Bool=false, source_file::String="spsm_k.bin", 
                  startbin::Int=2, endbin::Union{Int,Nothing}=nothing,
                  outlier_mode::Symbol=:dropmaxmin, outlier_param::Real=0,
                  auto_digits::Bool=true, k_point_tolerance::Float64=1e-6, verbose::Bool=true) -> StructureFactorResult

Calculate antiferromagnetic structure factor SAF(L) = [spsmk(0,A,A) + spsmk(0,B,B) - spsmk(0,A,B) - spsm_k(0,B,A)].

The function can use either:

• A pre-processed file (default: "afmsfk.bin") containing the structure factor directly
• A source file (e.g., "spsmk.bin" or "ssk.bin") to generate the structure factor file if it doesn't exist or force_rebuild is true

Parameters

• k_point: Target momentum point, default (0.0, 0.0)
• filename: Target structure factor file name (default: "afmsfk.bin")
• filedir: Directory containing the files (default: current directory)
• force_rebuild: Whether to force rebuild the structure factor file even if it exists (default: false)
• source_file: Source file to generate structure factor if needed (default: "spsm_k.bin")
• startbin: Starting bin for statistics (default: 2)
• endbin: Ending bin for statistics (default: all bins)
• outlier_mode: :dropmaxmin or :iqrfence (default: :dropmaxmin)
• outlier_param: parameter for the selected outlier mode (default: 0, meaning no trimming/fence)
• auto_digits: Whether to automatically determine significant digits (default: true)
• k_point_tolerance: Tolerance for k-point matching (default: 1e-6)
• verbose: Whether to output detailed information (default: true)

Returns

• StructureFactorResult: Structure factor result struct

Examples

# Use existing afm_sf_k.bin file
result = AFMStructureFactor()

# Force rebuild from source file
result = AFMStructureFactor(force_rebuild=true)

# Specify custom filenames
result = AFMStructureFactor(filename="custom_afm_sf.bin", source_file="custom_afm_source.bin", force_rebuild=true)

CDWCorrelationRatio(shift_point::Tuple{<:Real,<:Real}, Q_point::Tuple{<:Real,<:Real}=(0.0, 0.0),
                 filename::String="cdwpair_sf_k.bin", source_file::String="cdwpair_k.bin", filedir::String=pwd();
                 force_rebuild::Bool=false, startbin::Int=2, endbin::Union{Int,Nothing}=nothing,
                 outlier_mode::Symbol=:dropmaxmin, outlier_param::Real=0,
                 orbital_columns::Vector{Tuple{Int,Int}}=[(3,4), (5,6), (7,8), (9,10)],
                 orbital_labels::Vector{String}=["AA", "BA", "AB", "BB"],
                 auto_digits::Bool=true, k_point_tolerance::Float64=1e-6, verbose::Bool=true)

Calculate the correlation ratio R_{m^2} for charge density wave structure factor, used to quantify disorder-order transitions.

Formula

R{m^2} = 1 - SCDW(Q+δq) / S_CDW(Q) where δq is a small shift in reciprocal space

Parameters

• shift_point: Momentum space shift (δqx, δqy)
• Q_point: CDW ordering vector Q (default: (0.0, 0.0))
• filename: Structure factor file name (default: "cdwpairsfk.bin")
• source_file: Source file to generate structure factor if not exists (default: "cdwpair_k.bin")
• filedir: File directory (default: current directory)
• force_rebuild: Force rebuild structure factor file even if exists (default: false)
• startbin: Starting bin (default: 2)
• endbin: Ending bin (default: all bins)
• outlier_mode: :dropmaxmin or :iqrfence (default: :dropmaxmin)
• outlier_param: parameter for the selected outlier mode (default: 0, meaning no trimming/fence)
• orbital_columns: Orbital column indices (default: [(3,4), (5,6), (7,8), (9,10)])
• orbital_labels: Orbital labels (default: ["AA", "BA", "AB", "BB"])
• auto_digits: Whether to automatically determine significant digits (default: true)
• k_point_tolerance: Tolerance for matching k-points (default: 1e-6)
• verbose: Whether to output detailed information (default: true)

Returns

A named tuple with the following fields:

• Q_point: CDW ordering vector Q
• shift_point: Momentum space shift (δqx, δqy)
• Q_shifted: Shifted k-point
• S_CDW_Q: CDW structure factor at Q
• err_S_CDW_Q: Error of the CDW structure factor at Q
• S_CDW_Q_shifted: CDW structure factor at the shifted point
• err_S_CDW_Q_shifted: Error of the CDW structure factor at the shifted point
• correlation_ratio: Calculated correlation ratio
• err_correlation_ratio: Error of the correlation ratio
• formatted_correlation_ratio: Formatted correlation ratio result

Example

# Calculate correlation ratio with (0.25,0) shift
result = CDWCorrelationRatio((0.25, 0.0))
println("Correlation Ratio: $(result.formatted_correlation_ratio)")

CDWStructureFactor(k_point::Tuple{<:Real,<:Real}=(0.0, 0.0), 
                  filename::String="cdwpair_sf_k.bin", filedir::String=pwd();
                  force_rebuild::Bool=false, source_file::String="cdwpair_k.bin", 
                  startbin::Int=2, endbin::Union{Int,Nothing}=nothing,
                  outlier_mode::Symbol=:dropmaxmin, outlier_param::Real=0,
                  auto_digits::Bool=true, k_point_tolerance::Float64=1e-6, verbose::Bool=true) -> StructureFactorResult

Calculate charge density wave structure factor SCDW(L) = [cdwpairk(0,A,A) + cdwpairk(0,B,B) + cdwpairk(0,A,B) + cdwpair_k(0,B,A)].

The function can use either:

• A pre-processed file (default: "cdwpairsfk.bin") containing the structure factor directly
• A source file (e.g., "cdwpairk.bin") to generate the structure factor file if it doesn't exist or `forcerebuild` is true

Parameters

• k_point: Target momentum point, default (0.0, 0.0)
• filename: Target structure factor file name (default: "cdwpairsfk.bin")
• filedir: Directory containing the files (default: current directory)
• force_rebuild: Whether to force rebuild the structure factor file even if it exists (default: false)
• source_file: Source file to generate structure factor if needed (default: "cdwpair_k.bin")
• startbin: Starting bin for statistics (default: 2)
• endbin: Ending bin for statistics (default: all bins)
• outlier_mode: :dropmaxmin or :iqrfence (default: :dropmaxmin)
• outlier_param: parameter for the selected outlier mode (default: 0, meaning no trimming/fence)
• auto_digits: Whether to automatically determine significant digits (default: true)
• k_point_tolerance: Tolerance for k-point matching (default: 1e-6)
• verbose: Whether to output detailed information (default: true)

Returns

• StructureFactorResult: Structure factor result struct

Examples

# Use existing cdwpair_sf_k.bin file
result = CDWStructureFactor()

# Force rebuild from source file
result = CDWStructureFactor(force_rebuild=true)

# Specify custom filenames
result = CDWStructureFactor(filename="custom_cdw_sf.bin", source_file="custom_cdw.bin", force_rebuild=true)

CorrelationAnalysis(filename="spsm_r.bin", filedir=pwd();
                   startbin=2, endbin=nothing, dropmaxmin=0,
                   real_column=3, imag_column=4,
                   auto_digits=true,
                   verbose=true)

Analyze correlation function data files like spsm_r.bin or nn_r.bin, where the first two columns represent imj coordinates (distance vector between points i and j), and calculate Monte Carlo averages.

Arguments:

• filename: Name of the correlation file (default: "spsm_r.bin")
• filedir: Directory containing the file (default: current directory)
• startbin: First bin to include in analysis (default: 2)
• endbin: Last bin to include in analysis (default: all bins)
• dropmaxmin: Number of maximum and minimum values to drop (default: 0)
• real_column: Column index containing the real part of correlation values (default: 3)
• imag_column: Column index containing the imaginary part of correlation values (default: 4)
• auto_digits: Whether to automatically determine significant digits based on error of error (default: true)
• verbose: Whether to print results to console (default: true)

Returns:

• DataFrame containing the following columns:
  • coord: Tuple of (i,j) coordinates
  • imj_x, imj_y: x and y components of the distance vector
  • mean_real, mean_imag: Mean values of real and imaginary parts
  • err_real, err_imag: Errors of real and imaginary parts
  • formatted_real, formatted_imag: Formatted strings of values with errors
  • distance: Euclidean distance from origin
  • i_coord: coordinates of unit cell i relative to j = (1,1)

Example:

# Analyze spsm_r.bin in current directory
results = CorrelationAnalysis()

# Analyze nn_r.bin with custom columns
results = CorrelationAnalysis("nn_r.bin", real_column=3, imag_column=4)

# Access results
real_part = results[1, :mean_real]      # mean of real part
imag_part = results[1, :mean_imag]      # mean of imaginary part
real_err = results[1, :err_real]        # error of real part
imag_err = results[1, :err_imag]        # error of imaginary part

# Get coordinates and values
for row in eachrow(results)
    coord = row.coord
    real_val = row.mean_real
    imag_val = row.mean_imag
    real_e = row.err_real
    imag_e = row.err_imag
    # Format as complex number for display
    complex_val = "($real_val ± $real_e) + ($imag_val ± $imag_e)im"
    println("At $coord: $complex_val")
end

EnergyAnalysis(filename="energy.bin", filedir=pwd();
               startbin=2, endbin=nothing, outlier_mode=:dropmaxmin, outlier_param=0,
               columns=[5,7,9], labels=["E_kin", "d_occ", "E_tot"],
               verbose=true)

Analyze energy.bin file and calculate Monte Carlo averages and errors for specified columns.

Arguments

• filename: Name of the energy file (default: "energy.bin")
• filedir: Directory containing the file (default: current directory)
• startbin: First bin to include in analysis (default: 2)
• endbin: Last bin to include in analysis, inclusive (default: all bins)
• outlier_mode: :dropmaxmin (trim extremes) or :iqrfence (Tukey IQR fence).
• outlier_param: For :dropmaxmin, number of max/min values to trim (integer, default 0). For :iqrfence, positive Real k multiplier for IQR.
• columns: Array of column indices to analyze (default: [5,7,9])
• labels: Array of labels for the columns (default: ["Ekin", "docc", "E_tot"])
• verbose: Whether to print results to console (default: true)

Returns

• Dictionary with column labels as keys and [mean, error] arrays as values

Example

# Analyze energy.bin in current directory
results = EnergyAnalysis()

# Analyze specific columns with custom labels
results = EnergyAnalysis(columns=[5,7], labels=["Kinetic", "Potential"])

# Use IQR fence instead of trim
results = EnergyAnalysis(outlier_mode=:iqrfence, outlier_param=10.0)

# Access results
kinetic_energy = results["Kinetic"][1]  # mean value
kinetic_error = results["Kinetic"][2]   # error

KSpaceCorrelationAnalysis(filename="nn_k.bin", filedir=pwd();
                         startbin=2, endbin=nothing, dropmaxmin=0,
                         real_column=3, imag_column=4,
                         auto_digits=true,
                         verbose=true)

Analyze k-space correlation function data files like nn_k.bin or spsm_k.bin, where the first two columns represent k-space coordinates, and calculate Monte Carlo averages.

Arguments:

• filename: Name of the correlation file (default: "nn_k.bin")
• filedir: Directory containing the file (default: current directory)
• startbin: First bin to include in analysis (default: 2)
• endbin: Last bin to include in analysis (default: all bins)
• dropmaxmin: Number of maximum and minimum values to drop (default: 0)
• real_column: Column index containing the real part of correlation values (default: 3)
• imag_column: Column index containing the imaginary part of correlation values (default: 4)
• auto_digits: Whether to automatically determine significant digits based on error of error (default: true)
• verbose: Whether to print results to console (default: true)

Returns:

• DataFrame containing the following columns:
  • coord: Tuple of k-point coordinates
  • kx, ky: x and y components of the k-point
  • mean_real, mean_imag: Mean values of real and imaginary parts
  • err_real, err_imag: Errors of real and imaginary parts
  • formatted_real, formatted_imag: Formatted strings of values with errors
  • k_magnitude: Magnitude of the k-point

Example:

# Analyze nn_k.bin in current directory
results = KSpaceCorrelationAnalysis()

# Analyze spsm_k.bin with custom columns
results = KSpaceCorrelationAnalysis("spsm_k.bin", real_column=3, imag_column=4)

# Access results
real_part = results[1, :mean_real]      # mean of real part
imag_part = results[1, :mean_imag]      # mean of imaginary part
real_err = results[1, :err_real]        # error of real part
imag_err = results[1, :err_imag]        # error of imaginary part

# Get coordinates and values
for row in eachrow(results)
    coord = row.coord
    real_val = row.mean_real
    imag_val = row.mean_imag
    real_e = row.err_real
    imag_e = row.err_imag
    # Format as complex number for display
    complex_val = "($real_val ± $real_e) + ($imag_val ± $imag_e)im"
    println("At $coord: $complex_val")
end

MultiOrbitalCorrelationAnalysis(filename="nn_r.bin", filedir=pwd();
                              startbin=2, endbin=nothing, dropmaxmin=0,
                              orbital_columns=[(3,4), (5,6), (7,8), (9,10)],
                              orbital_labels=["AA", "BA", "AB", "BB"],
                              auto_digits=true,
                              verbose=true)

Analyze multi-orbital correlation function data files, where each orbital pair has its own real and imaginary columns.

Arguments:

• filename: Name of the correlation file (default: "nn_r.bin")
• filedir: Directory containing the file (default: current directory)
• startbin: First bin to include in analysis (default: 2)
• endbin: Last bin to include in analysis (default: all bins)
• dropmaxmin: Number of maximum and minimum values to drop (default: 0)
• orbital_columns: Array of (realcolumn, imagcolumn) tuples for each orbital (default: [(3,4), (5,6), (7,8), (9,10)])
• orbital_labels: Array of labels for each orbital (default: ["AA", "BA", "AB", "BB"])
• auto_digits: Whether to automatically determine significant digits based on error of error (default: true)
• verbose: Whether to print results to console (default: true)

Returns:

• DataFrame containing statistics for each coordinate and orbital

Example:

# Analyze nn_r.bin in current directory with default orbital columns
results = MultiOrbitalCorrelationAnalysis()

# Access results
corr_1_1_AA_real = results[1, :AA_mean_real]  # mean real value at first row for AA orbital
corr_1_1_AB_imag = results[1, :AB_mean_imag]  # mean imag value at first row for AB orbital

MultiOrbitalKSpaceCorrelationAnalysis(filename="nn_k.bin", filedir=pwd();
                                    startbin=2, endbin=nothing, dropmaxmin=0,
                                    orbital_columns=[(3,4), (5,6), (7,8), (9,10)],
                                    orbital_labels=["AA", "BA", "AB", "BB"],
                                    auto_digits=true,
                                    verbose=true)

Analyze multi-orbital k-space correlation function data files, where each orbital pair has its own real and imaginary columns.

Arguments:

• filename: Name of the correlation file (default: "nn_k.bin")
• filedir: Directory containing the file (default: current directory)
• startbin: First bin to include in analysis (default: 2)
• endbin: Last bin to include in analysis (default: all bins)
• dropmaxmin: Number of maximum and minimum values to drop (default: 0)
• orbital_columns: Array of (realcolumn, imagcolumn) tuples for each orbital (default: [(3,4), (5,6), (7,8), (9,10)])
• orbital_labels: Array of labels for each orbital (default: ["AA", "BA", "AB", "BB"])
• auto_digits: Whether to automatically determine significant digits based on error of error (default: true)
• verbose: Whether to print results to console (default: true)

Returns:

• DataFrame containing statistics for each coordinate and orbital

Example:

# Analyze nn_k.bin in current directory with default orbital columns
results = MultiOrbitalKSpaceCorrelationAnalysis()

# Access results
corr_1_1_AA_real = results[1, :AA_mean_real]  # mean real value at first row for AA orbital
corr_1_1_AB_imag = results[1, :AB_mean_imag]  # mean imag value at first row for AB orbital

RenyiNegativity(filename, filedir=pwd(); printLA=nothing, startbin=3, endbin=nothing,
                outlier_mode=:dropmaxmin, outlier_param=1, verbose=true)

Calculate Renyi negativity from expRenyiN*.bin files.

Arguments

• filename: Name of the Renyi negativity file (e.g., "expRenyiN3.bin")
• filedir: Directory containing the file (default: current directory)
• printLA: Which LA values to print (default: all)
• startbin: First bin to include (default: 3)
• endbin: Last bin to include, inclusive (default: all bins)
• outlier_mode: :dropmaxmin (trim extremes) or :iqrfence (Tukey IQR fence).
• outlier_param: For :dropmaxmin, number of max/min values to trim (integer, default 1). For :iqrfence, positive Real k multiplier for IQR.
• verbose: When true, prints IQR fence outlier summary per LA (only for :iqrfence).

Returns

• (expRenyiN, RenyiN): Arrays of shape (L+1, 2) with [mean, error] for each LA.

StructureFactorAnalysis(k_points::Vector{<:Tuple{<:Real,<:Real}}, 
                       filename::String="spsm_k.bin", filedir::String=pwd();
                       startbin::Int=2, endbin::Union{Int,Nothing}=nothing,
                       outlier_mode::Symbol=:dropmaxmin, outlier_param::Real=0,
                       real_column::Int=3, imag_column::Int=4,
                       auto_digits::Bool=true, k_point_tolerance::Float64=1e-6, 
                       verbose::Bool=true) -> Vector{StructureFactorResult}

从k空间关联函数数据中提取多个动量点的结构因子（一次读文件，高效处理）。

参数

• k_points: 目标动量点列表，格式为 [(kx1, ky1), (kx2, ky2), ...]
• filename: 关联函数文件名 (默认: "spsm_k.bin")
• filedir: 文件目录 (默认: 当前目录)
• startbin: 起始bin (默认: 2)
• endbin: 结束bin (默认: 所有bin)
• outlier_mode: :dropmaxmin 或 :iqrfence（默认 :dropmaxmin）
• outlier_param: 对应模式的参数（默认 0，表示不做离群过滤）
• real_column: 实部列索引 (默认: 3)
• imag_column: 虚部列索引 (默认: 4)
• auto_digits: 是否自动确定有效数字 (默认: true)
• k_point_tolerance: k点匹配容差 (默认: 1e-6)
• verbose: 是否输出详细信息 (默认: true)

返回值

• Vector{StructureFactorResult}: 结构因子结果数组

示例

# 分析多个k点
k_list = [(π, π), (0.0, 0.0), (π, 0.0)]
results = StructureFactorAnalysis(k_list, "spsm_k.bin")
for r in results
    println("k = $(r.k_point): $(r.formatted_real)")
end

StructureFactorAnalysis(k_point::Tuple{<:Real,<:Real}, 
                       filename::String="spsm_k.bin", filedir::String=pwd();
                       startbin::Int=2, endbin::Union{Int,Nothing}=nothing,
                       outlier_mode::Symbol=:dropmaxmin, outlier_param::Real=0,
                       real_column::Int=3, imag_column::Int=4,
                       auto_digits::Bool=true, k_point_tolerance::Float64=1e-6, 
                       verbose::Bool=true) -> StructureFactorResult

从k空间关联函数数据中提取单个动量点的结构因子（调用多k点版本，保持兼容性）。

参数

• k_point: 目标动量点，格式为 (kx, ky) 的元组
• 其他参数同多k点版本

返回值

• StructureFactorResult: 结构因子结果结构体

示例

# 分析单个k点
result = StructureFactorAnalysis((π, π), "spsm_k.bin")
println("Real part: $(result.mean_real) ± $(result.err_real)")
println("Imag part: $(result.mean_imag) ± $(result.err_imag)")

创建结果行并填充数据

初始化结果 DataFrame 的列结构

_multi_k_structure_factor_analysis_core(k_points, filename, filedir;
                                       startbin, endbin, dropmaxmin,
                                       real_column, imag_column,
                                       auto_digits, k_point_tolerance, verbose) -> Vector{StructureFactorResult}

核心实现：一次读文件，处理多个k点。这是内部函数，不对外导出。

将参数向量转换为字典（包含 :prefix）

afm_k_files_generation(dir::AbstractString; afm_source::String="ss_k.bin", verbose::Bool=true)

重新生成目录中所有与反铁磁相关的衍生数据文件。

参数

• dir::AbstractString: 数据目录，默认为当前工作目录
• afm_source::String: 用于生成反铁磁结构因子的源文件名，默认为"ss_k.bin"
• verbose::Bool: 是否输出详细信息，默认为true

返回值

• Dict{String, String}: 包含生成的文件路径的字典，键为文件名，值为完整路径

示例

# 使用默认设置重新生成AFM相关文件
files = afm_k_files_generation()

# 指定目录和数据源文件
files = afm_k_files_generation("/path/to/data", afm_source="custom_source.bin", verbose=true)

analyze_AFM_correlation_ratio_multi_parameter(base_dir::AbstractString=pwd();
                                           shift_point::Tuple{<:Real,<:Real}=(0.25, 0.0),
                                           Q_point::Tuple{<:Real,<:Real}=(0.0, 0.0),
                                           filename::String="afm_sf_k.bin",
                                           source_file::String="spsm_k.bin",
                                           force_rebuild::Bool=false,
                                           startbin::Int=2,
                                           endbin::Union{Int,Nothing}=nothing,
                                           outlier_mode::Symbol=:dropmaxmin,
                                           outlier_param::Real=0,
                                           auto_digits::Bool=true,
                                           k_point_tolerance::Float64=1e-6,
                                           verbose::Bool=false,
                                           filter_options::Union{Dict, NamedTuple}=Dict()) -> DataFrame

Analyze AFM correlation ratio across multiple parameter directories.

Parameters

• base_dir::AbstractString: Base directory containing parameter directories (default: current directory)
• shift_point::Tuple{<:Real,<:Real}: Momentum space shift (δqx, δqy) (default: (0.25, 0.0))
• Q_point::Tuple{<:Real,<:Real}: AFM ordering vector Q (default: (0.0, 0.0))
• filename::String: Structure factor file name (default: "afmsfk.bin")
• source_file::String: Source file to generate structure factor if not exists (default: "spsm_k.bin")
• force_rebuild::Bool: Force rebuild structure factor file even if exists (default: false)
• startbin::Int: Starting bin for analysis (default: 2)
• endbin::Union{Int,Nothing}: Ending bin for analysis (default: all bins)
• outlier_mode::Symbol: :dropmaxmin or :iqrfence (default: :dropmaxmin)
• outlier_param::Real: parameter for the selected outlier mode (default: 0 = no filtering)
• auto_digits::Bool: Whether to automatically determine significant digits (default: true)
• k_point_tolerance::Float64: Tolerance for matching k-points (default: 1e-6)
• verbose::Bool: Whether to output detailed information (default: false)
• filter_options::Union{Dict, NamedTuple}: Options for filtering parameter directories (default: empty Dict)

Returns

• DataFrame: DataFrame containing parameters and AFM correlation ratio results

analyze_AFM_structure_factor_multi_parameter(base_dir::AbstractString=pwd(); 
                                           k_point::Tuple{<:Real,<:Real}=(0.0, 0.0),
                                           filename::String="afm_sf_k.bin",
                                           force_rebuild::Bool=false,
                                           source_file::String="spsm_k.bin",
                                           startbin::Int=2, 
                                           endbin::Union{Int,Nothing}=nothing, 
                                           outlier_mode::Symbol=:dropmaxmin,
                                           outlier_param::Real=0,
                                           auto_digits::Bool=true, 
                                           k_point_tolerance::Float64=1e-6, 
                                           verbose::Bool=false,
                                           filter_options::Union{Dict, NamedTuple}=Dict()) -> DataFrame

对多个参数目录执行反铁磁结构因子分析，并将结果整合到一个DataFrame中。

仅支持单 k 点分析。

参数

• base_dir::AbstractString=pwd(): 基础目录路径，默认为当前工作目录
• k_point::Tuple{<:Real,<:Real}=(0.0, 0.0): 要分析的k点
• filename::String="afm_sf_k.bin": 要分析的结构因子文件名
• force_rebuild::Bool=false: 是否强制重新构建结构因子文件
• source_file::String="spsm_k.bin": 当 filename 不存在时，用于生成结构因子的源文件名
• startbin::Int=2: 起始bin编号
• endbin::Union{Int,Nothing}=nothing: 结束bin编号
• outlier_mode::Symbol=:dropmaxmin: 离群过滤模式（:dropmaxmin / :iqrfence）
• outlier_param::Real=0: 对应模式的参数（0 表示不做过滤）
• auto_digits::Bool=true: 是否自动确定有效数字
• k_point_tolerance::Float64=1e-6: k点匹配容差
• verbose::Bool=false: 是否显示详细信息
• filter_options::Union{Dict, NamedTuple}=Dict(): 目录筛选选项，可包含:prefix、:b、:U等参数

返回值

• DataFrame: 包含所有参数和分析结果的DataFrame

analyze_CDW_correlation_ratio_multi_parameter(base_dir::AbstractString=pwd();
                                           shift_point::Tuple{<:Real,<:Real}=(0.25, 0.0),
                                           Q_point::Tuple{<:Real,<:Real}=(0.0, 0.0),
                                           filename::String="cdwpair_sf_k.bin",
                                           source_file::String="cdwpair_k.bin",
                                           force_rebuild::Bool=false,
                                           startbin::Int=2,
                                           endbin::Union{Int,Nothing}=nothing,
                                           outlier_mode::Symbol=:dropmaxmin,
                                           outlier_param::Real=0,
                                           auto_digits::Bool=true,
                                           k_point_tolerance::Float64=1e-6,
                                           verbose::Bool=false,
                                           filter_options::Union{Dict, NamedTuple}=Dict(),
                                           pattern::Regex=r"^proj_fft_honeycomb") -> DataFrame

Analyze CDW correlation ratio across multiple parameter directories.

Parameters

• base_dir::AbstractString: Base directory containing parameter directories (default: current directory)
• shift_point::Tuple{<:Real,<:Real}: Momentum space shift (δqx, δqy) (default: (0.25, 0.0))
• Q_point::Tuple{<:Real,<:Real}: CDW ordering vector Q (default: (0.0, 0.0))
• filename::String: Structure factor file name (default: "cdwpairsfk.bin")
• source_file::String: Source file to generate structure factor if not exists (default: "cdwpair_k.bin")
• force_rebuild::Bool: Force rebuild structure factor file even if exists (default: false)
• startbin::Int: Starting bin for analysis (default: 2)
• endbin::Union{Int,Nothing}: Ending bin for analysis (default: all bins)
• outlier_mode::Symbol: :dropmaxmin or :iqrfence (default: :dropmaxmin)
• outlier_param::Real: parameter for the selected outlier mode (default: 0 = no filtering)
• auto_digits::Bool: Whether to automatically determine significant digits (default: true)
• k_point_tolerance::Float64: Tolerance for matching k-points (default: 1e-6)
• verbose::Bool: Whether to output detailed information (default: false)
• filter_options::Union{Dict, NamedTuple}: Options for filtering parameter directories (default: empty Dict)

Returns

• DataFrame: DataFrame containing parameters and CDW correlation ratio results

analyze_CDW_structure_factor_multi_parameter(base_dir::AbstractString=pwd(); 
                                           k_point::Tuple{<:Real,<:Real}=(0.0, 0.0),
                                           filename::String="cdwpair_sf_k.bin",
                                           force_rebuild::Bool=false,
                                           source_file::String="cdwpair_k.bin",
                                           startbin::Int=2, 
                                           endbin::Union{Int,Nothing}=nothing, 
                                           outlier_mode::Symbol=:dropmaxmin,
                                           outlier_param::Real=0,
                                           auto_digits::Bool=true, 
                                           k_point_tolerance::Float64=1e-6, 
                                           verbose::Bool=false,
                                           filter_options::Union{Dict, NamedTuple}=Dict()) -> DataFrame

对多个参数目录执行电荷密度波结构因子分析，并将结果整合到一个DataFrame中。

仅支持单 k 点分析。

参数

• base_dir::AbstractString=pwd(): 基础目录路径，默认为当前工作目录
• k_point::Tuple{<:Real,<:Real}=(0.0, 0.0): 要分析的k点
• filename::String="cdwpair_sf_k.bin": 要分析的结构因子文件名
• force_rebuild::Bool=false: 是否强制重新构建结构因子文件
• source_file::String="cdwpair_k.bin": 当 filename 不存在时，用于生成结构因子的源文件名
• startbin::Int=2: 起始bin编号
• endbin::Union{Int,Nothing}=nothing: 结束bin编号
• outlier_mode::Symbol=:dropmaxmin: 离群过滤模式（:dropmaxmin / :iqrfence）
• outlier_param::Real=0: 对应模式的参数（0 表示不做过滤）
• auto_digits::Bool=true: 是否自动确定有效数字
• k_point_tolerance::Float64=1e-6: k点匹配容差
• verbose::Bool=false: 是否显示详细信息
• filter_options::Union{Dict, NamedTuple}=Dict(): 目录筛选选项，可包含:prefix、:b、:U等参数

返回值

• DataFrame: 包含所有参数和分析结果的DataFrame

analyze_correlation_ratio_multi_parameter(correlation_ratio_function::Function,
                                       base_dir::AbstractString=pwd(); 
                                       shift_point::Tuple{<:Real,<:Real}=(0.25, 0.0),
                                       Q_point::Tuple{<:Real,<:Real}=(0.0, 0.0),
                                       filename::String="afm_sf_k.bin",
                                       source_file::String="spsm_k.bin",
                                       result_columns::Vector{Symbol}=[:correlation_ratio, :err_correlation_ratio],
                                       result_prefix::String="R",
                                       force_rebuild::Bool=false,
                                       startbin::Int=2,
                                       endbin::Union{Int,Nothing}=nothing,
                                       outlier_mode::Symbol=:dropmaxmin,
                                       outlier_param::Real=0,
                                       auto_digits::Bool=true,
                                       k_point_tolerance::Float64=1e-6,
                                       verbose::Bool=false,
                                       filter_options::Union{Dict, NamedTuple}=Dict()) -> DataFrame

Generic multi-parameter correlation ratio analysis function, suitable for analyzing different types of correlation ratios.

Parameters

• correlation_ratio_function::Function: Function for analyzing correlation ratio, such as AFMCorrelationRatio or CDWCorrelationRatio
• base_dir::AbstractString: Base directory containing parameter directories (default: current directory)
• shift_point::Tuple{<:Real,<:Real}: Momentum space shift (δqx, δqy) (default: (0.25, 0.0))
• Q_point::Tuple{<:Real,<:Real}: Ordering vector Q (default: (0.0, 0.0))
• filename::String: Structure factor file name (default: "afmsfk.bin")
• source_file::String: Source file to generate structure factor if not exists (default: "spsm_k.bin")
• result_columns::Vector{Symbol}: Columns to include in results (default: [:correlationratio, :errcorrelation_ratio])
• result_prefix::String: Prefix for result column names (default: "R")
• force_rebuild::Bool: Force rebuild structure factor file even if exists (default: false)
• startbin::Int: Starting bin for analysis (default: 2)
• endbin::Union{Int,Nothing}: Ending bin for analysis (default: all bins)
• outlier_mode::Symbol: :dropmaxmin or :iqrfence (default: :dropmaxmin)
• outlier_param::Real: parameter for the selected outlier mode (default: 0 = no filtering)
• auto_digits::Bool: Whether to automatically determine significant digits (default: true)
• k_point_tolerance::Float64: Tolerance for matching k-points (default: 1e-6)
• verbose::Bool: Whether to output detailed information (default: false)
• filter_options::Union{Dict, NamedTuple}: Options for filtering parameter directories (default: empty Dict)

Returns

• DataFrame: DataFrame containing parameters and correlation ratio results

analyze_structure_factor_multi_parameter(analyzer_function::Function,
                                       k_points::Vector{<:Tuple{<:Real,<:Real}},
                                       base_dir::AbstractString=pwd(); 
                                       filename::String="afm_sf_k.bin",
                                       force_rebuild::Bool=false,
                                       source_file::String="spsm_k.bin",
                                       result_columns::Vector{Symbol}=[:mean_real, :err_real, :mean_imag, :err_imag],
                                       result_prefix::String="S",
                                       startbin::Int=2, 
                                       endbin::Union{Int,Nothing}=nothing, 
                                       outlier_mode::Symbol=:dropmaxmin,
                                       outlier_param::Real=0,
                                       auto_digits::Bool=true, 
                                       k_point_tolerance::Float64=1e-6, 
                                       verbose::Bool=false,
                                       filter_options::Union{Dict, NamedTuple}=Dict()) -> DataFrame

通用的多参数结构因子分析函数（多 k 点版本），可用于分析不同类型的结构因子。

返回长表，每个参数目录 × 每个 k 点一行，包含 :kx 和 :ky 列。

参数

• analyzer_function::Function: 用于分析结构因子的函数，必须支持多 k 点输入
• k_points::Vector{<:Tuple{<:Real,<:Real}}: 要分析的k点列表（位置参数）
• base_dir::AbstractString=pwd(): 基础目录路径，默认为当前工作目录
• 其他参数同单 k 点版本

返回值

• DataFrame: 包含所有参数、k点坐标和分析结果的DataFrame（长表） 新增列：:kx, :ky

analyze_structure_factor_multi_parameter(analyzer_function::Function,
                                      k_point::Tuple{<:Real,<:Real},
                                      base_dir::AbstractString=pwd(); 
                                      filename::String="afm_sf_k.bin",
                                      force_rebuild::Bool=false,
                                      source_file::String="spsm_k.bin",
                                      result_columns::Vector{Symbol}=[:mean_real, :err_real, :mean_imag, :err_imag],
                                      result_prefix::String="S",
                                      startbin::Int=2, 
                                      endbin::Union{Int,Nothing}=nothing, 
                                      outlier_mode::Symbol=:dropmaxmin,
                                      outlier_param::Real=0,
                                      auto_digits::Bool=true, 
                                      k_point_tolerance::Float64=1e-6, 
                                      verbose::Bool=false,
                                      filter_options::Union{Dict, NamedTuple}=Dict()) -> DataFrame

通用的多参数结构因子分析函数（单 k 点版本），可用于分析不同类型的结构因子。

返回宽表，每个参数目录一行，不包含 k 点信息列。

参数

• analyzer_function::Function: 用于分析结构因子的函数，如 AFMStructureFactor 或 CDWStructureFactor
• k_point::Tuple{<:Real,<:Real}: 要分析的k点（位置参数）
• base_dir::AbstractString=pwd(): 基础目录路径，默认为当前工作目录
• filename::String="afm_sf_k.bin": 要分析的结构因子文件名
• force_rebuild::Bool=false: 是否强制重新构建结构因子文件
• source_file::String="spsm_k.bin": 当 filename 不存在时，用于生成结构因子的源文件名
• result_columns::Vector{Symbol}: 结果列的名称，默认为 [:meanreal, :errreal, :meanimag, :errimag]
• result_prefix::String: 结果列名称的前缀，如 "SAF" 或 "SCDW"
• startbin::Int=2: 起始bin编号
• endbin::Union{Int,Nothing}=nothing: 结束bin编号
• outlier_mode::Symbol=:dropmaxmin: 离群过滤模式（:dropmaxmin / :iqrfence）
• outlier_param::Real=0: 对应模式的参数（0 表示不做过滤）
• auto_digits::Bool=true: 是否自动确定有效数字
• k_point_tolerance::Float64=1e-6: k点匹配容差
• verbose::Bool=false: 是否显示详细信息
• filter_options::Union{Dict, NamedTuple}=Dict(): 目录筛选选项，可包含:prefix、:b、:U等参数

返回值

• DataFrame: 包含所有参数和分析结果的DataFrame（宽表，每个参数目录一行）

batch_migrate_directories(base_dir::AbstractString=pwd(); 
                         pattern::Regex=r"^proj_fft_honeycomb",
                         dry_run::Bool=true,
                         action::String="mv") -> Vector{Tuple{String,String,Bool}}

批量迁移目录下的legacy格式文件夹名到新格式。

参数

• base_dir::AbstractString=pwd(): 基础目录路径，默认为当前工作目录
• pattern::Regex=r"^proj_fft_honeycomb": 用于匹配需要迁移的目录名的正则表达式
• dry_run::Bool=true: 是否为试运行模式（只显示将要进行的操作，不实际执行）
• action::String="mv": 执行的操作类型
  • "mv": 重命名目录（默认）
  • "cp": 复制目录到新名称，保留原目录
  • "rm": 删除原目录（需要先用"cp"创建新目录）

返回值

• Vector{Tuple{String,String,Bool}}: 迁移结果列表，每个元组包含 (原名, 新名, 是否成功)

示例

# 试运行，查看将要进行的迁移
results = batch_migrate_directories(dry_run=true)

# 复制到新格式，保留原目录
results = batch_migrate_directories(dry_run=false, action="cp")

# 重命名到新格式
results = batch_migrate_directories(dry_run=false, action="mv")

Calculate i coordinate from imj when j is fixed at (1,1)

calculate_statistics(df, auto_digits; input_coord_columns=[:imj_x, :imj_y], output_coord_names=[:imj_x, :imj_y], orbital_labels=nothing)

通用函数，计算DataFrame中每个坐标的统计信息。 该函数可用于实空间和k空间数据，支持单轨道和多轨道数据。

参数:

• df: 包含bin信息的DataFrame
• auto_digits: 是否使用自动精度进行误差计算
• input_coord_columns: 输入DataFrame中提取坐标值的列 (例如, [:imjx, :imjy] 或 [:kx, :ky])
• output_coord_names: 输出DataFrame中使用的坐标列名称
• orbital_labels: 轨道标签数组。如果为nothing，则处理单轨道数据（使用realval和imagval列）

返回:

• 包含每个坐标统计信息的DataFrame

cdwpair_k_files_generation(dir::AbstractString=pwd(); verbose::Bool=true)

生成目录中与电荷密度波和配对相关的衍生数据文件。

参数

• dir::AbstractString: 数据目录，默认为当前工作目录
• verbose::Bool: 是否输出详细信息，默认为true

返回值

• Dict{String, String}: 包含生成的文件路径的字典，键为文件名，值为完整路径

示例

# 使用默认设置生成CDW和配对相关文件
files = cdwpair_k_files_generation()

# 指定目录
files = cdwpair_k_files_generation("/path/to/data", verbose=true)

combine_bin_files(output_filename::String,
                  input_files::Vector{<:Tuple{<:AbstractString, <:Real}},
                  output_dir::String=pwd(),
                  input_dir::String=pwd();
                  preserve_columns::Union{Vector{Int}, UnitRange{Int}}=1:2,
                  operation::Function=+,
                  verbose::Bool=false)

将多个具有类似结构的二进制数据文件按权重组合成一个新文件。

参数

• output_filename::String: 输出文件名
• input_files::Vector{Tuple{String, Real}}: 输入文件名和权重的元组数组，如 [("spsmk.bin", 0.5), ("szszk.bin", 1.0)]
• output_dir::String=pwd(): 输出文件目录
• input_dir::String=pwd(): 输入文件目录
• preserve_columns::Union{Vector{Int}, UnitRange{Int}}=1:2: 保持不变的列索引（默认前两列，通常是坐标）
• operation::Function=+: 组合操作函数（默认为加法）
• verbose::Bool=false: 是否输出详细信息

返回值

• String: 生成的文件完整路径

示例

# 合并 spsm_k.bin 和 szsz_k.bin 文件，权重分别为 0.5 和 1.0
combined_file = combine_bin_files(
    "ss_k.bin",
    [("spsm_k.bin", 1.0), ("szsz_k.bin", 1.0)]
)

# 合并实空间关联函数文件，保持前3列不变
combined_file = combine_bin_files(
    "ss_r.bin", 
    [("spsm_r.bin", 1.0), ("szsz_r.bin", 1.0)],
    preserve_columns=1:3
)

# 使用乘法而不是加法合并文件
combined_file = combine_bin_files(
    "product.bin",
    [("file1.bin", 1.0), ("file2.bin", 1.0)],
    operation=*
)

combine_cdwpair_components(
    cdw_filename::String="cdw_k.bin",
    pair_filename::String="pair_onsite_k.bin",
    output_filename::String="cdwpair_k.bin",
    input_dir::String=pwd(),
    output_dir::String=pwd(),
    cdw_weight::Real=1.0,
    pair_weight::Real=2.0;
    preserve_columns::Union{Vector{Int}, UnitRange{Int}}=1:2,
    verbose::Bool=true
)

将CDW关联和配对关联合并为一个整体结构因子（假设了eta-SU（2）对称性）。 如果CDW关联文件不存在，会自动从密度-密度关联文件创建。

参数

• cdw_filename::String="cdw_k.bin": CDW关联文件名
• pair_filename::String="pair_onsite_k.bin": 配对关联文件名
• output_filename::String="cdwpair_k.bin": 输出文件名
• input_dir::String=pwd(): 输入文件目录
• output_dir::String=pwd(): 输出文件目录
• cdw_weight::Real=1.0: CDW关联的权重（默认为1.0）
• pair_weight::Real=2.0: 配对关联的权重（默认为2.0）
• preserve_columns::Union{Vector{Int}, UnitRange{Int}}=1:2: 保持不变的列索引（默认前两列，通常是k点坐标）
• verbose::Bool=true: 是否输出详细信息

返回值

• String: 生成的文件完整路径

示例

# 合并CDW和配对关联
combined_file = combine_cdwpair_components("cdw_k.bin", "pair_onsite_k.bin", "cdwpair_k.bin")

combine_ss_components(
    spsm_filename::String="spsm_k.bin",
    szsz_filename::String="szsz_k.bin",
    output_filename::String="ss_k.bin",
    input_dir::String=pwd(),
    output_dir::String=pwd(),
    xy_weight::Real=1.0,
    zz_weight::Real=1.0;
    preserve_columns::Union{Vector{Int}, UnitRange{Int}}=1:2,
    verbose::Bool=true
)

合并 XY 和 Z 分量的自旋相关函数数据文件。

参数

• spsm_filename::String="spsm_k.bin": XY分量文件名
• szsz_filename::String="szsz_k.bin": Z分量文件名
• output_filename::String="ss_k.bin": 输出文件名
• input_dir::String=pwd(): 输入文件目录
• output_dir::String=pwd(): 输出文件目录
• xy_weight::Real=1.0: XY分量的权重
• zz_weight::Real=1.0: Z分量的权重
• preserve_columns::Union{Vector{Int}, UnitRange{Int}}=1:2: 保持不变的列索引
• verbose::Bool=true: 是否输出详细信息

返回值

• String: 生成的文件完整路径或者空字符串

示例

# 合并 k 空间的 XY 和 Z 分量
combined_file = combine_ss_components(
    "spsm_k.bin",
    "szsz_k.bin",
    "ss_k.bin"
)

compute_cr_m2_covariance(m2_value, m2_error, cr_value, scaling_factor; return_components=false)

计算相关比（Correlation Ratio）和缩放m²之间的协方差。

数学推导

给定独立测量量：

• A = C(0) = m² （Q点的结构因子）
• B = C(δk) （Q+δq点的结构因子）
• Cov(A, B) = 0 （假设独立测量）

定义：

• K = L^(-(1+η_φ)) （缩放常数）
• y = K·A （缩放后的m²）
• x = 1 - B/A （相关比）

使用误差传播公式：

σ_xy ≈ (∂x/∂A)(∂y/∂A)σ_A² + (∂x/∂B)(∂y/∂B)σ_B²

由于 ∂y/∂B = 0，第二项为零。计算偏导数：

• ∂y/∂A = K
• ∂x/∂A = B/A²

因此：

σ_xy = (B/A²)·K·σ_A² = y·(1-x)·(σ_A/A)²

最终公式：

σ_xy = y·(1-x)·(σ_C(0)/C(0))²

参数

• m2_value::Real: m² = C(0) 的值（Q点的结构因子）
• m2_error::Real: σ_C(0)，m²的误差
• cr_value::Real: x，相关比的值（通常为 1 - C(δk)/C(0)）
• scaling_factor::Real: 例如K = L^(1+η_φ)，缩放因子
• return_components::Bool: 是否返回中间计算值（默认：false）

返回值

如果 return_components=false（默认）：

• (; covariance = σ_xy) - 仅返回协方差值

如果 return_components=true：

• (; covariance, scaled_m2, relative_error_m2) - 返回协方差及中间值

示例

# 基本用法
m2 = 2.0
σ_m2 = 0.1
cr = 0.5
K = 0.8
result = compute_cr_m2_covariance(m2, σ_m2, cr, K)
println("协方差: ", result.covariance)

# 返回中间值用于调试
result = compute_cr_m2_covariance(m2, σ_m2, cr, K; return_components=true)
println("缩放m²: ", result.scaled_m2)
println("相对误差: ", result.relative_error_m2)

参考

• AFMCorrelationRatio: 计算反铁磁相关比
• CDWCorrelationRatio: 计算CDW相关比
• AFMStructureFactor: 计算反铁磁结构因子（m²）

compute_cr_m2_covariance(scaled_m2, scaled_error, cr_value)

计算相关比和缩放m²之间的协方差（简化版，直接使用 scaled 值）。

由于 y = K·A 是线性缩放，相对误差保持不变：σy/y = σA/A 因此可以直接使用 scaled 值计算协方差。

参数

• scaled_m2::Real: Y = K·m²，缩放后的 m² 值
• scaled_error::Real: E = K·σ_m²，缩放后的误差
• cr_value::Real: x，相关比的值

返回值

• (; covariance) - 协方差值 σ_xy

示例

Y = 0.5    # scaled m²
E = 0.02   # scaled error
x = 0.3    # correlation ratio
result = compute_cr_m2_covariance(Y, E, x)
println("协方差: ", result.covariance)

参考

• compute_cr_m2_covariance(m2_value, m2_error, cr_value, scaling_factor): 4参数版本

compute_stats(real_values, imag_values; auto_digits=true)

计算复数数据的统计量（平均值、误差和格式化字符串）。

参数:

• real_values: 实部值数组
• imag_values: 虚部值数组
• auto_digits: 是否自动确定有效数字 (默认: true)

返回:

• 包含以下字段的命名元组:
  • mean_real, mean_imag: 平均值（实部和虚部）
  • err_real, err_imag: 误差（实部和虚部）
  • formatted_real, formatted_imag: 格式化后的结果字符串

create_cdw_from_nn(
    input_filename::String="nn_k.bin",
    output_filename::String="cdw_k.bin",
    input_dir::String=pwd(),
    output_dir::String=pwd();
    preserve_columns::Union{Vector{Int}, UnitRange{Int}}=1:2,
    verbose::Bool=true
)

将密度密度关联数据(nnk.bin)转换为CDW关联数据。 应用ηα ηβ因子到对应的轨道，其中ηα是+1（α=A轨道）或-1（α=B轨道）。

参数

• input_filename::String="nn_k.bin": 输入密度-密度关联文件名
• output_filename::String="cdw_k.bin": 输出文件名
• input_dir::String=pwd(): 输入文件目录
• output_dir::String=pwd(): 输出文件目录
• preserve_columns::Union{Vector{Int}, UnitRange{Int}}=1:2: 保持不变的列索引（默认前两列，通常是k点坐标）
• verbose::Bool=true: 是否输出详细信息

返回值

• String: 生成的文件完整路径

示例

# 创建CDW关联文件
cdw_file = create_cdw_from_nn("nn_k.bin", "cdw_k.bin")

error(data; sigma=1, bessel=true, auto_digits=false)

Calculate the standard error of the data.

Arguments:

• data: The data array
• sigma: Number of standard deviations (default: 1)
• bessel: Whether to use Bessel's correction (N-1) for sample standard deviation (default: true)
• auto_digits: Whether to automatically determine significant digits based on error of error (default: true)

Returns:

• Standard error multiplied by sigma, with appropriate precision if auto_digits=true

Calculate Euclidean distance between two points

export_bin_to_csv(
    input_file::String,
    dir::String=pwd();
    output_dir::Union{String, Nothing}=nothing,
    output_file::Union{String, Nothing}=nothing,
    kwargs...
)

Export a bin file to CSV format.

Arguments

• input_file::String: Input .bin file name
• dir::String=pwd(): Directory containing the bin file
• output_dir::Union{String, Nothing}=nothing: Output directory (defaults to dir/exported_csv)
• output_file::Union{String, Nothing}=nothing: Output filename (defaults to input_file with .csv extension)
• kwargs...: Additional arguments passed to export_bin_to_dataframe

Returns

• String: Path to the exported CSV file

Examples

# Export to default location (data/exported_csv/)
csv_file = export_bin_to_csv("nn_k.bin", dir="data/")

# Export to custom location
csv_file = export_bin_to_csv("nn_k.bin", dir="data/", output_dir="results/")

# Export with custom filename
csv_file = export_bin_to_csv("nn_k.bin", output_file="correlation_nn.csv")

export_bin_to_dataframe(
    input_file::String,
    dir::String=pwd();
    iscorrelation::Bool=true,
    orbital_columns::Union{Vector{Tuple{Int,Int}}, Nothing}=nothing,
    orbital_labels::Union{Vector{String}, Nothing}=nothing
)

Convert a bin file to a DataFrame with bin index column.

This function reads a bin file and converts it to a DataFrame format suitable for analysis and visualization. It automatically detects the file structure (k-space vs r-space) and handles both multi-orbital and single-column data.

Arguments

• input_file::String: Input .bin file name
• dir::String=pwd(): Directory containing the bin file
• iscorrelation::Bool=true: Whether to interpret the file as a correlation function (coordinates + real/imag pairs)
• orbital_columns::Union{Vector{Tuple{Int,Int}}, Nothing}=nothing: Column indices for each orbital pair (real, imag). Auto-generated when nothing
• orbital_labels::Union{Vector{String}, Nothing}=nothing: Labels for each orbital pair (defaults to AA/BA/... or pair1/pair2/...)

Returns

• DataFrame: Converted data with columns: bin, coord1, coord2, data columns...

Data Structure

The function handles multiple formats:

1. Multi-orbital (default 10 columns): kx, ky, AAreal, AAimag, BAreal, BAimag, ABreal, ABimag, BBreal, BBimag
   • Note: AA, AB, BA, BB represent orbital pairs in two-point correlation functions <c†{i,α} c{j,β}>
2. Custom orbital pairs: Specify any number of orbital pairs via orbital_columns and orbital_labels
3. Single column (4 columns): kx, ky, valuereal, valueimag

Examples

# Export k-space correlation function (default 4 orbital pairs: AA, BA, AB, BB)
df = export_bin_to_dataframe("nn_k.bin", dir="data/")

# Export only diagonal orbital pairs (AA and BB)
df = export_bin_to_dataframe("nn_k.bin", 
    orbital_columns=[(3,4), (9,10)],
    orbital_labels=["AA", "BB"])

# Export r-space correlation function
df = export_bin_to_dataframe("nn_r.bin", dir="data/")

# Export AFM structure factor (single column)
df = export_bin_to_dataframe("afm_sf_k.bin", dir="data/", iscorrelation=true, orbital_columns=[(3,4)], orbital_labels=["value"])

export_bin_to_jld2(
    input_file::String,
    dir::String=pwd();
    output_dir::Union{String, Nothing}=nothing,
    output_file::Union{String, Nothing}=nothing,
    dataset_name::Union{String, Nothing}=nothing,
    kwargs...
)

Export a bin file to JLD2 format.

Arguments

• input_file::String: Input .bin file name
• dir::String=pwd(): Directory containing the bin file
• output_dir::Union{String, Nothing}=nothing: Output directory (defaults to dir/exported_jld2)
• output_file::Union{String, Nothing}=nothing: Output filename (defaults to input filename with .jld2 extension, e.g., nn_k.jld2)
• dataset_name::Union{String, Nothing}=nothing: Dataset name in JLD2 file (defaults to base filename, e.g., "nn_k")
• kwargs...: Additional arguments passed to export_bin_to_dataframe

Returns

• String: Path to the exported JLD2 file

Examples

# Export to default JLD2 file (nn_k.jld2 with dataset "nn_k")
jld2_file = export_bin_to_jld2("nn_k.bin", dir="data/")
# Creates: data/exported_jld2/nn_k.jld2 (dataset: "nn_k")
# Read: load("nn_k.jld2", "nn_k")

# Export to custom JLD2 file
jld2_file = export_bin_to_jld2("nn_k.bin", output_file="correlations.jld2")
# Creates: correlations.jld2 (dataset: "nn_k")

# Multiple datasets in one file (if needed)
export_bin_to_jld2("nn_k.bin", output_file="all_data.jld2")  # dataset: "nn_k"
export_bin_to_jld2("nn_r.bin", output_file="all_data.jld2")  # dataset: "nn_r"
# Read: load("all_data.jld2", "nn_k") or load("all_data.jld2", "nn_r")

export_directory_bins(
    dir::String=pwd();
    file_patterns::Vector{String}=["*_k.bin", "*_r.bin"],
    output_format::Symbol=:both,
    output_dir::Union{String, Nothing}=nothing,
    verbose::Bool=true,
    iscorrelation::Union{Bool,Nothing}=nothing,
    orbital_columns::Union{Vector{Tuple{Int,Int}}, Nothing}=nothing,
    orbital_labels::Union{Vector{String}, Nothing}=nothing
)

Batch export all matching bin files in a directory.

Arguments

• dir::String=pwd(): Directory containing bin files
• file_patterns::Vector{String}=["*_k.bin", "*_r.bin"]: Glob patterns for files to export
• output_format::Symbol=:both: Output format (:csv, :jld2, or :both) - default is :both
• output_dir::Union{String, Nothing}=nothing: Output directory
• verbose::Bool=true: Print progress information
• iscorrelation::Union{Bool,Nothing}=nothing: Whether files should be treated as correlation data. nothing enables auto-detection based on filename (contains _k or _r).
• orbital_columns::Union{Vector{Tuple{Int,Int}}, Nothing}=nothing: Optional orbital column mapping passed to export functions (used when iscorrelation is true).
• orbital_labels::Union{Vector{String}, Nothing}=nothing: Optional orbital labels passed to export functions (used when iscorrelation is true).

Returns

• Vector{String}: Paths to exported files

Examples

# Export all k-space and r-space correlation files to both CSV and JLD2 (default)
export_directory_bins("data/")

# Export only to CSV
export_directory_bins("data/", output_format=:csv)

# Export only k-space files
export_directory_bins("data/", file_patterns=["*_k.bin"])

# Export with custom output directory
export_directory_bins("data/", output_dir="results/")

filter_bin_file(
    input_filename::String,
    coordinate::Union{Tuple{Int, Int}, Tuple{Float64, Float64}};
    output_filename::Union{String, Nothing}=nothing,
    dir::String=pwd(),
    k_point_tolerance::Float64=1e-6,
    verbose::Bool=false
)

Extract all bin data for a specific coordinate from a bin file.

This function filters a bin file to extract only the rows corresponding to a specific coordinate across all bins. The coordinate can be either:

• k-space (momentum): Tuple{Float64, Float64}, e.g., (0.5, 0.5)
• r-space (real space): Tuple{Int, Int}, e.g., (1, 2)

Arguments

• input_filename::String: Input .bin file (e.g., "nnk.bin", "nnr.bin")
• coordinate::Union{Tuple{Int, Int}, Tuple{Float64, Float64}}: Target coordinate
• output_filename::Union{String, Nothing}=nothing: Output .bin file name. If nothing, auto-generate from coordinate
• dir::String=pwd(): Working directory
• k_point_tolerance::Float64=1e-6: Tolerance for k-space coordinate matching (ignored for r-space)
• verbose::Bool=false: Whether to print verbose information

Returns

• String: Path to output file, or empty string if failed

Examples

# Filter k-space data for k=(π,π)
filter_bin_file("nn_k.bin", (0.5, 0.5), dir="/path/to/data")
# Output: nn_k_0.500_0.500.bin

# Filter r-space data for r=(1, 2)
filter_bin_file("nn_r.bin", (1, 2), dir="/path/to/data")
# Output: nn_r_1_2.bin

# Custom output filename
filter_bin_file("afm_sf_k.bin", (0.5, 0.5), output_filename="afm_pi_pi.bin")

filter_bins(df, startbin, endbin, dropmaxmin, n_bins, verbose; value_columns=[:real_val, :imag_val])

通用bin过滤函数，支持实空间和k空间数据。

参数

• df: 输入DataFrame
• startbin: 起始bin
• endbin: 结束bin
• dropmaxmin: 丢弃的最大最小值数量 （bin大小的metric为所有坐标，所有value_columns的平均值）
• n_bins: 总bin数
• verbose: 是否打印详细信息
• value_columns: 用于过滤的数值列，默认为[:realval, :imagval]

过滤逻辑

该函数按 bin 进行过滤，对每个 bin 计算其所有数据点的平均值，然后排序并丢弃最大/最小的 bin。这确保了在保留数据空间完整性的同时，去除了时间上的离群值。

返回

过滤后的DataFrame

find_closest_k_point(k_points, target_k, tolerance)

Find the closest k-point in a set of k-points to a target k-point.

The k-point coordinates are treated as periodic with period 1 in each direction, consistent with fractional Brillouin-zone coordinates used in the k-space bin files (e.g. kx = m/L, ky = n/L).

Arguments

• k_points::Vector{<:Tuple{<:Real,<:Real}}: Vector of k-point coordinates [(kx1, ky1), (kx2, ky2), ...]
• target_k::Tuple{<:Real,<:Real}: Target k-point (kx, ky)
• tolerance::Float64: Tolerance for matching k-points

Returns

• Tuple{Real, Real}: Closest k-point coordinates (kx, ky)
• Bool: Whether it's an exact match (distance <= tolerance)
• Float64: Distance to the target k-point

Example

k_points = [(0.0, 0.0), (0.5, 0.0), (0.5, 0.5)]
target = (0.49, 0.51)
closest_k, exact_match, distance = find_closest_k_point(k_points, target, 0.1)
# Returns: ((0.5, 0.5), true, 0.014...)

find_coordinate_index(coords, target_coord, tolerance)

Find the index of a coordinate in a coordinate matrix.

This function handles both r-space (integer) and k-space (float) coordinates:

• For r-space (integer tuples): exact integer matching
• For k-space (float tuples): nearest neighbor matching with tolerance

Arguments

• coords::Matrix: Matrix of coordinates (Nx2, first two columns of bin file)
• target_coord::Union{Tuple{Int, Int}, Tuple{Float64, Float64}}: Target coordinate
• tolerance::Float64=1e-6: Tolerance for k-space matching (ignored for r-space)

Returns

• Union{Int, Nothing}: Index of the coordinate (1-based), or Nothing if not found
• Bool: Whether the match is exact (k-space) or found (r-space)

Examples

# R-space example
coords = [1.0 1.0; 1.0 2.0; 2.0 1.0]
idx, exact = find_coordinate_index(coords, (1, 2), 1e-6)
# Returns: (2, true)

# K-space example
coords = [0.0 0.0; 0.5 0.0; 0.5 0.5]
idx, exact = find_coordinate_index(coords, (0.49, 0.51), 0.1)
# Returns: (3, true)  # distance = 0.014 < 0.1

format_value_error(value, error, error_sig_digits=1; format=:scientific)

格式化数值及其误差，支持科学计数法或普通小数表示。

误差会按照给定的有效数字数目进行向上取整，数值会匹配同样的精度。

参数:

• value: 待格式化的数值
• error: 该数值的误差
• error_sig_digits: 误差保留的有效数字个数 (默认: 1)
• format: 输出格式，:scientific(默认) 返回科学计数法字符串，:decimal 返回普通小数

返回:

• (formatted_value, formatted_error) 字符串元组，格式由 format 决定

示例:

# 科学计数法 (默认)
format_value_error(2.36738, 0.0023)                      # ("2.367e+00", "0.003e0")
format_value_error(2367.38, 23, 2)                       # ("2.367e+03", "0.023e3")

# 普通小数
format_value_error(2.36738, 0.0023; format=:decimal)     # ("2.367", "0.003")
format_value_error(2367.38, 23; format=:decimal)         # ("2370", "30")

generate_all_derived_files(dir::AbstractString=pwd();
                           afm_source::String="ss_k.bin", 
                           verbose::Bool=true)

生成目录中所有衍生数据文件，包括反铁磁和电荷密度波/配对相关的文件。

参数

• dir::AbstractString=pwd(): 数据目录，默认为当前目录
• afm_source::String="ss_k.bin": 用于生成反铁磁结构因子的源文件名，默认为"ss_k.bin"
• verbose::Bool=true: 是否输出详细信息，默认为true

返回值

• Dict{String, String}: 包含生成的文件路径的字典，键为文件名，值为完整路径

示例

# 在当前目录生成所有衍生数据文件
files = generate_all_derived_files(verbose=true)

# 指定目录和源文件
files = generate_all_derived_files(dir="/path/to/data", afm_source="spsm_k.bin", verbose=true)

# 如果只需要生成特定类型的文件，可以直接调用相应的函数
afm_files = afm_k_files_generation(dir, afm_source="spsm_k.bin")
cdw_files = cdwpair_k_files_generation(dir)

generate_all_derived_files_recursive(base_dir::AbstractString=pwd();
                                     pattern::Regex=r".", 
                                     max_depth::Int=1,
                                     afm_source::String="ss_k.bin", 
                                     verbose::Bool=true)

递归地生成多个目录中的所有衍生数据文件。

参数

• base_dir::AbstractString=pwd(): 基础目录，默认为当前目录
• pattern::Regex=r".": 用于匹配目录名的正则表达式
• max_depth::Int=1: 最大递归深度
• afm_source::String="ss_k.bin": 用于生成反铁磁结构因子的源文件名，默认为"ss_k.bin"
• verbose::Bool=true: 是否输出详细信息，默认为true

返回值

• Dict{String, Dict{String, String}}: 包含每个目录生成文件的嵌套字典

示例

# 在当前目录及其子目录中生成所有衍生数据文件
results = generate_all_derived_files_recursive(verbose=true)

# 只处理符合特定模式的目录
results = generate_all_derived_files_recursive(pattern=r"^proj_fft_", verbose=true)

# 递归处理2层目录
results = generate_all_derived_files_recursive(max_depth=2, verbose=true)

# 指定源文件
results = generate_all_derived_files_recursive(
    base_dir="/path/to/data",
    afm_source="spsm_k.bin",
    verbose=true
)

iqr_fence_filter(values; k=10.0, min_n=5)

Apply Tukey's IQR fence to remove extreme outliers.

Given samples x₁,…,xₙ, define the quartiles and fences; keep points in-range.

Behaviour / edge cases

• Ignore missing / non-finite before quantiles.
• If finite samples < min_n, or IQR <= 0, keep all finite.
• If fence would remove all, fall back to keeping all finite.

Returns

(; keep::BitVector, filtered::Vector{Float64}, removed_min::Int, removed_max::Int)

merge_afm_sf(
    input_file::AbstractString="ss_k.bin",
    output_file::AbstractString="afm_sf_k.bin",
    input_dir::AbstractString=pwd(),
    output_dir::AbstractString=pwd();
    verbose::Bool=true
)

计算反铁磁结构因子并保存到文件。

参数

• input_file::AbstractString="ss_k.bin": 输入文件名
• output_file::AbstractString="afm_sf_k.bin": 输出文件名
• input_dir::AbstractString=pwd(): 输入文件目录
• output_dir::AbstractString=pwd(): 输出文件目录
• verbose::Bool=true: 是否显示详细信息

返回值

• String: 输出文件的完整路径或者空字符串

示例

# 使用默认设置计算反铁磁结构因子
output_path = merge_afm_sf()

# 指定输入和输出文件名及目录
output_path = merge_afm_sf("my_ss_k.bin", "my_afm_sf_k.bin", "/input/dir", "/output/dir", verbose=true)

function merge_bin_columns(
    input_filename::String,
    output_filename::String,
    real_columns::Vector{Int},
    imag_columns::Vector{Int},
    weights::Vector{Float64}=ones(length(real_columns)),
    input_dir::String=pwd(),
    output_dir::String=pwd();
    preserve_columns::UnitRange{Int}=1:2,
    verbose::Bool=false
)

将一个多列数据中的指定列合并为单列，生成新的数据文件。

参数：

• input_filename: 输入文件名
• output_filename: 输出文件名
• real_columns: 要合并的实部列索引
• imag_columns: 要合并的虚部列索引
• weights: 每对列的权重，默认全为1.0
• input_dir: 输入目录，默认为当前目录
• output_dir: 输出目录，默认为当前目录
• preserve_columns: 要保留的列范围，默认为1:2（通常是k点坐标）
• verbose: 是否输出详细信息，默认为false

返回：

• 合并后的文件完整路径或者空字符串（如果失败）

示例：

# 合并AA和BB轨道到单列文件
merged_file = merge_bin_columns(
    "spsm_k.bin",      # 输入文件名
    "merged.bin",       # 输出文件名
    [3, 9],           # 实部列（AA和BB轨道的实部）
    [4, 10],          # 虚部列（AA和BB轨道的虚部）
    [1.0, 1.0]        # 权重
)

merge_cdw_sf(
    input_file::AbstractString="cdwpair_k.bin",
    output_file::AbstractString="cdwpair_sf_k.bin",
    input_dir::AbstractString=pwd(),
    output_dir::AbstractString=pwd();
    verbose::Bool=true
)

计算电荷密度波结构因子并保存到文件。

参数

• input_file::AbstractString="cdwpair_k.bin": 输入文件名
• output_file::AbstractString="cdwpair_sf_k.bin": 输出文件名
• input_dir::AbstractString=pwd(): 输入文件目录
• output_dir::AbstractString=pwd(): 输出文件目录
• verbose::Bool=true: 是否显示详细信息

返回值

• String: 输出文件的完整路径或者空字符串

示例

# 使用默认设置计算电荷密度波结构因子
output_path = merge_cdw_sf()

# 指定输入和输出文件名及目录
output_path = merge_cdw_sf("my_input.bin", "my_output.bin", "/input/dir", "/output/dir", verbose=true)

merge_staggered_components(
    input_filename::String="ss_k.bin",
    output_filename::String="afm_sf_k.bin",
    input_dir::String=pwd(),
    output_dir::String=pwd();
    real_columns::Vector{Int}=[3, 9, 7, 5],  # [AA, BB, AB, BA] 实部列
    imag_columns::Vector{Int}=[4, 10, 8, 6], # [AA, BB, AB, BA] 虚部列
    preserve_columns::UnitRange{Int}=1:2,
    verbose::Bool=false
)

将多列数据使用交错相位的方式合并，生成新的数据文件。 公式: S = A + B - C - D，其中 A, B, C, D 分别对应数组中的四个列索引。

这种合并方式常用于计算反铁磁结构因子，其中 SAF = AA + BB - AB - BA。 默认的文件名设置（ssk.bin -> afmsfk.bin）反映了这一应用场景。

参数

• input_filename::String="ss_k.bin": 输入文件名
• output_filename::String="afm_sf_k.bin": 输出文件名
• input_dir::String=pwd(): 输入目录，默认为当前目录
• output_dir::String=pwd(): 输出目录，默认为当前目录
• real_columns::Vector{Int}=[3, 9, 7, 5]: 实部列索引数组，顺序为[A, B, C, D]
• imag_columns::Vector{Int}=[4, 10, 8, 6]: 虚部列索引数组，顺序为[A, B, C, D]
• preserve_columns::UnitRange{Int}=1:2: 要保留的列范围，默认为1:2（通常是k点坐标）
• verbose::Bool=false: 是否输出详细信息，默认为false

返回值

• 合并后的文件完整路径或者空字符串（如果失败）

示例

# 计算反铁磁结构因子
afm_sf_file = merge_staggered_components(
    "ss_k.bin",
    "afm_sf_k.bin"
)

# 自定义列索引
result = merge_staggered_components(
    "custom_input.bin",
    "custom_output.bin",
    real_columns=[3, 5, 7, 9],
    imag_columns=[4, 6, 8, 10]
)

merge_uniform_components(
    input_filename::String="cdwpair_k.bin",
    output_filename::String="cdwpair_sf_k.bin",
    input_dir::String=pwd(),
    output_dir::String=pwd();
    real_columns::Vector{Int}=[3, 9, 7, 5],  # [A, B, C, D] 实部列 (按AA, BA, AB, BB顺序的列位置)
    imag_columns::Vector{Int}=[4, 10, 8, 6], # [A, B, C, D] 虚部列 (按AA, BA, AB, BB顺序的列位置)
    preserve_columns::UnitRange{Int}=1:2,
    verbose::Bool=false
)

将多列数据使用统一相位的方式合并，生成新的数据文件。 公式: S = A + B + C + D，其中 A, B, C, D 分别对应数组中的四个列索引。

这种合并方式常用于计算电荷结构因子，其中 Scharge = AA + BB + AB + BA。 默认的文件名设置（cdwpairk.bin -> cdwpairsfk.bin）反映了这一应用场景。

参数

• input_filename::String="cdwpair_k.bin": 输入文件名
• output_filename::String="cdwpair_sf_k.bin": 输出文件名
• input_dir::String=pwd(): 输入目录，默认为当前目录
• output_dir::String=pwd(): 输出目录，默认为当前目录
• real_columns::Vector{Int}=[3, 9, 7, 5]: 实部列索引数组，顺序为[A, B, C, D]
• imag_columns::Vector{Int}=[4, 10, 8, 6]: 虚部列索引数组，顺序为[A, B, C, D]
• preserve_columns::UnitRange{Int}=1:2: 要保留的列范围，默认为1:2（通常是k点坐标）
• verbose::Bool=false: 是否输出详细信息，默认为false

返回值

• 合并后的文件完整路径或者空字符串（如果失败）

示例

# 计算电荷结构因子
cdwpair_sf_file = merge_uniform_components(
    "cdwpair_k.bin",
    "cdwpair_sf_k.bin"
)

# 自定义列索引
result = merge_uniform_components(
    "custom_input.bin",
    "custom_output.bin",
    real_columns=[3, 5, 7, 9],
    imag_columns=[4, 6, 8, 10]
)

outlier_filter(values, mode, param; min_n=5)

统一的离群值处理入口（公开）。返回 keep mask 与筛选后的值，并附带删除计数。

print_af_structure_factor_result(result::StructureFactorResult, filename::String)

打印反铁磁结构因子分析结果。

print_correlation_results(results_df, filename, Lx, Ly, dropmaxmin, startbin, endbin, n_bins)

Print single-orbital correlation analysis results.

Arguments:

• results_df: DataFrame containing analysis results
• filename: Name of the correlation file
• Lx, Ly: Lattice dimensions
• dropmaxmin: Number of maximum and minimum values dropped
• startbin, endbin: Bin range used
• n_bins: Total number of bins

print_correlation_results_multi_orbital(results_df, filename, Lx, Ly, orbital_labels, dropmaxmin, startbin, endbin, n_bins)

Print multi-orbital correlation analysis results.

Arguments:

• results_df: DataFrame containing analysis results
• filename: Name of the correlation file
• Lx, Ly: Lattice dimensions
• orbital_labels: Array of orbital labels
• dropmaxmin: Number of maximum and minimum values dropped
• startbin, endbin: Bin range used
• n_bins: Total number of bins

print_kspace_correlation_results(results_df, filename, dropmaxmin, startbin, endbin, n_bins)

打印k空间关联分析结果。

print_kspace_correlation_results_multi_orbital(results_df, filename, orbital_labels, dropmaxmin, startbin, endbin, n_bins)

打印多轨道k空间关联分析结果。

print_structure_factor_result(result::StructureFactorResult, filename::String, orbital::String="")

打印结构因子分析结果。

remove_outliers(values, mode, param; min_n=5)

统一的离群值处理入口（返回筛选后数据 + 删除计数）。

round_error(error_val, error_of_error)

Round an error value based on its error of error.

The error is rounded to be precise to one digit before the first significant digit of error of error. This ensures that the reported error has appropriate precision.

Arguments:

• error_val: The error value to be rounded
• error_of_error: The error of the error (uncertainty in the error estimate)

Returns:

• Rounded error value with appropriate precision
• The number of significant digits in the rounded error

Examples:

round_error(23456, 2345)    # Returns (30000,1)
round_error(2.3456, 0.002345)  # Returns (2.35,3)

save_analysis_results(df::DataFrame, filename::AbstractString="analysis_results.csv")

将分析结果保存到CSV文件。

参数

• df::DataFrame: 要保存的DataFrame
• filename::AbstractString="analysis_results.csv": 输出文件名

scale_bin_columns(
    input_filename::String,
    output_filename::String,
    column_factors::Union{Vector{<:Real}, Dict{Int, <:Real}},
    input_dir::String=pwd(),
    output_dir::String=pwd();
    preserve_columns::Union{Vector{Int}, UnitRange{Int}, Nothing}=nothing,
    default_factor::Real=1.0,
    verbose::Bool=false
)

对二进制数据文件的指定列应用标量因子。

参数

• input_filename::String: 输入文件名
• output_filename::String: 输出文件名
• column_factors::Union{Vector{<:Real}, Dict{Int, <:Real}}: 列因子，可以是向量（按顺序应用）或字典（指定列索引）
• input_dir::String=pwd(): 输入文件目录
• output_dir::String=pwd(): 输出文件目录
• preserve_columns::Union{Vector{Int}, UnitRange{Int}, Nothing}=nothing: 保持不变的列索引（这些列将不应用因子）
• default_factor::Real=1.0: 未指定列的默认因子
• verbose::Bool=false: 是否输出详细信息

返回值

• String: 生成的文件完整路径

示例

# 对第3-10列应用不同的标量因子
scale_bin_columns(
    "input.bin",          # 输入文件名
    "scaled_output.bin",  # 输出文件名
    [1, 1, 0.5, 0.5, -1, -1, 0.25, 0.25],  # 列因子
    preserve_columns=1:2,  # 前两列保持不变
    verbose=true
)

# 使用字典指定特定列的因子
scale_bin_columns(
    "input.bin",
    "scaled_output.bin",
    Dict(3 => 0.5, 4 => 0.5, 5 => -1, 6 => -1),  # 只修改指定列
    default_factor=1.0,  # 其他列保持原值
    verbose=true
)

scan_parameter_directories(base_dir::AbstractString=pwd(); 
                          filter_options::Union{Dict, NamedTuple}=Dict(), 
                          return_params::Bool=false) -> Union{Vector{String}, Vector{Tuple{String,String,Vector{Tuple{String,Any,Int}}}}}

Scan and filter subdirectories based on parameters parsed from directory names.

Arguments

• base_dir::AbstractString=pwd(): Base directory (default: current dir)
• filter_options::Union{Dict, NamedTuple}=Dict(): Filtering rules by value type:
  • Single value: equality match. Value may be Number (Int/Float), Bool, or String (e.g. a prefix string).
  • Array: membership match. Elements may be Number, Bool, or String.
  • Tuple(min, max): closed interval match, numeric only (do not use for Bool or String).
  Common keys include "prefix", "b", "U", "L", "dtau", "gw", "lprojgw".
• return_params::Bool=false: Whether to also return parsed parameter info.

Returns

• When return_params=false: Vector{String} of matching directory paths
• When return_params=true: Vector{Tuple{String,String,Vector{Tuple{String,Any,Int}}}} of (dir_path, prefix, params_vector)

Examples

# Prefix + array match
scan_parameter_directories("."; filter_options = Dict("prefix"=>"proj_x", "U"=>[4.0,6.0]))

# Bool flag
scan_parameter_directories("."; filter_options = Dict("lprojgw"=>true))