GeoMagSharp 1.7.1

GeoMagSharp

A C# library for geomagnetic field calculations using spherical harmonic models. GeoMag # is a port of the C++ application GeoMag 7.0 distributed by NOAA.

Installation

dotnet add package GeoMagSharp

Or via the NuGet Package Manager:

Install-Package GeoMagSharp

Quick Start

using GeoMagSharp;

// Load a coefficient file (GeoMag is IDisposable so HDGM native handles get released)
using var geoMag = new GeoMag();
geoMag.LoadModel("WMM2025.COF");

// Configure calculation
var options = new CalculationOptions
{
    Latitude = 45.0,
    Longitude = -93.0,
    StartDate = new DateTime(2025, 7, 1),
    SecularVariation = true,
    CalculationMethod = Algorithm.BGS
};
options.SetElevation(0, Distance.Unit.meter, true);

// Run calculation
geoMag.MagneticCalculations(options);

// Access results
var result = geoMag.ResultsOfCalculation[0];
Console.WriteLine($"Declination: {result.Declination.Value:F2} degrees");
Console.WriteLine($"Inclination: {result.Inclination.Value:F2} degrees");
Console.WriteLine($"Total Field: {result.TotalField.Value:F1} nT");

Async API

// Async with progress reporting and cancellation
var cts = new CancellationTokenSource();
var progress = new Progress<CalculationProgressInfo>(p =>
    Console.WriteLine($"{p.PercentComplete:F0}% - {p.StatusMessage}"));

var model = await ModelReader.ReadAsync("WMM2025.COF", progress, cts.Token);
await geoMag.MagneticCalculationsAsync(options, progress, cts.Token);
await geoMag.SaveResultsAsync("output.txt", false, cts.Token);

Supported Models

Bundled coefficient files are in the coefficient/ directory. See coefficient/NOTICE.md for attribution and download links for non-bundled models.

HDGM is Windows-only and requires a user-supplied NOAA DLL. It provides a degree-740 crustal field with per-point uncertainty estimates and a high-resolution survey coverage flag. See docs/features/hdgm-support/README.md for setup instructions.

Uncertainty Estimation

GeoMagSharp includes ISCWSA-based geomagnetic uncertainty values (CDR-SM-03 Rev 8, Rev5.13). Uncertainty is automatically attached to calculation results based on the loaded model type.

// Uncertainty is auto-populated on each result
geoMag.MagneticCalculations(options);
var result = geoMag.ResultsOfCalculation[0];

if (result.Uncertainty != null)
{
    Console.WriteLine($"Category:    {result.Uncertainty.ModelCategory}");
    Console.WriteLine($"Declination: +/-{result.Uncertainty.Declination:F2} deg (1-sigma)");
    Console.WriteLine($"Total Field: +/-{result.Uncertainty.TotalField:F0} nT (1-sigma)");
    Console.WriteLine($"Dip Angle:   +/-{result.Uncertainty.DipAngle:F2} deg (1-sigma)");

    // Scale to approximate 2-sigma
    var u2 = result.Uncertainty.ScaleTo(2.0);
}

// Override for commercial models or in-field referencing
var ifrOptions = new CalculationOptions
{
    Latitude = 40.0,
    Longitude = -105.0,
    StartDate = new DateTime(2025, 7, 1),
    ModelCategoryOverride = GeomagneticModelCategory.InFieldReference1
};

Auto-detected categories: WMM/IGRF/DGRF → LowResolution, WMMHR/EMM → HighResolution. For BGGM, HDGM, or IFR corrections, set ModelCategoryOverride on CalculationOptions.

See examples/GeoMagSharp.Example for a runnable smoke test.

Target Frameworks

• .NET Framework 4.8
• .NET Standard 2.0 (compatible with .NET Core 2.0+, .NET 5+)

API Overview

Core Classes

• GeoMag - Main entry point for loading models and running calculations
• ModelReader - Parses COF/DAT coefficient files into model objects
• Calculator - Low-level spherical harmonic calculation engine
• CalculationOptions - Configuration for latitude, longitude, date, elevation, etc.
• ModelDiscovery - Enumerates loadable model files in a folder (COF, DAT, HDGM .dll)

Discovering models in a folder

ModelDiscovery.DiscoverModels(folderPath) enumerates every loadable model file (.cof, .dat, HDGM .dll) in a folder without knowing each format's filename rules:

foreach (var d in ModelDiscovery.DiscoverModels("./coefficients"))
    Console.WriteLine($"{d.DisplayName} ({d.DetectedType}) {d.MinDate}..{d.MaxDate}");

// e.g.   WMM-2025 (WMM)  2025..2030
//        IGRF2025 (IGRF) 1900..2030    // latest epoch label for multi-epoch IGRF files
//        HDGM2025 (HDGM) 2000..2030

For multi-epoch IGRF/DGRF .COF files, DisplayName reflects the latest epoch (e.g. "IGRF2025" for IGRF14.COF), with MinDate/MaxDate covering the full validity range across all contained epochs. Single-epoch models (WMM, EMM, BGGM) report their header-stated year and a 5-year MaxDate.

Pass new ModelDiscoveryOptions { UseCache = true } to populate a .models.json cache for fast subsequent startups. The cache is schema-versioned and auto-invalidates when classifier behavior changes between library versions.

ModelDiscovery.DescribeFile(path) performs the same inspection on a single file. See ScanMode, ModelDiscoveryOptions, and ModelDescriptor IntelliSense for full options.

Model Classes

• ModelDescriptor - Read-only snapshot returned by ModelDiscovery (file path, detected type, display name, validity range)
• MagneticModelSet - A set of magnetic models (main field + secular variation)
• MagneticModelCollection - Manages multiple model sets with JSON serialization
• MagneticCalculations - Calculation results (declination, inclination, field components)

Result Properties

Each MagneticCalculations result contains MagneticValue objects with:

• Value - The calculated value
• ChangePerYear - Secular variation (when enabled)

Available components: Declination, Inclination, TotalField, HorizontalIntensity, NorthComponent, EastComponent, VerticalComponent, GridVariation.

License

MIT License - see LICENSE for details.

Bundled coefficient files are U.S. Government works in the public domain. See coefficient/NOTICE.md for full attribution.