Training configuration

For inference, load a pretrained bundle: it restores the architecture and configuration from the checkpoint. You do not need a training configuration to use VDC. See getting started.

For a small new training run from a source checkout:

python -m pip install -e '.[train]'
python examples/train_custom_copula.py --output results/custom_denoiser.yaml
python scripts/train_unified.py --model-type denoiser --config results/custom_denoiser.yaml

The example writes a small configuration and prints the training command. It does not launch training. Its model is for learning the workflow, not a substitute for the published checkpoint. Increase capacity and training duration only after checking validation performance on independent synthetic cases.

Data

The unified trainer reads these keys under data:

Key Meaning
m Density grid width and height.
n_samples_per_copula An integer, a list of choices, or a mapping with mode, min, max (or choices).
copula_families Mapping of supported family names to nonnegative sampling weights.
param_ranges Optional parameter ranges, e.g. gaussian_rho: [-0.8, 0.8].
rotation_prob Probability of selecting a rotation for asymmetric families.
mixture_prob Probability of a parametric mixture example.
n_mixture_components Inclusive minimum and maximum component counts.
num_workers DataLoader worker count; use zero for a small CPU run.

Supported parametric names are gaussian, student, clayton, gumbel, frank, joe, bb1, bb7, and independence. Grid-defined complex examples are selected with complex, complex:x, complex:ring, or complex:double_banana. Mixtures combine parametric families.

data:
  m: 64
  n_samples_per_copula:
    mode: log_uniform
    min: 200
    max: 20000
  copula_families:
    gaussian: 1
    student: 1
    clayton: 1
    gumbel: 1
    frank: 1
    joe: 1
    bb1: 1
    bb7: 1
    independence: 1
  rotation_prob: 0.5
  mixture_prob: 0.3
  n_mixture_components: [2, 4]
  num_workers: 2

This illustrates configuration syntax; it is not a validated replacement recipe for the paper's model. Varying sample counts returns fixed-size histograms rather than raw sample tensors so batches can be collated. Options that require raw samples, such as histogram reconstruction, should use a fixed count.

Read training data before reusing historical configurations. The invalid conditional_* training options are rejected. Corrected sampling changes future training streams, while the released checkpoint remains unchanged.

Architecture

Choose the architecture with the command-line --model-type. For denoiser, the model section accepts base_channels, depth, blocks_per_level, time_emb_dim, dropout, and output_mode. Channel widths must be divisible by eight for group normalization. use_coordinates adds the two coordinate channels; use_log_n adds a sample-count channel. Match these settings when loading checkpoints; the public loader does that automatically.

diffusion_unet uses a different architecture (channel_mults, num_res_blocks, attention_resolutions) and a diffusion section for its noise schedule and timesteps. baseline_cnn and enhanced_cnn are additional architectures. Their settings are not interchangeable with the denoiser's.

Probit-coordinate and density-transform options are experimental. They do not by themselves turn the uniform cell grid into a nonuniform grid. The public checkpoint uses its embedded geometry settings.

Optimization and outputs

The training section requires batch_size, max_steps, and learning_rate. Useful options include weight_decay, gradient_clip, use_amp, and projection_iters. Set use_amp: false for the CPU example.

loss_weights supports ce (cross-entropy), ise (integrated squared error), tail, ms (multiscale), tv (total variation), and marg_kl (marginal regularization). A zero weight disables a term. These losses are grid approximations, and their scales differ; compare validation metrics when changing their balance. Unknown keys are not a way to add a loss.

log_interval, save_interval, and viz_interval control reporting, checkpoint saving and training diagnostics. checkpoint_dir is a top-level key. Use --resume path/to/checkpoint.pt to resume a compatible trusted checkpoint.

The unified command seeds dataset workers from 42 + distributed rank; record worker count, source revision, full configuration and environment alongside a run. Exact historical training replay requires the original generator revision. The older scripts/legacy/train.py is a separate training frontend; do not assume its checkpoints or defaults are interchangeable with scripts/train_unified.py.