API Reference

The top-level nf2 package exposes the stable public access points. Lower-level modules remain available for advanced use cases, but user code should prefer these helpers.

Public access points for the NF2 framework.

The top-level package intentionally avoids importing heavy astronomy and deep learning dependencies until a caller asks for the matching helper.

nf2.download_hmi_full_disk(*args, **kwargs)

Download HMI full-disk vector data through JSOC/DRMS.

nf2.download_hmi_sharp(*args, **kwargs)

Download HMI SHARP vector data through JSOC/DRMS.

nf2.download_hmi_synoptic(*args, **kwargs)

Download HMI synoptic vector maps through JSOC/DRMS.

nf2.download_sharp_series(*args, **kwargs)

Download a SHARP data series through JSOC/DRMS.

nf2.export_file(*args, **kwargs)

Export one NF2 result file to VTK, NPZ, HDF5, or FITS.

nf2.export_series(*args, **kwargs)

Export multiple NF2 result files matched by one or more glob patterns.

nf2.load(path, device=None)

Load an NF2 result and return the matching output helper.

Parameters:

• path – Path to a .nf2 checkpoint.

• device – Optional PyTorch device used for evaluation.

Returns:

Geometry-specific output helper selected from checkpoint metadata.

Return type:

CartesianOutput or SphericalOutput

nf2.run(*args, **kwargs)

Run a single NF2 extrapolation.

The function accepts either the normalized runtime configuration used by nf2.extrapolate or the public v0.4 YAML-style schema. When the public schema is passed, it is normalized before training starts.

nf2.run_series(*args, **kwargs)

Run an NF2 extrapolation series.

Accepts the same public configuration schema as run(), with series placeholders expanded before the data module is built.

class nf2.CartesianOutput(*args, **kwargs)

Evaluate Cartesian NF2 extrapolation checkpoints.

load_cube(height_range=None, x_range=None, y_range=None, Mm_per_pixel=None, **kwargs)

Load a regularly sampled Cartesian volume.

Ranges are specified in megameters. Additional keyword arguments are forwarded to BaseOutput.load_coords().

load_slice(z=<Quantity 0. Mm>, Mm_per_pixel=None, **kwargs)

Load one horizontal Cartesian slice at height z.

load_maps(**kwargs)

Load SunPy maps for integrated field strength, current, and energy.

trace(start_coords, direction=1, max_iterations=None, **kwargs)

Trace the field line from the given coordinates using a 4th order Runge-Kutta method.

class nf2.SphericalOutput(*args, **kwargs)

Evaluate spherical NF2 extrapolation checkpoints.

load_spherical(radius_range=None, latitude_range=<Quantity [-1.57079633,  1.57079633] rad>, longitude_range=<Quantity [0.        , 6.28318531] rad>, sampling=[100, 180, 360], **kwargs)

Load a regularly sampled spherical volume.

sampling is ordered as radius, latitude, longitude. Ranges should use Astropy units.

Parameters:

• radius_range (Quantity)

• latitude_range (Quantity)

• longitude_range (Quantity)

load(radius_range=None, latitude_range=<Quantity [-1.57079633, 1.57079633] rad>, longitude_range=(0, 6.283185307179586), resolution=<Quantity 64. pix / solRad>, nan_value=0, **kwargs)

Load a Cartesian cube covering a spherical shell selection.

Parameters:

• radius_range (Quantity)

• latitude_range (Quantity)

• longitude_range (Quantity)

• resolution (Quantity)

load_spherical_coords(spherical_coords, **kwargs)

Evaluate the model at explicit SkyCoord positions.

Parameters:

spherical_coords (SkyCoord)

Unified export command for NF2 result files.

nf2.export.export_file(nf2_path, out_path=None, *, fmt='vtk', Mm_per_pixel=None, height_range=None, metrics=None, x_range=None, y_range=None, radius_range=None, latitude_range=None, longitude_range=None, pixels_per_solRad=64, progress=True)

Export one NF2 file to a supported exchange format.

Parameters:

• nf2_path (str) – Path to an extrapolation_result.nf2 checkpoint.

• out_path (str | None) – Optional output path. Converter defaults are used when omitted.

• fmt (str) – Export format: vtk, npz, hdf5/h5, fits, or height for multi-height surface mappings.

• Mm_per_pixel (float | None) – Cartesian sampling controls in megameters.

• height_range (list[float] | None) – Cartesian sampling controls in megameters.

• x_range (list[float] | None) – Cartesian sampling controls in megameters.

• y_range (list[float] | None) – Cartesian sampling controls in megameters.

• radius_range (list[float] | None) – Spherical VTK sampling controls. Radius is in solar radii; angles are in degrees.

• latitude_range (list[float] | None) – Spherical VTK sampling controls. Radius is in solar radii; angles are in degrees.

• longitude_range (list[float] | None) – Spherical VTK sampling controls. Radius is in solar radii; angles are in degrees.

• pixels_per_solRad (int) – Spherical VTK sampling controls. Radius is in solar radii; angles are in degrees.

• metrics (list[str] | None) – Derived quantities to include, such as j, alpha, or free_energy_fft.

• progress (bool) – Show converter progress where supported.

nf2.export.export_series(patterns, out_dir, *, fmt='vtk', overwrite=False, **kwargs)

Export all NF2 files matched by one or more glob patterns.

Existing files are skipped unless overwrite is true.

Parameters:

• patterns (list[str])

• out_dir (str)

• fmt (str)

• overwrite (bool)

Command-line quality metrics for NF2 extrapolation results.

nf2.metrics.compute_metrics(nf2_path, *, device=None, progress=False, **kwargs)

Compute standard NLFF quality metrics for an NF2 result.

Parameters:

• nf2_path – Path to an extrapolation_result.nf2 file.

• device – Optional PyTorch device for evaluation.

• progress – Show progress while sampling the model.

• **kwargs – Geometry-specific sampling options. Cartesian output accepts Mm_per_pixel, height_range, x_range, and y_range. Spherical output accepts spherical_sampling, radius_range, latitude_range, and longitude_range.

Returns:

Metric names and scalar values ready for printing or downstream use.

Return type:

dict

nf2.metrics.print_metrics(metrics)

Print metrics in a compact command-line table.

Unified download command for NF2 example data sources.

nf2.data.download.download_hmi_sharp(download_dir, email, t_start, t_end=None, noaa_num=None, sharp_num=None, cadence='720s', segments='Br,Bp,Bt,Br_err,Bp_err,Bt_err', series='sharp_cea_720s')

Download an HMI SHARP or SHARP CEA vector magnetogram series.

Parameters mirror the nf2-download --source hmi_sharp command. Provide either sharp_num or noaa_num.

nf2.data.download.download_hmi_synoptic(download_dir, email, carrington_rotation=None, carrington_rotation_end=None, t_start=None, t_end=None, segments='Br,Bt,Bp', series='b_synoptic', include_mr_polfil=False, synoptic_product='vector')

Download HMI synoptic maps for one or more Carrington rotations.

Rotations can be provided explicitly or inferred from t_start and optional t_end.

nf2.data.download.download_hmi_full_disk(download_dir, email, t_start, t_end=None, cadence='720s', series='B_720s', segments='field,inclination,azimuth,disambig', convert_ptr=True, keep_coordinates=False)

Download HMI full-disk vector data, optionally converted to Br/Bt/Bp.

Conversion uses the JSOC HmiB2ptr export process by default.