CLI Reference¶
This guide covers all command-line tools provided by furax-cs for data generation, component separation, and analysis.
Workflow Overview¶
generate_data → kmeans-model / ptep-model / fgbuster-model → r_analysis snap → r_analysis plot
Generate simulated frequency maps
Run component separation (produces result folders)
Analyze results with
r_analysis
generate_data¶
Pre-generate and cache frequency maps (CMB + Dust + Synchrotron).
generate_data --nside 64 --sky c1d1s1
Flag |
Type |
Default |
Description |
|---|---|---|---|
|
|
|
HEALPix resolution |
|
|
|
PySM sky configuration tag |
The --sky tag follows PySM naming: c (CMB), d (dust), s (synchrotron), with a digit indicating the model index. Use 0 to disable a component.
Custom CMB with tensor-to-scalar ratio:
# Generate CMB with r = 0.003
generate_data --nside 64 --sky cr3d1s1
The cr<N> prefix generates a CMB map with \(r = 0.001 \times N\).
kmeans-model¶
Adaptive K-means clustering for spatially-varying component separation. The sky is partitioned into clusters, and spectral parameters are optimized per cluster.
Usage¶
kmeans-model -n 64 -pc 10000 500 500 -m GAL020 -tag c1d1s1
Arguments¶
Flag |
Type |
Default |
Description |
|---|---|---|---|
|
|
|
HEALPix resolution |
|
|
|
Cluster counts for \([\beta_d, T_d, \beta_s]\) |
|
|
none |
Cluster source for \([\beta_d, T_d, \beta_s]\). Overrides |
|
|
|
Galactic mask (see Masks section below) |
|
|
|
Sky simulation tag |
|
|
|
Number of noise realizations |
|
|
|
Noise level as fraction of signal RMS |
|
|
|
Starting seed for noise simulations |
|
|
|
Instrument config: |
|
|
|
Optimizer (see minimization) |
|
|
|
Max optimization iterations |
|
|
|
Initial \([\beta_d, T_d, \beta_s]\) |
|
|
|
Linesearch: |
|
flag |
|
Enable gradient conditioning |
|
flag |
|
Only save best params (skip full results) |
|
flag |
|
Use |
|
|
none |
Fraction of constraints to release (active set) |
|
|
|
Absolute convergence tolerance |
|
|
|
Relative convergence tolerance |
|
|
|
Output directory |
|
|
auto |
Override output folder name |
Cluster Sources (-c)¶
The -c flag provides fine-grained control over how clusters are defined for each spectral parameter. It accepts exactly three values, one for each of \([\beta_d, T_d, \beta_s]\):
Value |
Meaning |
|---|---|
|
Use precomputed pixel subsets derived from true parameter values. Only available for |
integer |
Run K-means clustering with this many clusters (same as |
path to |
Load a full-sky patches file (e.g., produced by |
Values can be mixed freely. When -c is provided, it overrides -pc entirely.
Examples:
# Use precomputed true-parameter subsets for all three parameters
kmeans-model -n 64 -c true true true -m GAL020 -tag c1d1s1
# Use binned patches from r_analysis bin
kmeans-model -n 64 \
-c binned/patches_beta_dust.npy binned/patches_temp_dust.npy binned/patches_beta_pl.npy \
-m GAL020 -tag c1d1s1
# Mix: true for beta_dust, 50 K-means clusters for temp_dust, file for beta_synch
kmeans-model -n 64 -c true 50 binned/patches_beta_pl.npy -m GAL020 -tag c1d1s1
ptep-model¶
Multi-resolution component separation using HEALPix ud_grade. Each spectral parameter is optimized at a different angular resolution.
Usage¶
# Beta_dust at nside=64, Temp_dust at 32, Beta_synch at 16
ptep-model -n 64 -ud 64 32 16 -m GAL020 -tag c1d1s1
Arguments¶
Same as kmeans-model except:
Flag |
Type |
Default |
Description |
|---|---|---|---|
|
|
|
Target nside for \([\beta_d, T_d, \beta_s]\) (replaces |
No --linesearch argument. Otherwise shares all other flags with kmeans-model.
fgbuster-model¶
Baseline comparison using the FGBuster framework with multi-resolution clustering.
Usage¶
fgbuster-model -n 64 -ud 64 32 16 -m GAL020 -tag c1d1s1
Arguments¶
Flag |
Type |
Default |
Description |
|---|---|---|---|
|
|
|
HEALPix resolution |
|
|
|
Target nside for \([\beta_d, T_d, \beta_s]\) |
|
|
|
Galactic mask |
|
|
|
Sky simulation tag |
|
|
|
Number of noise realizations |
|
|
|
Noise level (default differs from other models) |
|
|
|
Starting seed |
|
|
|
Instrument config |
|
|
|
Max iterations (uses TNC solver internally) |
|
|
|
Initial parameters |
|
flag |
|
Only save best params |
|
|
|
Output directory |
|
|
auto |
Override output folder name |
Note
fgbuster-model always uses SciPy’s TNC solver internally. It does not support --solver, --cond, --linesearch, or --use-vmap.
Output Structure¶
All three models produce the same output structure:
results/<run_name>/
├── best_params.npz # Optimized spectral parameters
├── mask.npy # Binary sky mask used
└── results.npz # Full results (maps, NLL, per-realization data)
The <run_name> encodes the configuration. For example:
results/kmeans_c1d1s1_BD10000_TD500_BS500_SP1.54_20.0_-3.0_LiteBIRD_GAL020_U_optax_lbfgs_condFalse_lsbacktracking_noise0/
Use --name to set a custom folder name instead.
These result folders are consumed by r_analysis for computing \(r\) estimates, residuals, and generating plots.
Masks¶
Available mask names:
Mask |
Description |
|---|---|
|
Full sky |
|
Galactic plane only |
|
20% Galactic cut (upper + lower) |
|
10% upper Galactic cut |
|
10% lower Galactic cut |
|
20% Galactic cut |
|
10% upper/lower |
|
20% Galactic cut |
|
10% upper/lower |
Masks can be combined with + (union) and - (subtract):
kmeans-model -m "GAL040-GAL020" # 40% cut minus 20% cut
kmeans-model -m "GAL020+GAL040" # union of both regions