inertialsim.sensors.gyro

Gyro simulation.

Classes:

Name	Description
GyroSpecification	Gyro specification.
GyroData	Gyro output data.
Gyro	Simulate gyroscope (gyro) sensors.

GyroSpecification

GyroSpecification(axes: int = NUM_CARTESIAN_AXES)

Bases: SensorSpecification

Gyro specification.

A gyro specification includes the parameters required to simulate gyro 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
DataInterface	An abstract base class for data interface parameters.
InputLimits	Sensor input limits.
Noise	Sensor noise terms.
Bias	Sensor bias terms.
ScaleFactor	Sensor scale factor terms.
Misalignment	Sensor misalignment.
GyroDataInterface	Gyro interface parameters.
GyroInputLimits	Gyro input limits.
GyroNoise	Gyro noise terms.
GyroBias	Gyro bias terms.

Attributes:

Name	Type	Description
axes	int	Number of independent sensing axes of the sensor.
manufacturer	str	Manufacturer of the sensor.
model	str	Model number/identifier of the sensor.
version	str	Version number/identifier of the sensor.
data_interface	DataInterface	Sensor data interface specifications.
scale_factor	ScaleFactor	Sensor scale factor specification.
misalignment	Misalignment	A sensor misalignment specification.
input_limits	GyroInputLimits	A gyro input limits specification.
noise	GyroNoise	A gyro noise specification.
bias	GyroBias	A gyro bias specification.

axes property

axes: int

Number of independent sensing axes of the sensor.

manufacturer property writable

manufacturer: str

Manufacturer of the sensor.

model property writable

model: str

Model number/identifier of the sensor.

version property writable

version: str

Version number/identifier of the sensor.

data_interface deletable property writable

data_interface: DataInterface

Sensor data interface specifications.

scale_factor property

scale_factor: ScaleFactor

Sensor scale factor specification.

misalignment property

misalignment: Misalignment

A sensor misalignment specification.

input_limits property

input_limits: GyroInputLimits

A gyro input limits specification.

noise property

noise: GyroNoise

A gyro noise specification.

bias property

bias: GyroBias

A gyro bias specification.

DataInterface

DataInterface(axes: int)

Bases: ABC

An abstract base class for data interface parameters.

The data interface of the sensor. The sensor interface includes the data frequency, which is the frequency at which the sensor transmits new data, and the data type, which is one of rate or delta.

Derived classes should set appropriate defaults and handle units in the setter methods.

Attributes:

Name	Type	Description
sample_rate	Parameter	The frequency at which new data is output from the sensor.
delta_sample_rate	Parameter	The frequency at which delta type data is output from the sensor.
quantization	Parameter | None	Data interface rate output quantization.
delta_quantization	Parameter | None	Data interface delta output quantization.
delta_stride	int	Integer number of rate outputs per delta output.

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").

delta_sample_rate property writable

delta_sample_rate: Parameter

The frequency at which delta type data is output from the sensor.

Units must be "Hz" and must be a integer divisor of sample_rate. Default value = Parameter(0, "Hz") meaning no delta outputs.

quantization abstractmethod property writable

quantization: Parameter | None

Data interface rate output quantization.

Outputs will be quantized at simulated digital levels. Use this when the parameters of the analog to digital conversion are known. If the sensor to simulate has been characterized experimentally, e.g. by the Allan deviation method, use Noise.quantization instead. Do not use both.

delta_quantization abstractmethod property writable

delta_quantization: Parameter | None

Data interface delta output quantization.

Delta (integrated) outputs will be quantized at simulated digital levels. Use this when the parameters of the analog to digital conversion are known. If the sensor to simulate has been characterized experimentally, e.g. by the Allan deviation method, use Noise.quantization instead. Do not use both.

delta_stride property

delta_stride: int

Integer number of rate outputs per delta output.

InputLimits

InputLimits(axes: int)

Bases: ABC

Sensor input limits.

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 these limits.

Derived classes should set appropriate defaults and handle units in the setter methods.

Attributes:

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

minimum abstractmethod property writable

minimum: Parameter

Minimum negative input.

Simulated outputs less than this value will be truncated to this value.

maximum abstractmethod property writable

maximum: Parameter

Maximum positive input.

Simulated outputs greater than this value will be truncated to this value.

Noise

Noise(axes: int)

Bases: ABC

Sensor noise terms.

Common inertial sensor noise terms describing quantization, random walk, bias instability, rate random walk, and rate ramp. See Reference [20] and Standard [05] & Standard [06] for details.

Each of these noise terms can be determined experimentally from Allan variance/deviation plots or from data sheets and direct knowledge of the sensor. Not all terms will be applicable to all sensors.

Derived classes should set appropriate defaults and handle units in the setter methods.

Attributes:

Name	Type	Description
quantization	Parameter	Quantization noise.
random_walk	Parameter	Random walk noise.
bias_instability	Parameter	Bias instability noise.
rate_random_walk	Parameter	Rate random walk noise.
rate_ramp	Parameter	Rate ramp noise.

quantization abstractmethod property writable

quantization: Parameter

Quantization noise.

Uniformly distributed random noise arising from digital quantization of the input. Use this parameter when the sensor to simulate has been characterized experimentally, e.g. by the Allan deviation method. If the parameters of the analog to digital converter are known explicitly, use ScaleFactor.quantization instead. Do not use both.

random_walk abstractmethod property writable

random_walk: Parameter

Random walk noise.

Random white noise in the signal that when integrated results in error buildup. Also known equivalently as noise density.

bias_instability abstractmethod property writable

bias_instability: Parameter

Bias instability noise.

The random variation in bias as computed over specified finite sampling time and averaging time intervals. Also known equivalently as bias in-run stability and flicker noise.

rate_random_walk abstractmethod property writable

rate_random_walk: Parameter

Rate random walk noise.

Random white noise in the signal derivative that results in error buildup.

rate_ramp abstractmethod property writable

rate_ramp: Parameter

Rate ramp noise.

Linear increase in the signal over long averaging time intervals.

Bias

Bias(axes: int)

Bases: ABC

Sensor bias terms.

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.

Derived classes should set appropriate defaults and handle units in the setter methods.

Attributes:

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

fixed abstractmethod 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.

repeatability abstractmethod 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. This parameter may represent unknown residuals from the factory calibration of a fixed bias.

temperature abstractmethod property writable

temperature: Parameter

Temperature bias.

A linear coefficient relating change in sensor temperature to a change in bias.

ScaleFactor

ScaleFactor(axes: int)

Sensor scale factor terms.

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.

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.

GyroDataInterface

GyroDataInterface(axes: int)

Bases: DataInterface

Gyro interface parameters.

The data interface of the gyros. The gyro 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.
delta_sample_rate	Parameter	The frequency at which delta type data is output from the sensor.
delta_stride	int	Integer number of rate outputs per delta output.
quantization	Parameter | None	Data interface rate output quantization.
delta_quantization	Parameter | None	Data interface delta 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").

delta_sample_rate property writable

delta_sample_rate: Parameter

The frequency at which delta type data is output from the sensor.

Units must be "Hz" and must be a integer divisor of sample_rate. Default value = Parameter(0, "Hz") meaning no delta outputs.

delta_stride property

delta_stride: int

Integer number of rate outputs per delta output.

quantization property writable

quantization: Parameter | None

Data interface rate output quantization.

Outputs will be quantized at simulated digital levels. Use this when the parameters of the analog to digital conversion are known. If the sensor to simulate has been characterized experimentally, e.g. by the Allan deviation method, use GyroNoise.quantization instead. Do not use both. Units must be one of: "rad/s/LSB", "deg/s/LSB", or "deg/h/LSB". Default value = None.

delta_quantization property writable

delta_quantization: Parameter | None

Data interface delta output quantization.

Delta angle outputs will be quantized at simulated digital levels. Use this when the parameters of the analog to digital conversion are known. If the sensor to simulate has been characterized experimentally, e.g. by the Allan deviation method, use GyroNoise.quantization instead. Do not use both. Delta angle outputs will be integrated with un-quantized angular rates before output. Units must be one of: "rad/LSB" or "deg/LSB". Default value = None.

GyroInputLimits

GyroInputLimits(axes: int)

Bases: InputLimits

Gyro input limits.

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: "rad/s" or "deg/s". Default value = Parameter([-Inf,-Inf,-Inf], "rad/s").

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: "rad/s" or "deg/s". Default value = Parameter([Inf,Inf,Inf], "rad/s").

GyroNoise

GyroNoise(axes: int)

Bases: Noise

Gyro noise terms.

Common gyro noise terms describing quantization, (angle) random walk, bias instability, rate random walk, and rate ramp. See Reference [20] and Standard [05] for details.

Each of these noise terms can be determined experimentally from Allan variance/deviation plots or from data sheets and direct knowledge of the sensor. Not all terms will be applicable to all sensors.

Attributes:

Name	Type	Description
quantization	Parameter	Quantization noise.
random_walk	Parameter	Random walk noise.
bias_instability	Parameter	Bias instability noise.
rate_random_walk	Parameter	Rate random walk noise.
rate_ramp	Parameter	Rate ramp noise.

quantization property writable

quantization: Parameter

Quantization noise.

Uniformly distributed random noise arising from digital quantization of the input (default = 0.0). Use this parameter when the sensor to simulate has been characterized experimentally, e.g. by the Allan deviation method. If the parameters of the analog to digital converter are known explicitly, use GyroDataInterface.quantization instead. Do not use both. Units must be one of: "rad" or "deg". Default value = Parameter([0.0,0.0,0.0], "rad").

random_walk property writable

random_walk: Parameter

Random walk noise.

Random white noise in the angular rate signal that when integrated results in angle error buildup (angle random walk). Also known equivalently as noise density. Units must be one of: "rad/sqrt(s)", "rad/s/sqrt(Hz)", "deg/sqrt(h)", or "deg/s/sqrt(Hz)". Default value = Parameter([0.0,0.0,0.0], "rad/sqrt(s)").

bias_instability property writable

bias_instability: Parameter

Bias instability noise.

The random variation in bias as computed over specified finite sampling time and averaging time intervals. Also known equivalently as bias in-run stability and flicker noise. Units must be one of: "rad/s", "deg/s", or "deg/h". Default value = Parameter([0.0,0.0,0.0], "rad/s").

rate_random_walk property writable

rate_random_walk: Parameter

Rate random walk noise.

Random white noise in the angular rate derivative (angular acceleration) that results in angular rate error buildup (rate random walk). Units must be one of: "rad/s/sqrt(s)", "deg/s/sqrt(s)", or "deg/h/sqrt(h)". Default value = Parameter([0.0,0.0,0.0], "rad/s/sqrt(s)").

rate_ramp property writable

rate_ramp: Parameter

Rate ramp noise.

Linear increase in the angular rate signal over long averaging time intervals. Units must be one of: "rad/s/s", "deg/s/s", or "deg/h/h". Default value = Parameter([0.0,0.0,0.0], "rad/s/s").

GyroBias

GyroBias(axes: int)

Bases: Bias

Gyro bias terms.

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: "rad/s", "deg/s", or "deg/h". Default value = Parameter([0.0,0.0,0.0], "rad/s").

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: "rad/s", "deg/s", or "deg/h". Default value = Parameter([0.0,0.0,0.0], "rad/s").

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: "rad/s/C", "deg/s/C", "deg/h/C", "deg/s/F", or "deg/h/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], "rad/s/C").

GyroData dataclass

GyroData(
    *,
    angular_rate: Measurement,
    delta_angle: Measurement | None = None,
)

Gyro output data.

An instance of this class is returned from the Gyro.simulate method. It contains the simulated angular rate and delta angle (optional) measurements.

Attributes:

Name	Type	Description
angular_rate	Measurement
delta_angle	Measurement | None

angular_rate instance-attribute

angular_rate: Measurement

delta_angle class-attribute instance-attribute

delta_angle: Measurement | None = None

Gyro

Gyro(
    model: SensorModel | IMUModel,
    specification: GyroSpecification | IMUSpecification,
    rng: Generator | int | None = None,
)

Gyro(
    model: SensorModel | IMUModel,
    specification: GyroSpecification | IMUSpecification,
    rng: Generator | int | None = None,
    *,
    mode: str = "real-time",
    max_duration: float,
)

Gyro(
    model: SensorModel | IMUModel,
    specification: GyroSpecification | IMUSpecification,
    rng: Generator | int | None = None,
    *,
    mode: str = "batch",
    max_duration: float | None = None,
)

Bases: Sensor

Simulate gyroscope (gyro) sensors.

A gyro is "an inertial sensor that measures angular rotation with respect to inertial space about its input axis(es)." [Standard 03].

Gyros requires 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.

Two modes are supported: batch (default) and real-time. In batch mode, the simulate() method should be called once with all inputs to return all simulated measurement outputs. In real-time mode, the simulate() method can be called repeatedly to incrementally simulate measurements. In real-time mode, a max_duration input (specified in seconds) should supply an upper bound on the expected simulation duration. If the expected duration is unknown it is safe and efficient to specify a value up to several hours.

Parameters:

Name	Type	Description	Default
model	SensorModel | IMUModel	Gyro or IMU model.	required
specification	GyroSpecification | IMUSpecification	Gyro or IMU 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 to precompute correlated noise terms.	None

Methods:

Name	Description
simulate	Simulate gyro measurements from kinematic 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(
    *,
    angular_rate: Vector,
    temperature: ArrayLike | None = None,
) -> GyroData

simulate(
    *,
    angular_rate: Vector,
    global_pose: GlobalPose,
    temperature: ArrayLike | None = None,
) -> GyroData

simulate(
    *,
    global_pose: GlobalPose,
    temperature: ArrayLike | None = None,
) -> GyroData

simulate(
    *,
    attitude: Rotation,
    temperature: ArrayLike | None = None,
) -> GyroData

simulate(
    *,
    angular_rate: Vector | None = None,
    global_pose: GlobalPose | None = None,
    attitude: Rotation | None = None,
    temperature: ArrayLike | None = None,
) -> GyroData

Simulate gyro measurements from kinematic 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.

Measurement output sample rate(s) will match the input sample rate. In batch mode (default), if the simulate_sample_rate model option is True, the output sample rate(s) will match the sample rate(s) in the sensor specification. Linear interpolation of angular rate is used for the resampling.

All inputs are reduced to angular rate (with respect to inertial space) internally and sources of error from the gyro specification are then applied to produce the measurement output(s).

The supported combination of inputs are:

angular_rate: the input must be the angular rate of the gyro relative to an inertial frame as measured in gyro coordinates. When angular_rate is used alone, it is not possible to include the effect of Earth's rotation in the measured output. For this reason, the angular rate can also be relative to a fixed navigation frame (also known as world, or global frame) if Earth's rotation is not important for the application.

angular_rate + global_pose: the input must be the angular rate of the gyro relative to an Earth fixed navigation frame (also known as world, or global frame) as measured in gyro coordinates. The effect of Earth's rotation will be added to the input based on the global_pose data to produce angular rate relative to inertial space. If needed, the global_pose input will be interpolated to match the times of the angular_rate input. For this reason, global_pose time stamps must match or span the entire duration of the angular_rate input.

global_pose: angular rate is numerically calculated as the first forward difference of the global attitude. The effect of Earth's rotation will be compensated to produce angular rate relative to inertial space. At least two poses must be supplied. In real-time mode, overlapping inputs should be supplied, e.g. pairwise poses (1-2, 2-3, 3-4, ...).

attitude: the input must be the attitude (orientation) of the gyro relative to an inertial frame. Angular rate is numerically calculated as the first forward difference of the attitude. When attitude is used alone, it is not possible to include the effect of Earth's rotation in the measured output. For this reason, the attitude can also be relative to a fixed navigation frame (also known as world, or global frame) if Earth's rotation is not important for the application. At least two poses must be supplied. In real-time mode, overlapping inputs should be supplied, e.g. pairwise attitudes (1-2, 2-3, 3-4, ...).

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
angular_rate	Vector | None	Angular rate experienced by the gyro.	None
global_pose	GlobalPose | None	Attitude and position of the gyro relative to Earth.	None
attitude	Rotation | None	Attitude of the gyro.	None
temperature	ArrayLike | None	Array of temperatures corresponding to the primary input (degrees C).	None

Returns:

Name	Type	Description
result	GyroData	GyroResult instance.