fr.cnes.sirius.patrius.models.earth

Class GeoMagneticField

java.lang.Object

fr.cnes.sirius.patrius.models.earth.GeoMagneticField

public class GeoMagneticField
extends Object

Used to calculate the geomagnetic field at a given geodetic point on earth. The calculation is estimated using spherical harmonic expansion of the geomagnetic potential with coefficients provided by an actual geomagnetic field model (e.g. IGRF, WMM).

Based on original software written by Manoj Nair from the National Geophysical Data Center, NOAA, as part of the WMM 2010 software release (WMM_SubLibrary.c)

Author:

Thomas Neidhart

See Also:

World Magnetic Model Overview, WMM Software Downloads

Constructor Summary

Constructors

Constructor and Description
GeoMagneticField(String modelNameIn, double epochIn, int maxNIn, int maxNSecIn, double validityStartIn, double validityEndIn) Create a new geomagnetic field model with the given parameters.

Method Summary

Modifier and Type	Method and Description
GeoMagneticElements	calculateField(double latitude, double longitude, double height) Calculate the magnetic field at the specified geodetic point identified by latitude, longitude and altitude.
GeoMagneticElements	calculateField(GeodeticPoint gp) Calculate the magnetic field at the specified geodetic point identified by geodetic objet.
GeoMagneticElements	calculateField(Vector3D point, Frame frame, AbsoluteDate date) Calculate the magnetic field at the specified point identified by the coordinates of the point and the reference point.
static double	getDecimalYear(AbsoluteDate date) Utility function to get a decimal year for a given AbsoluteDate.
static double	getDecimalYear(int day, int month, int year) Utility function to get a decimal year for a given day.
double	getEpoch() Returns the epoch for this magnetic field model.
String	getModelName() Returns the model name.
void	setMainFieldCoefficients(int n, int m, double gnm, double hnm) Set the given main field coefficients.
void	setSecularVariationCoefficients(int n, int m, double dgnm, double dhnm) Set the given secular variation coefficients.
boolean	supportsTimeTransform() Indicates whether this model supports time transformation or not.
GeoMagneticField	transformModel(double year) Time transform the model coefficients from the base year of the model using secular variation coefficients.
GeoMagneticField	transformModel(GeoMagneticField otherModel, double year) Time transform the model coefficients from the base year of the model using a linear interpolation with a second model.
double	validFrom() Returns the start of the validity period for this model.
double	validTo() Returns the end of the validity period for this model.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

GeoMagneticField

public GeoMagneticField(String modelNameIn,
                        double epochIn,
                        int maxNIn,
                        int maxNSecIn,
                        double validityStartIn,
                        double validityEndIn)

Create a new geomagnetic field model with the given parameters. Internal structures are initialized according to the specified degrees of the main and secular variations.

Parameters:

modelNameIn - the model name

epochIn - the base time of magnetic field model epoch (yrs)

maxNIn - the maximum degree of the main model

maxNSecIn - the maximum degree of the secular variations

validityStartIn - validity start of this model

validityEndIn - validity end of this model

Method Detail

getEpoch

public double getEpoch()

Returns the epoch for this magnetic field model.

Returns:

the epoch

getModelName

public String getModelName()

Returns the model name.

Returns:

the model name

validFrom

public double validFrom()

Returns the start of the validity period for this model.

Returns:

the validity start as decimal year

validTo

public double validTo()

Returns the end of the validity period for this model.

Returns:

the validity end as decimal year

supportsTimeTransform

public boolean supportsTimeTransform()

Indicates whether this model supports time transformation or not.

Returns:

true if this model can be transformed within its validity period, false otherwise

setMainFieldCoefficients

public void setMainFieldCoefficients(int n,
                                     int m,
                                     double gnm,
                                     double hnm)

Set the given main field coefficients.

Parameters:

n - the degree

m - the order

gnm - the g coefficient at position n,m

hnm - the h coefficient at position n,m

setSecularVariationCoefficients

public void setSecularVariationCoefficients(int n,
                                            int m,
                                            double dgnm,
                                            double dhnm)

Set the given secular variation coefficients.

Parameters:

n - the degree

m - the order

dgnm - the dg coefficient at position n,m

dhnm - the dh coefficient at position n,m

calculateField

public GeoMagneticElements calculateField(double latitude,
                                          double longitude,
                                          double height)

Calculate the magnetic field at the specified geodetic point identified by latitude, longitude and altitude.

Parameters:

latitude - the latitude in decimal degrees

longitude - the longitude in decimal degrees

height - the altitude in kilometers above mean sea level

Returns:

the GeoMagneticElements at the given geodetic point

calculateField

public GeoMagneticElements calculateField(GeodeticPoint gp)

Calculate the magnetic field at the specified geodetic point identified by geodetic objet.

Parameters:

gp - geodetic point

Returns:

the GeoMagneticElements at the given geodetic point

calculateField

public GeoMagneticElements calculateField(Vector3D point,
                                          Frame frame,
                                          AbsoluteDate date)
                                   throws PatriusException

Calculate the magnetic field at the specified point identified by the coordinates of the point and the reference point.

Parameters:

point - cartesian point

frame - frame in which cartesian point is expressed

date - date in which cartesian point is given

Returns:

the GeoMagneticElements at the given cartesian point

Throws:

PatriusException - if point cannot be converted to body frame

PatriusException - if the specified year is outside the validity period

PatriusException - if getDecimalYear() error occurred

transformModel

public GeoMagneticField transformModel(double year)
                                throws PatriusException

Time transform the model coefficients from the base year of the model using secular variation coefficients.

Parameters:

year - the year to which the model shall be transformed

Returns:

a time-transformed magnetic field model

Throws:

PatriusException - if the specified year is outside the validity period of the model or the model does not support time transformations (i.e. no secular variations available)

transformModel

public GeoMagneticField transformModel(GeoMagneticField otherModel,
                                       double year)
                                throws PatriusException

Time transform the model coefficients from the base year of the model using a linear interpolation with a second model. The second model is required to have an adjacent validity period.

Parameters:

otherModel - the other magnetic field model

year - the year to which the model shall be transformed

Returns:

a time-transformed magnetic field model

Throws:

PatriusException - if the specified year is outside the validity period of the model or the model does not support time transformations (i.e. no secular variations available)

getDecimalYear

public static double getDecimalYear(AbsoluteDate date)
                             throws PatriusException

Utility function to get a decimal year for a given AbsoluteDate.

Parameters:

date - date in AbsoluteDate format

Returns:

the decimal year represented by the given day

Throws:

PatriusException - if TimeScalesFactory error occurred

getDecimalYear

public static double getDecimalYear(int day,
                                    int month,
                                    int year)

Utility function to get a decimal year for a given day.

Parameters:

day - the day (1-31)

month - the month (1-12)

year - the year

Returns:

the decimal year represented by the given day