Class: QgsMagneticModel

Represents a model of the Earth’s magnetic field.

Warning

This class is only usable if QGIS was built with GeographicLib support. If not, then QgsNotSupportedException exceptions will be raised when calling the methods for this class.

The Qgis.hasGeographicLib() method can be used to determine if QGIS was built with GeographicLib support.

Added in version 4.0.

List of all members, including inherited members

Methods

dateTime	Returns the date of the magnetic model, if available.
declination	Calculates the declination of the field at a point.
defaultFilePath	Returns the default path used by GeographicLib to search for magnetic models.
defaultModelName	Returns the name of the default magnetic model used by GeographicLib.
degree	Returns the maximum degree of the components of the model.
description	Returns the description of the magnetic model, if available.
directory	Returns the full directory name containing the magnetic model file.
error	Returns a string for the last error encountered by the model.
file	Returns the full file name for the magnetic model.
getComponents	Evaluates the components of the geomagnetic field at a point.
getComponentsWithTimeDerivatives	Evaluates the components of the geomagnetic field at a point, and their time derivatives.
inclination	Calculates the inclination of the field at a point.
isValid	Returns True if the model is valid and can be used.
maximumHeight	Returns the maximum height above the ellipsoid (in meters) for which the model should be used.
maximumYear	Returns the maximum time (in decimal years) for which the model should be used.
minimumHeight	Returns the minimum height above the ellipsoid (in meters) for which the model should be used.
minimumYear	Returns the minimum time (in decimal years) for which the model should be used.
name	Returns the name of the magnetic model.
order	Returns the maximum order of the components of the model.

Static Methods

fieldComponents	Compute various quantities dependent on a magnetic field.
fieldComponentsWithTimeDerivatives	Compute various quantities dependent on a magnetic field and their rates of change.

class qgis.core.QgsMagneticModel

Bases: object

__init__(name: str | None, path: str | None = '', maxDegree: int = -1, maxOrder: int = -1)

Constructor for QgsMagneticModel.

A filename is formed by appending “.wmm” (World Magnetic Model) to the name argument.

If path is specified (and is non-empty), then the associated file is loaded from this path. Otherwise the file path is given by the defaultFilePath().

The associated file must exist and point to a valid magnetic model file. If not, then isValid() will return False and a descriptive error can be retrieved by error().

If maxDegree ≥ 0 and maxOrder < 0, then maxOrder is set to maxDegree. After the model is loaded, the maximum degree and order of the model can be found by the degree() and order() methods.

Parameters:

• name (Optional[str]) – the name of the model.

• path (Optional[str] = '') – optional directory for data file. If not specified then defaultFilePath() is used.

• maxDegree (int = -1) – if nonnegative, truncate the degree of the model to this value

• maxOrder (int = -1) – if nonnegative, truncate the order of the model to this value

dateTime(self) → QDateTime

Returns the date of the magnetic model, if available.

Raises:

QgsNotSupportedException – if GeographicLib is not available

Return type:

QDateTime

declination(self, years: float, latitude: float, longitude: float, height: float)

Calculates the declination of the field at a point.

Note

The latitude and longitude should be specified as a WGS84 coordinate

Note

If calculating both the inclination and declination at the same point it is more efficient to use getComponents() and fieldComponents()

Parameters:

• years (float) – the time (in fractional years)

• latitude (float) – latitude of the point (in decimal degrees)

• longitude (float) – longitude of the point (in decimal degrees)

• height (float) – height of the point above the ellipsoid (in meters)

Return type:

(bool, float)

Returns:

• True if declination was successfully calculated

• declination: magnetic field declination, in degrees east of north

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

inclination()

defaultFilePath() → str

Returns the default path used by GeographicLib to search for magnetic models.

See also

defaultModelName()

Return type:

str

defaultModelName() → str

Returns the name of the default magnetic model used by GeographicLib.

See also

defaultFilePath()

Return type:

str

degree(self) → int

Returns the maximum degree of the components of the model.

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

order()

Return type:

int

description(self) → str

Returns the description of the magnetic model, if available.

Raises:

QgsNotSupportedException – if GeographicLib is not available

Return type:

str

directory(self) → str

Returns the full directory name containing the magnetic model file.

Raises:

QgsNotSupportedException – if GeographicLib is not available

Return type:

str

error(self) → str

Returns a string for the last error encountered by the model.

Return type:

str

static fieldComponents(Bx: float, By: float, Bz: float)

Compute various quantities dependent on a magnetic field.

Parameters:

• Bx (float) – the easterly component of the magnetic field (in nanotesla)

• By (float) – the northerly component of the magnetic field (in nanotesla)

• Bz (float) – the vertical (up) component of the magnetic field (in nanotesla)

Return type:

(bool, float, float, float, float)

Returns:

• True if the components were successfully calculated

• H: the horizontal magnetic field (in nanotesla)

• F: the total magnetic field (in nanotesla)

• D: the declination of the field (degrees east of north)

• I: the inclination of the field (degrees down from horizontal)

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

fieldComponentsWithTimeDerivatives()

static fieldComponentsWithTimeDerivatives(Bx: float, By: float, Bz: float, Bxt: float, Byt: float, Bzt: float)

Compute various quantities dependent on a magnetic field and their rates of change.

Parameters:

• Bx (float) – the easterly component of the magnetic field (in nanotesla)

• By (float) – the northerly component of the magnetic field (in nanotesla)

• Bz (float) – the vertical (up) component of the magnetic field (in nanotesla)

• Bxt (float) – the rate of change of Bx (nT/yr)

• Byt (float) – the rate of change of By (nT/yr)

• Bzt (float) – the rate of change of Bz (nT/yr)

Return type:

(bool, float, float, float, float, float, float, float, float)

Returns:

• True if the components were successfully calculated

• H: the horizontal magnetic field (in nanotesla)

• F: the total magnetic field (in nanotesla)

• D: the declination of the field (degrees east of north)

• I: the inclination of the field (degrees down from horizontal)

• Ht: the rate of change of H (nT/yr)

• Ft: the rate of change of F (nT/yr)

• Dt: the rate of change of D (degrees/yr)

• It: the rate of change of I (degrees/yr)

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

fieldComponentsWithTimeDerivatives()

file(self) → str

Returns the full file name for the magnetic model.

Raises:

QgsNotSupportedException – if GeographicLib is not available

Return type:

str

getComponents(self, years: float, latitude: float, longitude: float, height: float)

Evaluates the components of the geomagnetic field at a point.

Note

The latitude and longitude should be specified as a WGS84 coordinate

Parameters:

• years (float) – the time (in fractional years)

• latitude (float) – latitude of the point (in decimal degrees)

• longitude (float) – longitude of the point (in decimal degrees)

• height (float) – height of the point above the ellipsoid (in meters)

Return type:

(bool, float, float, float)

Returns:

• True if the components were successfully calculated

• Bx: the easterly component of the magnetic field (in nanotesla).

• By: the northerly component of the magnetic field (in nanotesla)

• Bz: the vertical (up) component of the magnetic field (in nanotesla)

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

getComponentsWithTimeDerivatives()

getComponentsWithTimeDerivatives(self, years: float, latitude: float, longitude: float, height: float)

Evaluates the components of the geomagnetic field at a point, and their time derivatives.

Note

The latitude and longitude should be specified as a WGS84 coordinate

Parameters:

• years (float) – the time (in fractional years)

• latitude (float) – latitude of the point (in decimal degrees)

• longitude (float) – longitude of the point (in decimal degrees)

• height (float) – height of the point above the ellipsoid (in meters)

Return type:

(bool, float, float, float, float, float, float)

Returns:

• True if the components were successfully calculated

• Bx: the easterly component of the magnetic field (in nanotesla).

• By: the northerly component of the magnetic field (in nanotesla)

• Bz: the vertical (up) component of the magnetic field (in nanotesla)

• Bxt: the rate of change of Bx (nT/yr)

• Byt: the rate of change of By (nT/yr)

• Bzt: the rate of change of Bz (nT/yr)

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

getComponents()

inclination(self, years: float, latitude: float, longitude: float, height: float)

Calculates the inclination of the field at a point.

Note

The latitude and longitude should be specified as a WGS84 coordinate

Note

If calculating both the inclination and declination at the same point it is more efficient to use getComponents() and fieldComponents()

Parameters:

• years (float) – the time (in fractional years)

• latitude (float) – latitude of the point (in decimal degrees)

• longitude (float) – longitude of the point (in decimal degrees)

• height (float) – height of the point above the ellipsoid (in meters)

Return type:

(bool, float)

Returns:

• True if inclination was successfully calculated

• inclination: magnetic field inclination, in degrees down from horizontal

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

declination()

isValid(self) → bool

Returns True if the model is valid and can be used.

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

error()

Return type:

bool

maximumHeight(self) → float

Returns the maximum height above the ellipsoid (in meters) for which the model should be used.

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

minimumHeight()

Return type:

float

maximumYear(self) → float

Returns the maximum time (in decimal years) for which the model should be used.

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

minimumYear()

Return type:

float

minimumHeight(self) → float

Returns the minimum height above the ellipsoid (in meters) for which the model should be used.

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

maximumHeight()

Return type:

float

minimumYear(self) → float

Returns the minimum time (in decimal years) for which the model should be used.

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

maximumYear()

Return type:

float

name(self) → str

Returns the name of the magnetic model.

Raises:

QgsNotSupportedException – if GeographicLib is not available

Return type:

str

order(self) → int

Returns the maximum order of the components of the model.

Raises:

QgsNotSupportedException – if GeographicLib is not available

See also

degree()

Return type:

int