Full YAML Reference

This page is generated from nf2.reference and mirrors the public v0.4 YAML schema.

General Run Keys

Key	Type	Default	Description
path	str	./runs/nf2	Directory for checkpoints, logs, and extrapolation_result.nf2.
work_path	str | null	path/work	Optional scratch directory for preprocessed arrays.
logging	dict	{}	Options passed to the Lightning/W&B logger.
logging.project	str	logger default	W&B project name when W&B logging is enabled.
logging.name	str	logger default	Run name shown in W&B/log output.
meta_path	str	none	Optional previous NF2 state used by series runs.

Data And Geometry

Key	Type	Default	Description
data.geometry	cartesian | spherical	required	Extrapolation geometry.
data.normalization.Mm_per_ds	float	100	Length represented by one model coordinate unit.
data.normalization.Gauss_per_dB	float	1000	Magnetic-field strength represented by one model field unit.
data.boundaries	list[dict]	required	Boundary observations, analytical fields, or maps.
data.boundaries[].id	str	boundary / generated	Stable dataset id used by losses, transforms, callbacks, and series references.
data.boundaries[].type	str	required	Dataset implementation name. See the dataset reference for supported types.
data.boundaries[].files	dict | list[dict] | glob	dataset dependent	Input file mapping or series file mapping for observational datasets.
data.boundaries[].errors	dict | list[dict]	optional	Optional uncertainty-file mapping. Bundled templates skip unresolved error placeholders.
data.boundaries[].batch_size	int	data batch size	Per-dataset batch size override.
data.boundaries[].requires_jacobian	bool	dataset dependent	Whether this dataset must provide derivatives for losses or callbacks.
data.boundaries[].Mm_per_pixel	float	dataset default	Spatial sampling for this boundary in Mm per pixel.
data.boundaries[].coordinate_center	list[float] | dict	[0, 0]	Cartesian coordinate assigned to the boundary center, in Mm.
data.boundaries[].height_mapping	dict	none	Height metadata for multi-height Cartesian boundary datasets.
data.boundaries[].mask_configs	dict | list[dict]	none	Spherical map masking/filtering configuration.
data.boundaries[].mask_configs.type	str	mask dependent	Mask/filter implementation name, for example mu_filter or reference.
data.boundaries[].mask_configs.min	float	mask dependent	Minimum value for simple threshold-style masks such as mu_filter.
data.boundaries[].mask_configs.file	str	required for reference masks	Reference map file used by spherical reference masks.
data.boundaries[].mask_configs.mu_filter	dict	optional	Nested mu-angle filter applied inside a spherical reference mask.
data.boundaries[].mask_configs.mu_filter.min	float	mask dependent	Minimum mu value for the nested reference-mask filter.
data.boundaries[].mask_configs[].type	str	mask dependent	Mask/filter implementation name when masks are provided as a list.
data.boundaries[].mask_configs[].min	float	mask dependent	Minimum value when list-form masks use mu_filter.
data.validation	list[dict]	geometry default	Validation grids and plotting datasets.
data.validation[].id	str	generated	Stable validation dataset id used by callbacks.
data.validation[].type	str	required	Validation dataset implementation name.
data.validation[].files	dict | list[dict] | glob	dataset dependent	Input file mapping for validation datasets.
data.validation[].errors	dict | list[dict]	optional	Optional validation uncertainty-file mapping.
data.validation[].filter_nans	bool	dataset default	Whether to filter NaN samples in spherical map validation datasets.
data.validation[].shuffle	bool	dataset default	Whether to shuffle validation samples.
data.validation[].plot_overview	bool	dataset default	Whether to prepare overview plots for spherical map validation datasets.
data.validation[].plot_currents	bool	dataset default	Whether spherical slice validation plots include current-density views.
data.validation[].n_slices	int	dataset default	Number of slices for slice-based validation datasets.
data.validation[].mask_configs.type	str	mask dependent	Mask/filter implementation name for validation map datasets.
data.validation[].mask_configs.min	float	mask dependent	Minimum value for validation threshold-style masks such as mu_filter.
data.validation[].mask_configs[].type	str	mask dependent	Mask/filter implementation name when validation masks are provided as a list.
data.validation[].mask_configs[].min	float	mask dependent	Minimum value when list-form validation masks use mu_filter.
data.batch_size	int	4096 spherical, 8192 cartesian	Default dataset batch size passed to loaders.
data.validation_batch_size	int	16384	Cartesian validation batch size.
data.validation_pixel_per_ds	float	128	Cartesian validation sampling density; larger values make coarser validation cubes.
data.sampler	dict	height sampler	Cartesian physics sampling dataset.
data.sampler.type	height | default	height	Cartesian random sampler type.
data.sampler.batch_size	int	16384 in examples	Cartesian random sampler batch size.
data.samplers	list[dict]	random_radial_grouped	Spherical physics sampling datasets.
data.samplers[].id	str	random	Spherical sampler id used by losses.
data.samplers[].type	random_radial_grouped | random_spherical	random_radial_grouped	Spherical random sampler type.
data.samplers[].batch_size	int	data.batch_size	Spherical random sampler batch size.
data.potential_boundary	dict	FFT potential	Cartesian potential boundary data. Use type: none to disable.
data.potential_boundary.id	str	ignored	Accepted for readability; normalized away because the runtime id is potential.
data.potential_boundary.type	potential | potential_top | none	potential	Potential side/top boundary mode.
data.potential_boundary.strides	int	4	Downsample factor for potential boundary generation.
data.z_range	list[float]	loader default	Cartesian height range in Mm where supported by the loader.
data.max_radius	float	loader default	Spherical outer radius in solar radii where supported by the loader.
data.iterations	int	10000	Number of random sampler batches per epoch-like pass.
data.num_workers	int	4	Default PyTorch DataLoader workers for training and validation loaders. Series preloading uses this value unless data.data_module_workers is set.
data.train_num_workers	int	data.num_workers	PyTorch DataLoader workers for training loaders.
data.validation_num_workers	int	data.num_workers	PyTorch DataLoader workers for validation loaders.
data.prefetch_factor	int	5	Training DataLoader prefetch factor when workers are enabled.
data.persistent_workers	bool	true	Keep training DataLoader workers alive while a loader is active.
data.preload_data_modules	bool	true	For series runs, preload all step data modules up front instead of loading each step lazily.
data.data_module_workers	int	data.num_workers	Series-only multiprocessing workers used to preload per-step data modules.

Model

Key	Type	Default	Description
model.field	vector_potential | scaled_vector_potential | b	vector_potential	Field representation.
model.network.type	siren	siren	Only SIREN networks are supported.
model.network.hidden_dim	int	256 cartesian, 512 spherical	SIREN hidden width.
model.network.layers	int	model default	Number of SIREN layers.
model.network.w0	float	model default	SIREN frequency scale for hidden layers.
model.network.w0_initial	float	model default	SIREN frequency scale for the first layer.
model.radial_power	float	2.0	Radial power for scaled_vector_potential, applied as (r / R_sun)^-radial_power.
model.coordinate_radial_power	float	4.0	Radial power for compressing SIREN input coordinates in scaled_vector_potential, applied as coords * (r / R_sun)^-coordinate_radial_power.
model.base_radius	float	R_sun in model units	Reference radius for scaled_vector_potential; omit for spherical runs.

Training

Key	Type	Default	Description
training.epochs	int	15	Number of Lightning epochs.
training.optimizer.start	float	5e-4	Initial learning rate.
training.optimizer.end	float	5e-5	Final learning rate.
training.optimizer.iterations	int	100000	Learning-rate schedule length.
training.gradient_clip_val	float	0.1	Gradient clipping value passed to the Lightning Trainer unless overridden in training.trainer.
training.matmul_precision	str	medium	Torch matmul precision setting used before training.
training.reload_dataloaders_every_n_epochs	int	1 for series	Series cadence for advancing to the next dataset.
training.check_val_every_n_epoch	int	1	Lightning validation cadence. Series examples use 10 to validate every 10th dataset.
training.val_check_interval	int | float	Lightning default	Optional Lightning validation interval alias used by single-run training.
training.trainer	dict	{}	Additional Lightning Trainer keyword arguments.
training.trainer.*	any	Lightning default	Additional keyword passed through to lightning.pytorch.Trainer.

Losses And Scaling

Key	Type	Default	Description
losses	list[dict]	geometry default	Training objective terms. Omit to use geometry-specific defaults.
losses[].type	str	geometry default	Loss implementation name. Supported values are boundary, boundary_los_trv, boundary_azi, boundary_los_trv_azi, boundary_los, divergence, force_free, potential, weighted_height, height, NaNs, radial, min_height, energy_gradient, energy, sigma_j.
losses[].name	str	type	Stable logging and scaling identifier.
losses[].weight	float | schedule	required when explicit	Loss weight. The legacy lambda key is not accepted.
losses[].weight.type	exponential | linear | step	exponential	Schedule type when weight is a mapping.
losses[].weight.start	float	required for exponential/linear	Initial scheduled loss weight.
losses[].weight.end	float	required for scheduled weights	Final scheduled loss weight.
losses[].weight.iterations	int	required for exponential/linear	Number of optimizer steps over which to change the weight.
losses[].weight.steps	int	required for step	Step interval for step schedules.
losses[].datasets	str | list[str]	loss default	Dataset ids used by the loss.
losses[].ambiguous	bool	loss default	Enable ambiguity-aware behavior for supported azimuth/disambiguation losses.
loss_scaling	list[dict]	geometry default	Spatial scaling modules for selected losses.
loss_scaling[].type	exponential | potential_fit | b_height | radial	geometry default	Loss-scaling module type.
loss_scaling[].name	str	type	Stable loss-scaling module name.
loss_scaling[].loss_ids	list[str]	required	Loss names to scale.
loss_scaling[].base_radius	float	1.1 radial default	Solar-radius baseline for radial scaling.
loss_scaling[].max_radius	float | null	none	Optional outer radius used to normalize radial scaling.
loss_scaling[].power	float	module default	Exponent used by b_height or potential_fit scaling.

Callbacks And Transforms

Key	Type	Default	Description
callbacks	list[dict]	geometry default	Validation plots and metrics logged during training.
callbacks[].type	boundary | metrics | slices | spherical_slices | fits_comparison | disambiguation | los_trv_azi_boundary	required	Callback implementation name.
callbacks[].dataset	str	required for most callbacks	Public alias for validation dataset id; normalized internally to ds_id.
callbacks[].name	str	callback default	Optional display/logging name for callbacks that support it.
callbacks[].plot	bool	true	For plotting callbacks, set false to keep scalar metrics but skip image rendering/logging.
callbacks[].component_labels	list[str]	callback default	Optional labels for vector-component plots.
transforms	list[dict]	[]	Optional coordinate/field transforms applied to datasets.
transforms[].type	height_range | height | optical_depth | azimuth	required	Transform implementation name.
transforms[].datasets	str | list[str]	required	Dataset ids to transform; normalized internally to ds_id.
transforms[].height_range	list[float]	required for height	Height range in Mm for learned height transforms.
transforms[].max_height	float	required for optical_depth	Maximum optical-depth transform height in Mm.
transforms[].max_log_optical_depth	float	-5	Maximum log optical depth for optical-depth transforms.