inertialsim.sensors.magnetometer

Magnetometer simulation.

Classes:

Name	Description
MagnetometerSpecification	Magnetometer specification.
MagnetometerModel	Sensor model options.
Magnetometer	Simulate magnetometer sensors.

MagnetometerSpecification

MagnetometerSpecification(axes: int = NUM_CARTESIAN_AXES)

Bases: SensorSpecification

Magnetometer specification.

A magnetometer specification includes the parameters required to simulate magnetometer response to ideal inputs. These include input limits, noise coefficients, biases, scale factors, and internal sensor misalignments.

By default the specification returns a perfect sensor whose output will precisely match its sensed input.

Classes:

Name	Description
ScaleFactor	Sensor scale factor specification.
Misalignment	Sensor misalignment specification.
DataInterface	Magnetometer data interface specification.
InputLimits	Magnetometer input limits specification.
Noise	Magnetometer noise specification.
Bias	Magnetometer bias specification.

Attributes:

Name	Type	Description
manufacturer	str	Manufacturer of the sensor.
model	str	Model number/identifier of the sensor.
version	str	Version number/identifier of the sensor.
scale_factor	ScaleFactor	Sensor scale factor specification.
misalignment	Misalignment	Sensor misalignment specification.
axes	int	Number of independent sensing axes of the sensor.
data_interface	DataInterface	Magnetometer data interface specification.
input_limits	InputLimits	Magnetometer input limits specification.
noise	Noise	Magnetometer noise specification.
bias	Bias	Magnetometer bias specification.

manufacturer instance-attribute

manufacturer: str = ''

Manufacturer of the sensor.

model instance-attribute

model: str = ''

Model number/identifier of the sensor.

version instance-attribute

version: str = ''

Version number/identifier of the sensor.

scale_factor instance-attribute

scale_factor: ScaleFactor = ScaleFactor(axes)

Sensor scale factor specification.

misalignment instance-attribute

misalignment: Misalignment = Misalignment(axes)

Sensor misalignment specification.

axes property

axes: int

Number of independent sensing axes of the sensor.

data_interface instance-attribute

data_interface: DataInterface = DataInterface(axes)

Magnetometer data interface specification.

input_limits instance-attribute

input_limits: InputLimits = InputLimits(axes)

Magnetometer input limits specification.

noise instance-attribute

noise: Noise = Noise(axes)

Magnetometer noise specification.

bias instance-attribute

bias: Bias = Bias(axes)

Magnetometer bias specification.

ScaleFactor

ScaleFactor(axes: int)

Sensor scale factor specification.

Scale factor is the ratio of change in output to change in input at the analog sensing elements.

A perfect sensor has a linear analog response with a scale of 1.0. Imperfect sensors may have a non-unit scale.

Attributes:

Name	Type	Description
fixed	Parameter	Fixed scale factor error.
repeatability	Parameter	Random scale factor error.

fixed property writable

fixed: Parameter

Fixed scale factor error.

A fixed offset from the ideal unit scale factor (1.0) that is constant across all conditions. For many sensors, this may be removed by factory calibration in which case this parameter can represent any known residual error in that calibration. Units are ratios of similar quantities so must be one of: "dimensionless", "%", or "ppm". Default value = Parameter([0.0,0.0,0.0], "dimensionless").

repeatability property writable

repeatability: Parameter

Random scale factor error.

The standard deviation of a random scale factor error that varies with each turn-on of the sensor and/or varies across external conditions. This parameter may represent unknown residuals from the factory calibration of fixed scale factor. Units are ratios of similar quantities so must be one of: "dimensionless", "%", or "ppm". Default value = Parameter([0.0,0.0,0.0], "dimensionless").

Misalignment

Misalignment(axes: int)

Sensor misalignment specification.

Misalignment is the offset between the ideal orthogonal input reference axes (IRA) and the actual sensitive input axis (IA) of the sensor. It is comprised of a fixed component (that can be calibrated) and a random component (that may vary from turn-on to turn-on or with changing conditions).

See Standard [05] and Standard [06] for details.

Attributes:

Name	Type	Description
fixed	Parameter	Fixed sensor alignment.
repeatability	Parameter	Random sensor misalignment.

fixed property writable

fixed: Parameter

Fixed sensor alignment.

Coordinate transform matrix converting 3-dimensional input reference axes (IRA) to N-dimensional input axes (IA). IRA are also known as platform axes and the IA are also known as accelerometer, gyro, or sensor axes. The resulting matrix is Nx3 where N is the number of measurement axes of the device. For an ideal sensor this will typically be an identity matrix. For real sensors, the deviation from identity represents the misalignment. This fixed misalignment may be removed by factory calibration in which case this parameter can represent any residual error in that calibration. Units must be "dimensionless". For sensors with <= 3 axes, the default value is a one-to-one map of input axes to the available output axes. For example, in a default 2-axis sensor input x-y axes map to output x-y axes: Parameter([[1,0,0],[0,1,0]],"dimensionless"). The input z-axis is not sensed. For sensors with > 3 axes, inputs are duplicated in sequence to fill the output. For example, by default a 4-axis sensor will duplicate the x input: Parameter([[1,0,0],[0,1,0],[0,0,1],[1,0,0]],"dimensionless"). This is typically not how redundant sensor designs are aligned so users should take care to supply the correct input in these cases. An example of a single axis sensor with a fixed, known misalignment is: Parameter([0.999,0.02,-0.04],"dimensionless"). This maps IRA inputs to a single output with a known misalignment. Default value = Parameter(np.eye(3), "rad").

repeatability property writable

repeatability: Parameter

Random sensor misalignment.

Standard deviation of a (small) random angle offset applied to the each input axis (IA). Each axis is independently rotated, meaning that the result is non-orthogonal. The random offset is applied as a rotation vector with components sampled independently around each of the 3 input reference axes (IRA). For example, a single axis sensor has a default fixed axis of: Parameter([1,0,0],"dimensionless"). That axis will be rotated according to:

rotation_vector = repeatability * rng.std_normal(shape=(3,1))
axis = Rotation.from_rotation_vector(rotation_vector) @ [1,0,0]

The result will be a slightly misaligned axis such as: Parameter([0.999,0.02,-0.04],"dimensionless"). This process is repeated for each axis. This parameter may represent an unknown residual from the factory calibration or an offset that varies with changing conditions like packaging stress and shock. Units must be one of: "rad" or "deg". Default value = Parameter([0.0,0.0,0.0], "rad") per axis.

DataInterface

DataInterface(axes: int)

Bases: DataInterface

Magnetometer data interface specification.

The data interface of the magnetometer. The magnetometer interface includes the sample rate, which is the frequency at which the sensor transmits new data and any digital quantization in the data.

Attributes:

Name	Type	Description
sample_rate	Parameter	The frequency at which new data is output from the sensor.
quantization	Parameter | None	Data interface rate output quantization.

sample_rate property writable

sample_rate: Parameter

The frequency at which new data is output from the sensor.

Units must be "Hz". Default value = Parameter(100, "Hz").

quantization property writable

quantization: Parameter | None

Data interface rate output quantization.

Outputs will be quantized at simulated digital levels. Units must be one of: "T/LSB", or "gauss/LSB". Default value = None.

InputLimits

InputLimits(axes: int)

Bases: InputLimits

Magnetometer input limits specification.

The extreme values of the input (negative and positive) within which performance is of the specified accuracy. Simulated outputs outside of this range are truncated to the limits.

Attributes:

Name	Type	Description
minimum	Parameter	Minimum negative input.
maximum	Parameter	Maximum positive input.

minimum property writable

minimum: Parameter

Minimum negative input.

Simulated outputs less than this value will be truncated to this value. Units must be one of: "T" or "gauss". Default value = Parameter([-Inf,-Inf,-Inf], "T").

maximum property writable

maximum: Parameter

Maximum positive input.

Simulated outputs greater than this value will be truncated to this value. Units must be one of: "T" or "gauss". Default value = Parameter([Inf,Inf,Inf], "T").

Noise

Noise(axes: int)

Bases: Noise

Magnetometer noise specification.

Random uncorrelated noise in the magnetometer outputs.

Attributes:

Name	Type	Description
noise_density	Parameter	Random noise.

noise_density property writable

noise_density: Parameter

Random noise.

Random white Gaussian noise in the magnetometer signal. Units must be one of: "T/sqrt(Hz)", or "gauss/sqrt(Hz)". Default value = Parameter([0.0,0.0,0.0], "T/sqrt(Hz)").

Bias

Bias(axes: int)

Bases: Bias

Magnetometer bias specification.

Bias is the non-zero output of a sensor at rest, or equivalently, the output that has no correlation with the input. It is comprised of a fixed component (that can be calibrated), a random component (that may vary from turn-on to turn-on or with changing conditions), and a temperature dependent component.

Attributes:

Name	Type	Description
fixed	Parameter	Fixed bias.
repeatability	Parameter	Random bias.
temperature	Parameter	Temperature bias.

fixed property writable

fixed: Parameter

Fixed bias.

A fixed bias that is constant across all conditions. For many sensors, this may be removed by factory calibration in which case this parameter can represent any known residual error in that calibration. Units must be one of: "T", "gauss". Default value = Parameter([0.0,0.0,0.0], "T").

repeatability property writable

repeatability: Parameter

Random bias.

The standard deviation of a random bias component that varies with each turn-on of the sensor and/or varies across external conditions. Also known as bias repeatability. This parameter may represent unknown residuals from the factory calibration of a fixed bias. Units must be one of: "T", "gauss". Default value = Parameter([0.0,0.0,0.0], "T").

temperature property writable

temperature: Parameter

Temperature bias.

A linear coefficient relating change in sensor temperature to a change in bias. Units must be one of: "T/C", "gauss/C", or "gauss/F". Note: for change in temperature (delta), the Celsius (C) and Kelvin (K) scales are equivalent, so units per Kelvin are implicitly supported. Default value = Parameter([0.0,0.0,0.0], "T/C").

MagnetometerModel dataclass

MagnetometerModel(
    *,
    data_interface: DataInterface = DataInterface(),
    misalignment: Misalignment = Misalignment(),
    input_limits: InputLimits = InputLimits(),
    bias: Bias = Bias(),
    noise: Noise = Noise(),
    scale_factor: ScaleFactor = ScaleFactor(),
)

Sensor model options.

Specify model options for simulating generic sensor errors and data interfaces. These model options are suitable for many types of sensors. By default all supported sources of error are simulated.

Default specifications

Sensor specification parameters default to zero (or identity). Unspecified parameters will have no effect on the simulation result regardless of the settings here. See SensorSpecification.

Classes:

Name	Description
DataInterface	Data interface simulation options.
Misalignment	Misalignment simulation options.
InputLimits	Input limits simulation options.
Bias	Bias simulation options.
Noise	Noise simulation options.
ScaleFactor	Scale factor simulation options.

Methods:

Name	Description
reset	Reset model parameters to their defaults.
set_all	Set all model parameters.

Attributes:

Name	Type	Description
data_interface	DataInterface	Data interface simulation options.
misalignment	Misalignment	Misalignment simulation options.
input_limits	InputLimits	Input limits simulation options.
bias	Bias	Bias simulation options.
noise	Noise	Noise simulation options.
scale_factor	ScaleFactor	Scale factor simulation options.

data_interface class-attribute instance-attribute

data_interface: DataInterface = field(
    default_factory=DataInterface
)

Data interface simulation options.

misalignment class-attribute instance-attribute

misalignment: Misalignment = field(
    default_factory=Misalignment
)

Misalignment simulation options.

input_limits class-attribute instance-attribute

input_limits: InputLimits = field(
    default_factory=InputLimits
)

Input limits simulation options.

bias class-attribute instance-attribute

bias: Bias = field(default_factory=Bias)

Bias simulation options.

noise class-attribute instance-attribute

noise: Noise = field(default_factory=Noise)

Noise simulation options.

scale_factor class-attribute instance-attribute

scale_factor: ScaleFactor = field(
    default_factory=ScaleFactor
)

Scale factor simulation options.

DataInterface dataclass

DataInterface(
    *,
    simulate_sample_rate: bool = True,
    simulate_quantization: bool = True,
)

Data interface simulation options.

Attributes:

Name	Type	Description
simulate_sample_rate	bool	Simulate sensor data sample rate.
simulate_quantization	bool	Simulate sensor data quantization.

simulate_sample_rate class-attribute instance-attribute

simulate_sample_rate: bool = True

Simulate sensor data sample rate.

simulate_quantization class-attribute instance-attribute

simulate_quantization: bool = True

Simulate sensor data quantization.

Misalignment dataclass

Misalignment(*, simulate_random: bool = True)

Misalignment simulation options.

Attributes:

Name	Type	Description
simulate_random	bool	Simulate random sensing axis misalignment.

simulate_random class-attribute instance-attribute

simulate_random: bool = True

Simulate random sensing axis misalignment.

InputLimits dataclass

InputLimits(
    *,
    simulate_minimum: bool = True,
    simulate_maximum: bool = True,
)

Input limits simulation options.

Attributes:

Name	Type	Description
simulate_minimum	bool	Simulate minimum sensed value.
simulate_maximum	bool	Simulate maximum sensed value.

simulate_minimum class-attribute instance-attribute

simulate_minimum: bool = True

Simulate minimum sensed value.

simulate_maximum class-attribute instance-attribute

simulate_maximum: bool = True

Simulate maximum sensed value.

Bias dataclass

Bias(
    *,
    simulate_fixed: bool = True,
    simulate_random: bool = True,
    simulate_temperature: bool = True,
)

Bias simulation options.

Attributes:

Name	Type	Description
simulate_fixed	bool	Simulate fixed bias offset.
simulate_random	bool	Simulate random bias offset.
simulate_temperature	bool	Simulate temperature dependent bias offset.

simulate_fixed class-attribute instance-attribute

simulate_fixed: bool = True

Simulate fixed bias offset.

simulate_random class-attribute instance-attribute

simulate_random: bool = True

Simulate random bias offset.

simulate_temperature class-attribute instance-attribute

simulate_temperature: bool = True

Simulate temperature dependent bias offset.

Noise dataclass

Noise(*, simulate_wgn: bool = True)

Noise simulation options.

Attributes:

Name	Type	Description
simulate_wgn	bool	Simulate white, Gaussian noise.

simulate_wgn class-attribute instance-attribute

simulate_wgn: bool = True

Simulate white, Gaussian noise.

ScaleFactor dataclass

ScaleFactor(
    *,
    simulate_fixed: bool = True,
    simulate_random: bool = True,
)

Scale factor simulation options.

Attributes:

Name	Type	Description
simulate_fixed	bool
simulate_random	bool

simulate_fixed class-attribute instance-attribute

simulate_fixed: bool = True

simulate_random class-attribute instance-attribute

simulate_random: bool = True

reset

reset() -> None

Reset model parameters to their defaults.

set_all

set_all(*, value: bool) -> None

Set all model parameters.

All model parameters will be set to the input value, True or False.

Parameters:

Name	Type	Description	Default
value	bool	True or False.	required

Magnetometer

Magnetometer(
    model: SensorModel,
    specification: MagnetometerSpecification,
    rng: Generator | int | None = None,
)

Magnetometer(
    model: SensorModel,
    specification: MagnetometerSpecification,
    rng: Generator | int | None = None,
    *,
    mode: str = "real-time",
    max_duration: float,
)

Magnetometer(
    model: SensorModel,
    specification: MagnetometerSpecification,
    rng: Generator | int | None = None,
    *,
    mode: str = "batch",
    max_duration: float | None = None,
)

Bases: Sensor

Simulate magnetometer sensors.

A magnetometer is a "device to measure the magnetic field strength of the earth in three orthogonal directions." [Standard 03].

Magnetometers require a model which specifies which sources of error to simulate; a specification which includes the parameters necessary to model deterministic and random errors; and optionally a random number generator or seed to control determinism and repeatability of the simulation.

Parameters:

Name	Type	Description	Default
model	SensorModel	Magnetometer model.	required
specification	MagnetometerSpecification	Magnetometer specification.	required
rng	Generator | int | None	Random number generator or seed. See numpy.random.default_rng.	None
mode	str	One of batch (default) or real-time.	'batch'
max_duration	float | None	The maximum simulation duration in seconds. If simulating in real-time mode, max_duration is required.	None

Methods:

Name	Description
simulate	Simulate magnetometer measurements from inputs.

Attributes:

Name	Type	Description
state	SimulationState	Simulation state.

state property

state: SimulationState

Simulation state.

Return the simulation state. The state includes the sensor model; the sensor specification; the random number generator state at initialization; and the value of all internal sensor parameters required to replicate the simulated measurement outputs.

simulate

simulate(
    *,
    magnetic_field: Vector,
    temperature: ArrayLike | None = None,
) -> Measurement

simulate(
    *,
    magnetic_field: Vector,
    attitude: Rotation,
    temperature: ArrayLike | None = None,
) -> Measurement

simulate(
    *,
    global_pose: GlobalPose,
    datum: MagneticDatum = WMM2025,
    date: float | date | None = None,
    temperature: ArrayLike | None = None,
) -> Measurement

simulate(
    *,
    magnetic_field: Vector | None = None,
    attitude: Rotation | None = None,
    global_pose: GlobalPose | None = None,
    datum: MagneticDatum | None = None,
    date: float | date | None = None,
    temperature: ArrayLike | None = None,
) -> Measurement

Simulate magnetometer measurements from inputs.

All inputs are optional. Measurement outputs are calculated based on the best available inputs. Insufficient inputs to calculate a valid output will raise a ValueError.

All inputs are reduced to a magnetic field model in sensor coordinates and sources of error from the magnetometer specification are then applied to produce the measurement output(s).

The supported combination of inputs are:

magnetic_field: the input must be the magnetic field experienced by the sensor as measured in sensor coordinates.

magnetic_field + attitude: the magnetic field input must be the magnetic field experienced by the sensor in world (navigation) coordinates. The magnetic field may be a single fixed vector or an array of vectors of the same dimension as the attitude. The attitude input must be the attitude (orientation) of the sensor frame relative to the world (navigation) frame.

global_pose + datum + date: the global pose input must be the pose (position and orientation) of the sensor relative to Earth. The date must be a date object or a decimal year (e.g. 2025.67). If not supplied the epoch of the datum will be used as a default (e.g. 2025.0). Earth's core magnetic field will be simulated using the World Magnetic Model specified in the datum at the given date and pose. See MagneticField for more details.

The temperature input is always optional. If included, it will be used in combination with any temperature dependent specifications when simulating measurement outputs.

Parameters:

Name	Type	Description	Default
magnetic_field	Vector | None	Magnetic field experienced by the magnetometer.	None
attitude	Rotation | None	Attitude (orientation) of the magnetometer.	None
global_pose	GlobalPose | None	Attitude and position of the magnetometer relative to Earth.	None
datum	MagneticDatum | None	World magnetic model datum.	None
date	float | date | None	Date associated with the magnetic datum.	None
temperature	ArrayLike | None	Array of temperatures corresponding to the primary input (degrees C).	None

Returns:

Name	Type	Description
result	Measurement	Measurement instance.