### Compile with mpy-cross

Source: https://github.com/boxpet/pygeomag/blob/main/CONTRIBUTING.rst

Ensure the code can be compiled using mpy-cross for MicroPython compatibility. Refer to the provided guide for setup.

```bash
mpy-cross
```

--------------------------------

### Install pyGeoMag using pip

Source: https://github.com/boxpet/pygeomag/blob/main/README.rst

Install the pyGeoMag library using pip. This command is used to add the package to your Python environment.

```shell
pip install pygeomag
```

--------------------------------

### CircuitPython/MicroPython Geomagnetic Calculations

Source: https://context7.com/boxpet/pygeomag/llms.txt

Use pyGeoMag on microcontrollers by copying the `boxpet_geomag` folder to the `lib/` directory. This example demonstrates using compiled coefficient data directly for faster performance and reduced memory usage.

```python
# On CircuitPython/MicroPython boards, copy boxpet_geomag folder to lib/
from boxpet_geomag.geomag import GeoMag
from boxpet_geomag.wmm_2025 import WMM_2025

# Use coefficients data directly (faster on microcontrollers)
geo_mag = GeoMag(coefficients_data=WMM_2025)

# Calculate declination
result = geo_mag.calculate(
    glat=47.6205,
    glon=-122.3493,
    alt=0,
    time=2025.5
)

print(f"Declination: {result.d:.4f}°")
print(f"Inclination: {result.i:.4f}°")
print(f"Total Intensity: {result.f:.1f} nT")

# Calculate uncertainty
uncertainty = result.calculate_uncertainty()
print(f"Declination uncertainty: ±{uncertainty.d:.4f}°")

# Note: High resolution model (WMMHR) may not work on most
# microcontrollers due to memory constraints
```

--------------------------------

### Calculate Geomagnetic Declination with WMM_2010

Source: https://github.com/boxpet/pygeomag/blob/main/README.rst

Calculates the geomagnetic declination for a given latitude, longitude, altitude, and time using the WMM_2010 coefficient file. This example demonstrates a specific time point.

```python
>>> from pygeomag import GeoMag
>>> geo_mag = GeoMag(coefficients_file='wmm/WMM_2010.COF')
>>> result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2013.25)
>>> print(result.d)
16.415602225952366
```

--------------------------------

### Calculate Geomagnetic Declination with Default Coefficients

Source: https://github.com/boxpet/pygeomag/blob/main/README.rst

Calculates the geomagnetic declination using the default coefficient file, which is WMM_2025. This example shows a calculation for a specific time point.

```python
>>> result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2025.25)
>>> print(result.d)
15.065629638512593
```

--------------------------------

### Calculate Magnetic Field Components

Source: https://context7.com/boxpet/pygeomag/llms.txt

Use the `calculate()` method with latitude, longitude, altitude, and time to get magnetic field components. The result includes declination, inclination, and various intensity measures. Options are available to allow calculations outside the model's lifespan or to raise exceptions in warning zones.

```python
from pygeomag import GeoMag

geo_mag = GeoMag(coefficients_file="wmm/WMM_2025.COF")

# Calculate magnetic field at Space Needle, Seattle, WA
# glat: Geodetic Latitude (-90 to +90, North positive)
# glon: Geodetic Longitude (-180 to +180, East positive)
# alt: Altitude in km (-1 to 850, relative to WGS84 ellipsoid)
# time: Decimal year (e.g., 2025.25 = April 1, 2025)
result = geo_mag.calculate(
    glat=47.6205,      # Seattle latitude
    glon=-122.3493,    # Seattle longitude
    alt=0,             # Sea level
    time=2025.25       # April 2025
)

# Access magnetic field components
print(f"Declination (d): {result.d}°")      # 15.065629638512593
print(f"Inclination (i): {result.i}°")      # Dip angle
print(f"Total Intensity (f): {result.f} nT") # Total field strength
print(f"Horizontal Intensity (h): {result.h} nT")
print(f"North Component (x): {result.x} nT")
print(f"East Component (y): {result.y} nT")
print(f"Vertical Component (z): {result.z} nT")
print(f"Grid Variation (gv): {result.gv}")  # None if not in arctic/antarctic

# Check warning zones near magnetic poles
print(f"In blackout zone: {result.in_blackout_zone}")  # H < 2000 nT
print(f"In caution zone: {result.in_caution_zone}")    # H < 6000 nT

# Allow calculations outside the model's 5-year lifespan
result = geo_mag.calculate(
    glat=47.6205, glon=-122.3493, alt=0, time=2031.0,
    allow_date_outside_lifespan=True  # Allows estimation beyond validity
)

# Raise exceptions when in warning zones
try:
    result = geo_mag.calculate(
        glat=85.0, glon=0, alt=0, time=2025.5,
        raise_in_warning_zone=True
    )
except Exception as e:
    print(f"Warning: {e}")
```

--------------------------------

### Build Documentation with Sphinx

Source: https://github.com/boxpet/pygeomag/blob/main/CONTRIBUTING.rst

Build the project documentation using Sphinx. The -W flag will treat warnings as errors, ensuring documentation quality.

```bash
pip install -r docs/requirements.txt
sphinx-build -W -b html docs/ docs/build/html
```

--------------------------------

### Build Project Package

Source: https://github.com/boxpet/pygeomag/blob/main/docs/contributing.md

Create a distributable package for the project using the 'build' tool. This command is necessary before releasing or testing the package.

```bash
python -m build
```

--------------------------------

### Build Project Package

Source: https://github.com/boxpet/pygeomag/blob/main/CONTRIBUTING.rst

Build the project package for distribution. This step is required to ensure the project builds correctly.

```bash
pip install -r requirements-build.txt
python -m build
```

--------------------------------

### GeoMag Class Initialization

Source: https://context7.com/boxpet/pygeomag/llms.txt

Demonstrates various ways to initialize the GeoMag class, including using default coefficients, specifying a file, using data directly, auto-selecting by year, and using high-resolution models.

```APIDOC
## GeoMag Class Initialization

### Description
Initializes the `GeoMag` class, which is the primary interface for calculating geomagnetic field components. It can load WMM coefficient data in several ways.

### Method
`GeoMag(coefficients_file=None, coefficients_data=None, base_year=None, high_resolution=False)`

### Parameters
- **coefficients_file** (str) - Optional - Path to the WMM coefficients file (e.g., 'wmm/WMM_2025.COF').
- **coefficients_data** (dict) - Optional - WMM coefficients data loaded directly.
- **base_year** (int) - Optional - Year to automatically select the appropriate coefficients file.
- **high_resolution** (bool) - Optional - Set to True to use the high-resolution WMMHR model.

### Request Example
```python
from pygeomag import GeoMag

# Method 1: Use default (latest) coefficients file (WMM-2025)
geo_mag = GeoMag()

# Method 2: Specify a coefficients file explicitly
geo_mag = GeoMag(coefficients_file="wmm/WMM_2025.COF")

# Method 3: Use coefficients data directly (useful for microcontrollers)
from pygeomag.wmm.wmm_2025 import WMM_2025
geo_mag = GeoMag(coefficients_data=WMM_2025)

# Method 4: Auto-select coefficients based on a year
geo_mag = GeoMag(base_year=2023)  # Will use WMM_2020.COF

# Method 5: Use high resolution model (WMMHR 2025)
geo_mag = GeoMag(coefficients_file='wmm/WMMHR_2025.COF', high_resolution=True)
```

### Response
#### Success Response (200)
- **model** (str) - The WMM model being used (e.g., 'WMM-2025').
- **life_span** (tuple) - A tuple representing the start and end years of the model's validity.
- **release_date** (str) - The release date of the WMM model.

### Response Example
```python
# Assuming geo_mag is initialized
print(geo_mag.model)        # "WMM-2025"
print(geo_mag.life_span)    # (2025.0, 2030.0)
print(geo_mag.release_date) # "11/13/2024"
```
```

--------------------------------

### Initialize GeoMag with coefficients file

Source: https://github.com/boxpet/pygeomag/blob/main/README.rst

Initialize the GeoMag object with the WMM coefficients file. This is required before performing any geomagnetic calculations.

```python
>>> from pygeomag import GeoMag
>>> geo_mag = GeoMag(coefficients_file="wmm/WMM_2025.COF")
```

--------------------------------

### Generate Coverage Report

Source: https://github.com/boxpet/pygeomag/blob/main/CONTRIBUTING.rst

View code coverage in the console or generate HTML files to identify areas needing improvement.

```bash
python -m coverage report
```

```bash
python -m coverage html
```

--------------------------------

### Run Pytest with Coverage

Source: https://github.com/boxpet/pygeomag/blob/main/CONTRIBUTING.rst

Execute tests using pytest and generate code coverage reports. Ensure all tests pass and coverage is at 100% for your changes.

```bash
pip install -r requirements-test.txt
pytest --cov --xdoctest
```

--------------------------------

### Generate HTML Code Coverage Report

Source: https://github.com/boxpet/pygeomag/blob/main/docs/contributing.md

Build an HTML version of the code coverage report for a more detailed analysis. This is useful for visualizing untested code.

```bash
python -m coverage html
```

--------------------------------

### Initialize GeoMag Class

Source: https://context7.com/boxpet/pygeomag/llms.txt

Instantiate the GeoMag class using default coefficients, a specified file, embedded data, or by base year. For high-resolution models, set `high_resolution=True`.

```python
from pygeomag import GeoMag

# Method 1: Use default (latest) coefficients file (WMM-2025)
geo_mag = GeoMag()

# Method 2: Specify a coefficients file explicitly
geo_mag = GeoMag(coefficients_file="wmm/WMM_2025.COF")

# Method 3: Use coefficients data directly (useful for microcontrollers)
from pygeomag.wmm.wmm_2025 import WMM_2025
geo_mag = GeoMag(coefficients_data=WMM_2025)

# Method 4: Auto-select coefficients based on a year
geo_mag = GeoMag(base_year=2023)  # Will use WMM_2020.COF

# Method 5: Use high resolution model (WMMHR 2025)
geo_mag = GeoMag(coefficients_file='wmm/WMMHR_2025.COF', high_resolution=True)

# Access model information
print(geo_mag.model)        # "WMM-2025"
print(geo_mag.life_span)    # (2025.0, 2030.0)
print(geo_mag.release_date) # "11/13/2024"
```

--------------------------------

### Convert Decimal Degrees to Degrees Minutes Seconds

Source: https://context7.com/boxpet/pygeomag/llms.txt

Converts decimal degrees to degrees, minutes, and seconds format for precise coordinate display. Includes conversion back to decimal degrees.

```python
from pygeomag import decimal_degrees_to_degrees_minutes_seconds

# Convert latitude to DMS format
degrees, minutes, seconds = decimal_degrees_to_degrees_minutes_seconds(47.6205)
print(f"{degrees}° {minutes}' {seconds}"")  # 47° 37' 13.8"

# Convert longitude
degrees, minutes, seconds = decimal_degrees_to_degrees_minutes_seconds(-122.3493)
print(f"{degrees}° {minutes}' {seconds}"")  # -122° 20' 57.48"

# Convert back to decimal
from pygeomag import degrees_minutes_seconds_to_decimal_degrees
original = degrees_minutes_seconds_to_decimal_degrees(47, 37, 13.8)
print(f"Back to decimal: {original}")  # 47.6205
```

--------------------------------

### View Code Coverage Report

Source: https://github.com/boxpet/pygeomag/blob/main/docs/contributing.md

Generate a console report of code coverage using the coverage tool. This helps identify areas of the code that are not tested.

```bash
python -m coverage report
```

--------------------------------

### Calculate Historical Declination with WMM Coefficient Files

Source: https://context7.com/boxpet/pygeomag/llms.txt

Load specific WMM coefficient files to calculate magnetic declination for historical dates. Ensure the correct coefficient file is used for the desired time period.

```python
from pygeomag import GeoMag

# Seattle coordinates
lat, lon, alt = 47.6205, -122.3493, 0

# Calculate for 2013 using WMM-2010 (valid 2010-2015)
geo_mag_2010 = GeoMag(coefficients_file='wmm/WMM_2010.COF')
result_2013 = geo_mag_2010.calculate(glat=lat, glon=lon, alt=alt, time=2013.25)
print(f"2013 Declination: {result_2013.d:.4f}°")  # 16.4156°

# Calculate for 2017 using WMM-2015v2 (valid 2015-2020)
geo_mag_2015 = GeoMag(coefficients_file='wmm/WMM_2015v2.COF')
result_2017 = geo_mag_2015.calculate(glat=lat, glon=lon, alt=alt, time=2017.0)
print(f"2017 Declination: {result_2017.d:.4f}°")

# Calculate for 2023 using WMM-2020 (valid 2020-2025)
geo_mag_2020 = GeoMag(coefficients_file='wmm/WMM_2020.COF')
result_2023 = geo_mag_2020.calculate(glat=lat, glon=lon, alt=alt, time=2023.0)
print(f"2023 Declination: {result_2023.d:.4f}°")

# Calculate for 2026 using WMM-2025 (valid 2025-2030)
geo_mag_2025 = GeoMag(coefficients_file='wmm/WMM_2025.COF')
result_2026 = geo_mag_2025.calculate(glat=lat, glon=lon, alt=alt, time=2026.0)
print(f"2026 Declination: {result_2026.d:.4f}°")

# Available coefficient files:
# WMM.COF / WMM_2025.COF  - WMM-2025 (2025.0 - 2030.0)
# WMM_2020.COF            - WMM-2020 (2020.0 - 2025.0)
# WMM_2015v2.COF          - WMM-2015v2 (2015.0 - 2020.0)
# WMM_2015.COF            - WMM-2015 (2015.0 - 2020.0)
# WMM_2010.COF            - WMM-2010 (2010.0 - 2015.0)
# WMMHR.COF / WMMHR_2025.COF - High Resolution (2025.0 - 2030.0)
```

--------------------------------

### decimal_degrees_to_degrees_minutes_seconds() - Convert Decimal to DMS Format

Source: https://context7.com/boxpet/pygeomag/llms.txt

Converts decimal degrees to degrees, minutes, and seconds format for precise coordinate display.

```APIDOC
## decimal_degrees_to_degrees_minutes_seconds() - Convert Decimal to DMS Format

### Description
Converts decimal degrees to degrees, minutes, and seconds format for precise coordinate display.

### Method
`decimal_degrees_to_degrees_minutes_seconds(decimal_degrees)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from pygeomag import decimal_degrees_to_degrees_minutes_seconds

# Convert latitude to DMS format
degrees, minutes, seconds = decimal_degrees_to_degrees_minutes_seconds(47.6205)
print(f"{degrees}° {minutes}' {seconds}"")  # 47° 37' 13.8"

# Convert longitude
degrees, minutes, seconds = decimal_degrees_to_degrees_minutes_seconds(-122.3493)
print(f"{degrees}° {minutes}' {seconds}"")  # -122° 20' 57.48"

# Convert back to decimal
from pygeomag import degrees_minutes_seconds_to_decimal_degrees
original = degrees_minutes_seconds_to_decimal_degrees(47, 37, 13.8)
print(f"Back to decimal: {original}")  # 47.6205
```

### Response
#### Success Response (200)
- **degrees** (int) - The degree part of the coordinate.
- **minutes** (int) - The minute part of the coordinate.
- **seconds** (float) - The second part of the coordinate.
```

--------------------------------

### pretty_print_degrees() - Human-Readable Coordinate Formatting

Source: https://context7.com/boxpet/pygeomag/llms.txt

Formats decimal degrees into human-readable strings with compass directions (N/S/E/W), suitable for display in navigation applications.

```APIDOC
## pretty_print_degrees() - Human-Readable Coordinate Formatting

### Description
Formats decimal degrees into human-readable strings with compass directions (N/S/E/W), suitable for display in navigation applications.

### Method
`pretty_print_degrees(decimal_degrees, is_latitude, number_of_digits, show_seconds, full_words)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from pygeomag import pretty_print_degrees

# Basic latitude formatting
lat = 47.6205
formatted = pretty_print_degrees(decimal_degrees=lat, is_latitude=True)
print(formatted)  # "47° 37' N"

# Longitude formatting
lon = -122.3493
formatted = pretty_print_degrees(decimal_degrees=lon, is_latitude=False)
print(formatted)  # "122° 21' W"

# With decimal precision for minutes
formatted = pretty_print_degrees(
    decimal_degrees=47.6205,
    is_latitude=True,
    number_of_digits=2
)
print(formatted)  # "47° 37.23' N"

# Include seconds
formatted = pretty_print_degrees(
    decimal_degrees=47.6205,
    is_latitude=True,
    show_seconds=True,
    number_of_digits=1
)
print(formatted)  # "47° 37' 13.8" N"

# Full words mode
formatted = pretty_print_degrees(
    decimal_degrees=47.6205,
    is_latitude=True,
    full_words=True,
    number_of_digits=2
)
print(formatted)  # "47 Degrees 37.23 Minutes North"

# Southern latitude
formatted = pretty_print_degrees(decimal_degrees=-33.8688, is_latitude=True)
print(formatted)  # "33° 52' S"
```

### Response
#### Success Response (200)
- **formatted_string** (string) - The human-readable formatted coordinate string.
```

--------------------------------

### decimal_degrees_to_degrees_minutes() - Convert Decimal to DM Format

Source: https://context7.com/boxpet/pygeomag/llms.txt

Converts decimal degrees to degrees and minutes format, commonly used for GPS coordinates and navigation displays.

```APIDOC
## decimal_degrees_to_degrees_minutes() - Convert Decimal to DM Format

### Description
Converts decimal degrees to degrees and minutes format, commonly used for GPS coordinates and navigation displays.

### Method
`decimal_degrees_to_degrees_minutes(decimal_degrees)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from pygeomag import decimal_degrees_to_degrees_minutes

# Convert latitude 47.6205° to degrees and minutes
degrees, minutes = decimal_degrees_to_degrees_minutes(47.6205)
print(f"{degrees}° {minutes}'")  # 47° 37.23'

# Works with negative values (maintains sign in degrees)
degrees, minutes = decimal_degrees_to_degrees_minutes(-122.3493)
print(f"{degrees}° {minutes}'")  # -122° 20.958'

# Converting back to verify
from pygeomag import degrees_minutes_to_decimal_degrees
original = degrees_minutes_to_decimal_degrees(47, 37.23)
print(f"Back to decimal: {original}")  # 47.6205
```

### Response
#### Success Response (200)
- **degrees** (int) - The degree part of the coordinate.
- **minutes** (float) - The minute part of the coordinate.
```

--------------------------------

### Calculate Declination for WMM 2010

Source: https://github.com/boxpet/pygeomag/blob/main/docs/index.md

Calculates the geomagnetic declination at the Space Needle in Seattle, WA using the WMM 2010 coefficient file. Requires the 'wmm/WMM_2010.COF' file.

```python
from pygeomag import GeoMag
geo_mag = GeoMag(coefficients_file='wmm/WMM_2010.COF')
result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2013.25)
print(result.d)
```

--------------------------------

### Calculate Uncertainty Estimates

Source: https://context7.com/boxpet/pygeomag/llms.txt

The `calculate_uncertainty()` method on a `GeoMagResult` object provides estimates for the uncertainty of each magnetic field component based on the WMM error model.

```python
from pygeomag import GeoMag

geo_mag = GeoMag(coefficients_file="wmm/WMM_2025.COF")
result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2025.5)

# Calculate uncertainty values
uncertainty = result.calculate_uncertainty()

print(f"Declination uncertainty: ±{uncertainty.d:.4f}°")
print(f"Inclination uncertainty: ±{uncertainty.i:.4f}°")
print(f"North (X) uncertainty: ±{uncertainty.x} nT")
print(f"East (Y) uncertainty: ±{uncertainty.y} nT")
print(f"Vertical (Z) uncertainty: ±{uncertainty.z} nT")
print(f"Horizontal (H) uncertainty: ±{uncertainty.h} nT")
print(f"Total (F) uncertainty: ±{uncertainty.f} nT")

# Example output for WMM-2025:

```

--------------------------------

### Calculate Magnetic Field Values in CircuitPython

Source: https://github.com/boxpet/pygeomag/blob/main/docs/microcontrollers.md

Use this snippet to calculate magnetic declination and its uncertainty at a given geographic location and time. Ensure the GeoMag library and WMM coefficient data are imported.

```pycon
>>> from boxpet_geomag.geomag import GeoMag
>>> from boxpet_geomag.wmm_2020 import WMM_2020
>>> geo_mag = GeoMag(coefficients_data=WMM_2020)
>>> result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2023.75)
>>> print(result.d)
15.2594
>>> uncertainty = result.calculate_uncertainty()
>>> print(uncertainty.d)
0.39353
```

--------------------------------

### Format Decimal Degrees to Human-Readable Coordinates

Source: https://context7.com/boxpet/pygeomag/llms.txt

Formats decimal degrees into human-readable strings with compass directions (N/S/E/W). Supports options for decimal precision, showing seconds, and full word output.

```python
from pygeomag import pretty_print_degrees

# Basic latitude formatting
lat = 47.6205
formatted = pretty_print_degrees(decimal_degrees=lat, is_latitude=True)
print(formatted)  # "47° 37' N"

# Longitude formatting
lon = -122.3493
formatted = pretty_print_degrees(decimal_degrees=lon, is_latitude=False)
print(formatted)  # "122° 21' W"

# With decimal precision for minutes
formatted = pretty_print_degrees(
    decimal_degrees=47.6205,
    is_latitude=True,
    number_of_digits=2
)
print(formatted)  # "47° 37.23' N"

# Include seconds
formatted = pretty_print_degrees(
    decimal_degrees=47.6205,
    is_latitude=True,
    show_seconds=True,
    number_of_digits=1
)
print(formatted)  # "47° 37' 13.8" N"

# Full words mode
formatted = pretty_print_degrees(
    decimal_degrees=47.6205,
    is_latitude=True,
    full_words=True,
    number_of_digits=2
)
print(formatted)  # "47 Degrees 37.23 Minutes North"

# Southern latitude
formatted = pretty_print_degrees(decimal_degrees=-33.8688, is_latitude=True)
print(formatted)  # "33° 52' S"
```

--------------------------------

### Convert Decimal Degrees to Degrees Minutes

Source: https://context7.com/boxpet/pygeomag/llms.txt

Converts decimal degrees to degrees and minutes format. Works with positive and negative values, maintaining the sign in the degrees component.

```python
from pygeomag import decimal_degrees_to_degrees_minutes

# Convert latitude 47.6205° to degrees and minutes
degrees, minutes = decimal_degrees_to_degrees_minutes(47.6205)
print(f"{degrees}° {minutes}'")  # 47° 37.23'

# Works with negative values (maintains sign in degrees)
degrees, minutes = decimal_degrees_to_degrees_minutes(-122.3493)
print(f"{degrees}° {minutes}'")  # -122° 20.958'

# Converting back to verify
from pygeomag import degrees_minutes_to_decimal_degrees
original = degrees_minutes_to_decimal_degrees(47, 37.23)
print(f"Back to decimal: {original}")  # 47.6205
```

--------------------------------

### Calculate Declination for WMM 2025

Source: https://github.com/boxpet/pygeomag/blob/main/docs/index.md

Calculates the geomagnetic declination at the Space Needle in Seattle, WA using the WMM 2025 coefficient file. Requires the 'wmm/WMM_2025.COF' file.

```python
from pygeomag import GeoMag
geo_mag = GeoMag(coefficients_file="wmm/WMM_2025.COF")
result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2025.25)
print(result.d)
```

--------------------------------

### GeoMag.calculate()

Source: https://context7.com/boxpet/pygeomag/llms.txt

Calculates geomagnetic field components (declination, inclination, intensity) for a given location, altitude, and time.

```APIDOC
## GeoMag.calculate()

### Description
Computes all magnetic field components for a given geographic location, altitude, and time using the loaded WMM coefficients. Returns a `GeoMagResult` object.

### Method
`calculate(glat, glon, alt, time, allow_date_outside_lifespan=False, raise_in_warning_zone=False)`

### Parameters
#### Path Parameters
- **glat** (float) - Geodetic Latitude (-90 to +90, North positive).
- **glon** (float) - Geodetic Longitude (-180 to +180, East positive).
- **alt** (float) - Altitude in km (-1 to 850, relative to WGS84 ellipsoid).
- **time** (float) - Decimal year (e.g., 2025.25 for April 1, 2025).

#### Query Parameters
- **allow_date_outside_lifespan** (bool) - Optional - If True, allows calculations outside the model's 5-year lifespan (estimation).
- **raise_in_warning_zone** (bool) - Optional - If True, raises an exception when the calculation is within a warning zone (e.g., near magnetic poles).

### Request Example
```python
from pygeomag import GeoMag

geo_mag = GeoMag(coefficients_file="wmm/WMM_2025.COF")

# Calculate magnetic field at Space Needle, Seattle, WA
result = geo_mag.calculate(
    glat=47.6205,
    glon=-122.3493,
    alt=0,
    time=2025.25
)

# Allow calculations outside the model's 5-year lifespan
result_future = geo_mag.calculate(
    glat=47.6205, glon=-122.3493, alt=0, time=2031.0,
    allow_date_outside_lifespan=True
)

# Raise exceptions when in warning zones
try:
    result_warning = geo_mag.calculate(
        glat=85.0, glon=0, alt=0, time=2025.5,
        raise_in_warning_zone=True
    )
except Exception as e:
    print(f"Warning: {e}")
```

### Response
#### Success Response (200)
- **d** (float) - Declination in degrees.
- **i** (float) - Inclination in degrees.
- **f** (float) - Total Intensity in nT.
- **h** (float) - Horizontal Intensity in nT.
- **x** (float) - North Component (X) in nT.
- **y** (float) - East Component (Y) in nT.
- **z** (float) - Vertical Component (Z) in nT.
- **gv** (float or None) - Grid Variation in degrees, or None if not in arctic/antarctic.
- **in_blackout_zone** (bool) - True if Horizontal Intensity is less than 2000 nT.
- **in_caution_zone** (bool) - True if Horizontal Intensity is less than 6000 nT.

#### Response Example
```python
# Assuming result is the output of geo_mag.calculate()
print(f"Declination (d): {result.d}°")
print(f"Inclination (i): {result.i}°")
print(f"Total Intensity (f): {result.f} nT")
print(f"Horizontal Intensity (h): {result.h} nT")
print(f"North Component (x): {result.x} nT")
print(f"East Component (y): {result.y} nT")
print(f"Vertical Component (z): {result.z} nT")
print(f"Grid Variation (gv): {result.gv}")
print(f"In blackout zone: {result.in_blackout_zone}")
print(f"In caution zone: {result.in_caution_zone}")
```
```

--------------------------------

### round_to_digits() - Precision Rounding

Source: https://context7.com/boxpet/pygeomag/llms.txt

Rounds numbers to a specified number of decimal places using standard rounding (not Python's round-to-even). Useful for display formatting.

```APIDOC
## round_to_digits() - Precision Rounding

### Description
Rounds numbers to a specified number of decimal places using standard rounding (not Python's round-to-even). Useful for display formatting.

### Method
`round_to_digits(number, number_of_digits)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from pygeomag import round_to_digits

# Round to whole number
result = round_to_digits(45.7625, 0)
print(result)  # 46 (returns int when number_of_digits=0)

# Round to 1 decimal place
result = round_to_digits(45.7625, 1)
print(result)  # 45.8

# Round to 2 decimal places
result = round_to_digits(45.7625, 2)
print(result)  # 45.76

# Works with negative numbers
result = round_to_digits(-45.7625, 1)
print(result)  # -45.8

# Standard rounding, not round-to-even
result = round_to_digits(2.5, 0)
print(result)  # 3 (Python's round() would give 2)
```

### Response
#### Success Response (200)
- **rounded_number** (float or int) - The number rounded to the specified number of decimal places.
```

--------------------------------

### Round Numbers to Specified Decimal Places

Source: https://context7.com/boxpet/pygeomag/llms.txt

Rounds numbers to a specified number of decimal places using standard rounding rules (rounds .5 up). Returns an integer when zero decimal places are specified.

```python
from pygeomag import round_to_digits

# Round to whole number
result = round_to_digits(45.7625, 0)
print(result)  # 46 (returns int when number_of_digits=0)

# Round to 1 decimal place
result = round_to_digits(45.7625, 1)
print(result)  # 45.8

# Round to 2 decimal places
result = round_to_digits(45.7625, 2)
print(result)  # 45.76

# Works with negative numbers
result = round_to_digits(-45.7625, 1)
print(result)  # -45.8

# Standard rounding, not round-to-even
result = round_to_digits(2.5, 0)
print(result)  # 3 (Python's round() would give 2)
```

--------------------------------

### GeoMagResult.calculate_uncertainty()

Source: https://context7.com/boxpet/pygeomag/llms.txt

Calculates uncertainty estimates for the magnetic field components based on the WMM error model.

```APIDOC
## GeoMagResult.calculate_uncertainty()

### Description
Calculates uncertainty values for a `GeoMagResult` object using the WMM error model. Provides uncertainty estimates for all magnetic field components.

### Method
`calculate_uncertainty()`

### Parameters
This method does not take any parameters.

### Request Example
```python
from pygeomag import GeoMag

geo_mag = GeoMag(coefficients_file="wmm/WMM_2025.COF")
result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2025.5)

# Calculate uncertainty values
uncertainty = result.calculate_uncertainty()
```

### Response
#### Success Response (200)
- **d** (float) - Declination uncertainty in degrees.
- **i** (float) - Inclination uncertainty in degrees.
- **x** (float) - North (X) component uncertainty in nT.
- **y** (float) - East (Y) component uncertainty in nT.
- **z** (float) - Vertical (Z) component uncertainty in nT.
- **h** (float) - Horizontal (H) component uncertainty in nT.
- **f** (float) - Total (F) component uncertainty in nT.

#### Response Example
```python
# Assuming uncertainty is the output of result.calculate_uncertainty()
print(f"Declination uncertainty: ±{uncertainty.d:.4f}°")
print(f"Inclination uncertainty: ±{uncertainty.i:.4f}°")
print(f"North (X) uncertainty: ±{uncertainty.x} nT")
print(f"East (Y) uncertainty: ±{uncertainty.y} nT")
print(f"Vertical (Z) uncertainty: ±{uncertainty.z} nT")
print(f"Horizontal (H) uncertainty: ±{uncertainty.h} nT")
print(f"Total (F) uncertainty: ±{uncertainty.f} nT")
```
```

--------------------------------

### High Resolution Geomagnetic Model Calculation

Source: https://context7.com/boxpet/pygeomag/llms.txt

Utilize the high-resolution WMMHR model for more accurate magnetic field calculations. This model uses significantly more coefficients than the standard WMM. The `high_resolution=True` flag must be set during GeoMag initialization.

```python
from pygeomag import GeoMag

# Initialize with high resolution model
geo_mag_hr = GeoMag(coefficients_file='wmm/WMMHR_2025.COF', high_resolution=True)

# Calculate declination at Seattle
result = geo_mag_hr.calculate(
    glat=47.6205,
    glon=-122.3493,
    alt=0,
    time=2025.0
)

print(f"Declination (HR): {result.d}°")  # 15.017316292177854
print(f"Is high resolution: {result.is_high_resolution}")  # True

# Compare with standard resolution
geo_mag_std = GeoMag(coefficients_file='wmm/WMM_2025.COF')
result_std = geo_mag_std.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2025.0)
print(f"Declination (Std): {result_std.d}°")

# Calculate uncertainty for high resolution model
uncertainty = result.calculate_uncertainty()
print(f"Declination uncertainty (HR): ±{uncertainty.d:.4f}°")
```

--------------------------------

### Calculate Declination with High Resolution Model

Source: https://github.com/boxpet/pygeomag/blob/main/docs/index.md

Calculates the geomagnetic declination using the high-resolution WMMHR 2025 model. Requires the 'wmm/WMMHR_2025.COF' file and setting 'high_resolution=True'.

```python
from pygeomag import GeoMag
geo_mag = GeoMag(coefficients_file='wmm/WMMHR_2025.COF', high_resolution=True)
result = geo_mag.calculate(glat=47.6205, glon=-122.3493, alt=0, time=2025.00)
print(result.d)
```

--------------------------------

### Convert Dates to Decimal Year

Source: https://context7.com/boxpet/pygeomag/llms.txt

Converts datetime objects, date objects, struct_time, Unix timestamps, and float/int years to a decimal year format. Handles leap years automatically.

```python
import datetime
import time
from pygeomag import calculate_decimal_year, decimal_year_from_date, decimal_year_from_struct_time

# From datetime object
dt = datetime.datetime(2025, 7, 2)
decimal_year = calculate_decimal_year(dt)
print(f"Decimal year: {decimal_year}")  # 2025.5 (middle of year)

# From date object
d = datetime.date(2025, 1, 1)
decimal_year = decimal_year_from_date(d)
print(f"Decimal year: {decimal_year}")  # 2025.0

# From struct_time (useful for MicroPython)
st = time.struct_time((2025, 7, 2, 0, 0, 0, 0, 0, 0))
decimal_year = decimal_year_from_struct_time(st)
print(f"Decimal year: {decimal_year}")  # 2025.5

# From Unix timestamp
timestamp = 1735689600  # Jan 1, 2025
decimal_year = calculate_decimal_year(timestamp)

# Pass float/int directly (values < 3000 assumed to be years)
decimal_year = calculate_decimal_year(2025.75)
print(f"Decimal year: {decimal_year}")  # 2025.75
```

--------------------------------

### calculate_decimal_year() - Convert Dates to Decimal Year

Source: https://context7.com/boxpet/pygeomag/llms.txt

Converts various date formats (datetime, date, struct_time, timestamps) to decimal year format. Handles leap years automatically.

```APIDOC
## calculate_decimal_year() - Convert Dates to Decimal Year

### Description
Converts various date formats (datetime, date, struct_time, timestamps) to decimal year format required by `GeoMag.calculate()`. Handles leap years automatically.

### Method
`calculate_decimal_year(date_input)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import datetime
import time
from pygeomag import calculate_decimal_year, decimal_year_from_date, decimal_year_from_struct_time

# From datetime object
dt = datetime.datetime(2025, 7, 2)
decimal_year = calculate_decimal_year(dt)
print(f"Decimal year: {decimal_year}")  # 2025.5 (middle of year)

# From date object
d = datetime.date(2025, 1, 1)
decimal_year = decimal_year_from_date(d)
print(f"Decimal year: {decimal_year}")  # 2025.0

# From struct_time (useful for MicroPython)
st = time.struct_time((2025, 7, 2, 0, 0, 0, 0, 0, 0))
decimal_year = decimal_year_from_struct_time(st)
print(f"Decimal year: {decimal_year}")  # 2025.5

# From Unix timestamp
timestamp = 1735689600  # Jan 1, 2025
decimal_year = calculate_decimal_year(timestamp)

# Pass float/int directly (values < 3000 assumed to be years)
decimal_year = calculate_decimal_year(2025.75)
print(f"Decimal year: {decimal_year}")  # 2025.75
```

### Response
#### Success Response (200)
- **decimal_year** (float) - The date represented as a decimal year.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.