Inertial Navigation System (INS) simulation.
Classes:
| Name | Description |
|---|---|
INSModel |
INS model options. |
INSSpecification |
INS specification. |
INSState |
INS internal state. |
INSData |
INS simulation results. |
INS |
INS sensor simulation. |
Attributes:
| Name | Type | Description |
|---|---|---|
AttitudeFormat |
INS attitude output format options. |
|
Integrator |
INS numerical integrator options. |
module-attribute
¶
AttitudeFormat = AttitudeFormat
INS attitude output format options.
dataclass
¶
INSModel(
*,
data_interface: DataInterface = DataInterface(),
numerical_methods: NumericalMethods = NumericalMethods(),
initial_conditions: InitialConditions = InitialConditions(),
gravity: Gravity = Gravity(),
)
INS model options.
Specify model options for simulating INS configuration and errors. 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 INSSpecification.
Classes:
| Name | Description |
|---|---|
DataInterface |
Data interface simulation options. |
NumericalMethods |
Numerical simulation options. |
InitialConditions |
Initial condition simulation options. |
Gravity |
Gravity model simulation options. |
Methods:
| Name | Description |
|---|---|
reset |
Reset model parameters to their defaults. |
set_all |
Set all boolean model parameters. |
Attributes:
| Name | Type | Description |
|---|---|---|
data_interface |
DataInterface
|
Data interface simulation options. |
numerical_methods |
NumericalMethods
|
Numerical simulation options. |
initial_conditions |
InitialConditions
|
Initial condition simulation options |
gravity |
Gravity
|
Gravity model simulation options. |
class-attribute
instance-attribute
¶
data_interface: DataInterface = field(
default_factory=DataInterface
)
Data interface simulation options.
class-attribute
instance-attribute
¶
numerical_methods: NumericalMethods = field(
default_factory=NumericalMethods
)
Numerical simulation options.
class-attribute
instance-attribute
¶
initial_conditions: InitialConditions = field(
default_factory=InitialConditions
)
Initial condition simulation options
class-attribute
instance-attribute
¶
Gravity model simulation options.
dataclass
¶
DataInterface(
*,
attitude_format: AttitudeFormat = EULER_ANGLE,
simulate_sample_rate: bool = True,
)
Data interface simulation options.
Classes:
| Name | Description |
|---|---|
AttitudeFormat |
Attitude (orientation) output format options. |
Attributes:
| Name | Type | Description |
|---|---|---|
attitude_format |
AttitudeFormat
|
Attitude (orientation) output format. |
simulate_sample_rate |
bool
|
Simulate output sample rate. |
class-attribute
instance-attribute
¶
attitude_format: AttitudeFormat = EULER_ANGLE
Attitude (orientation) output format.
class-attribute
instance-attribute
¶
simulate_sample_rate: bool = True
Simulate output sample rate.
Bases: Enum
Attitude (orientation) output format options.
Euler angle format uses the active, extrinsic "XYZ" convention. This is equivalent to the aerospace yaw (Z), pitch (Y), roll (X) coordinate transform convention. Quaternion format uses scalar element first. See the Rotation class for more details.
Attributes:
| Name | Type | Description |
|---|---|---|
EULER_ANGLE |
Euler angle format. |
|
QUATERNION |
Quaternion format. |
|
ROTATION_MATRIX |
Rotation matrix format. |
dataclass
¶
NumericalMethods(
*,
integrator: Integrator = EULER,
simulate_time_jitter: bool = True,
)
Numerical simulation options.
Classes:
| Name | Description |
|---|---|
Integrator |
Numerical integrator options. |
Attributes:
| Name | Type | Description |
|---|---|---|
integrator |
Integrator
|
Numerical integration method. |
simulate_time_jitter |
bool
|
Simulate random jitter in integration intervals. |
class-attribute
instance-attribute
¶
integrator: Integrator = EULER
Numerical integration method.
class-attribute
instance-attribute
¶
simulate_time_jitter: bool = True
Simulate random jitter in integration intervals.
Bases: Enum
Numerical integrator options.
Euler's method uses forward integration with a single sample. The trapezoidal method uses the average of samples at the start and end points of the interval. The RK4 method uses the Runge-Kutta 4th order algorithm and 3 samples (start, mid-point, end).
Attributes:
| Name | Type | Description |
|---|---|---|
EULER |
Euler's method. |
|
TRAPEZOID |
Trapezoidal method. |
|
RK4 |
Runge-Kutta 4th order method. |
dataclass
¶
Initial condition simulation options.
All options apply to attitude (orientation), position, and velocity initial conditions.
Attributes:
| Name | Type | Description |
|---|---|---|
simulate_bias |
bool
|
Simulate bias errors in initial conditions. |
simulate_random_error |
bool
|
Simulate random errors in initial conditions. |
dataclass
¶
Gravity model simulation options.
Attributes:
| Name | Type | Description |
|---|---|---|
simulate_scale_factor |
bool
|
Simulate scale factor error in gravity values. |
simulate_noise |
bool
|
Simulate random, white, Gaussian error in gravity values. |
INS specification.
An inertial navigation system (INS) specification includes the parameters required to simulate INS behavior and response to inputs.
By default the specification returns a perfect sensor with no intrinsic sources of error.
Classes:
| Name | Description |
|---|---|
DataInterface |
INS data interface specification. |
NumericalMethods |
INS numerical methods specification. |
InitialConditions |
INS initial attitude (orientation) accuracy specification. |
Gravity |
INS gravity specification. |
Attributes:
| Name | Type | Description |
|---|---|---|
data_interface |
DataInterface
|
|
numerical_methods |
NumericalMethods
|
|
initial_conditions |
InitialConditions
|
|
gravity |
Gravity
|
|
INS data interface specification.
The data interface of the INS. The INS interface includes the sample rate, which is the frequency at which the sensor transmits new data.
Attributes:
| Name | Type | Description |
|---|---|---|
sample_rate |
Parameter
|
The frequency at which new data is output from the sensor. |
INS numerical methods specification.
Numerical specifications affecting INS algorithms. The specification includes random timing errors to apply during numerical integration steps.
Attributes:
| Name | Type | Description |
|---|---|---|
time_jitter |
Parameter
|
Random time jitter. |
property
writable
¶
time_jitter: Parameter
Random time jitter.
Random white, Gaussian jitter that is added to sample times of the
INS inputs. White, Gaussian noise is uncorrelated in time and
normally distributed. The jitter should be specified by its
standard deviation in units of "s".
Default value = Parameter(0.0, "s").
INS initial attitude (orientation) accuracy specification.
Attributes:
| Name | Type | Description |
|---|---|---|
attitude_bias |
Parameter
|
Fixed bias error. |
attitude_random_error |
Parameter
|
Random error. |
position_bias |
Parameter
|
Initial position bias. |
position_random_error |
Parameter
|
Random error. |
velocity_bias |
Parameter
|
Initial velocity bias. |
velocity_random_error |
Parameter
|
Random error. |
property
writable
¶
attitude_bias: Parameter
Fixed bias error.
A fixed bias or offset in initial attitude (orientation). Units
must be one of: "rad" or "deg". The attitude error is specified
as a rotation vector, \(\boldsymbol{\phi}\) that is applied on the
right of the initial attitude matrix, \(\mathbf{R}_{0}' =
\mathbf{R}_{0} * \mathbf{R}(\boldsymbol{\phi})\).
Default value = Parameter([0.0,0.0,0.0], "rad").
property
writable
¶
attitude_random_error: Parameter
Random error.
Random normally distributed error in the initial attitude
(orientation). Random error should be specified as the standard
deviation for each component of a rotation vector. Units must be
one of: "rad", or "deg". The error, \(\boldsymbol{\phi}\), is
applied on the right of the initial attitude matrix,
\(\mathbf{R}_{0}' = \mathbf{R}_{0} * \mathbf{R}(\boldsymbol{\phi})\).
Default value = Parameter([0.0,0.0,0.0], "rad").
property
writable
¶
position_bias: Parameter
Initial position bias.
A fixed bias or offset in initial position. Units must be one of:
"m" or "ft". If the INS uses geodetic coordinates, the bias
must be specified in the local North, East, Down (NED) basis.
Default value = Parameter([0.0,0.0,0.0], "m").
property
writable
¶
position_random_error: Parameter
Random error.
Random normally distributed error in the initial position. Random
error should be specified as the standard deviation of a zero-mean
normal distribution. Units must be one of: "m", or "ft". If
the INS uses geodetic coordinates, the bias must be specified in the
local North, East, Down (NED) basis.
Default value = Parameter([0.0,0.0,0.0], "m").
property
writable
¶
velocity_bias: Parameter
Initial velocity bias.
A fixed bias or offset in initial velocity. Units must be one of:
"m/s" or "ft/s".
Default value = Parameter([0.0,0.0,0.0], "m/s").
property
writable
¶
velocity_random_error: Parameter
Random error.
Random normally distributed error in the initial velocity. Random
error should be specified as the standard deviation of a zero-mean
normal distribution. Units must be one of:
"m/s", or "ft/s".
Default value = Parameter([0.0,0.0,0.0], "m/s").
INS gravity specification.
Attributes:
| Name | Type | Description |
|---|---|---|
scale_factor |
Parameter
|
Scale factor error. |
noise |
Parameter
|
Random white, Gaussian noise. |
property
writable
¶
scale_factor: Parameter
Scale factor error.
A fixed offset from the ideal unit scale factor (1.0) applied to the
magnitude of gravity. For example, a 1% scale error results in a
scale factor of 1.01. A -100ppm scale error results in a scale
factor of 0.9999. Units are ratios of similar quantities so must be
one of: "dimensionless", "%", or "ppm".
Default value = Parameter(0.0, "dimensionless").
property
writable
¶
noise: Parameter
Random white, Gaussian noise.
Random white, Gaussian noise in the gravity signal. White, Gaussian
noise is uncorrelated in time and normally distributed and specified
by the standard deviation (zero mean). Units must be one of:
"m/s/s", "g", or "ft/s/s".
Default value = Parameter([0.0,0.0,0.0], "m/s/s").
dataclass
¶
INSState(
*,
numerical_methods: NumericalMethods = NumericalMethods(),
initial_conditions: InitialConditions = InitialConditions(),
gravity: Gravity = Gravity(),
)
INS internal state.
Fixed (non-random) simulation parameters are stored once. Random simulation
parameters are stored for each time step of the
Measurement output. Parameters that are
not simulated default to None.
Classes:
| Name | Description |
|---|---|
NumericalMethods |
Numerical simulation state. |
InitialConditions |
Initial conditions simulation state. |
Gravity |
Gravity simulation state. |
Attributes:
| Name | Type | Description |
|---|---|---|
numerical_methods |
NumericalMethods
|
Numerical methods simulation state. |
initial_conditions |
InitialConditions
|
Initial conditions simulation state. |
gravity |
Gravity
|
Gravity simulation state. |
class-attribute
instance-attribute
¶
numerical_methods: NumericalMethods = field(
default_factory=NumericalMethods
)
Numerical methods simulation state.
class-attribute
instance-attribute
¶
initial_conditions: InitialConditions = field(
default_factory=InitialConditions
)
Initial conditions simulation state.
class-attribute
instance-attribute
¶
Gravity simulation state.
dataclass
¶
NumericalMethods(*, time_jitter: NDArray | None = None)
dataclass
¶
InitialConditions(
*,
attitude_bias: NDArray | None = None,
attitude_random_error: NDArray | None = None,
position_bias: NDArray | None = None,
position_random_error: NDArray | None = None,
velocity_bias: NDArray | None = None,
velocity_random_error: NDArray | None = None,
)
Initial conditions simulation state.
Attributes:
| Name | Type | Description |
|---|---|---|
attitude_bias |
NDArray | None
|
|
attitude_random_error |
NDArray | None
|
|
position_bias |
NDArray | None
|
|
position_random_error |
NDArray | None
|
|
velocity_bias |
NDArray | None
|
|
velocity_random_error |
NDArray | None
|
|
dataclass
¶
dataclass
¶
INSData(
*,
attitude: Measurement,
position: Measurement,
velocity: Measurement,
)
INS simulation results.
An instance of this class is returned from the INS.simulate() method. It contains the simulated INS measurements. The coordinate systems are inherited from the initial conditions supplied in the INS.initialize() method.
For further details regarding coordinates and conventions see the geometry and geodesy modules.
Attributes:
| Name | Type | Description |
|---|---|---|
attitude |
Measurement
|
Attitude (orientation) measurements. |
position |
Measurement
|
Position measurements. |
velocity |
Measurement
|
Velocity measurements. |
instance-attribute
¶
attitude: Measurement
Attitude (orientation) measurements.
The attitude of the INS relative to the navigation frame. The format will be one of Euler angles, quaternion, or rotation matrix as specified in the attitude format field of the INSModel.
instance-attribute
¶
position: Measurement
Position measurements.
The position of the INS in navigation frame coordinates. For Cartesian coordinate frames (local, topocentric, or ECEF) this will be x, y, z data in meters. For geodetic coordinates this will be latitude, longitude, altitude in radians and meters respectively.
instance-attribute
¶
velocity: Measurement
Velocity measurements.
The velocity of the INS in navigation frame coordinates. For Cartesian coordinate frames (local, topocentric, or ECEF) this will be x, y, z data in meters per second. For geodetic coordinates this will be velocity in the local North, East, Down (NED) basis in meters per second.
INS(
model: INSModel,
specification: INSSpecification,
rng: Generator | int | None = None,
)
INS(
model: INSModel,
specification: INSSpecification,
rng: Generator | int | None = None,
*,
mode: str = "real-time",
)
INS(
model: INSModel,
specification: INSSpecification,
rng: Generator | int | None = None,
*,
mode: str = "batch",
)
INS sensor simulation.
INS sensors 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.
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.
Before calling simulate(), the INS must be initialized via the
initialize() method. This provides the initial attitude
(orientation), position, and velocity of the INS. The INS also inherits
the navigation coordinate frame from the initial condition inputs, along
with any geodetic datums and models.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
model
|
INSModel
|
INS model. |
required |
specification
|
INSSpecification
|
INS specification. |
required |
rng
|
Generator | int | None
|
Random number generator or seed. See numpy.random.default_rng. |
None
|
mode
|
str
|
One of |
'batch'
|
Methods:
| Name | Description |
|---|---|
initialize |
Initialize the INS sensor. |
simulate |
Simulate INS measurements from IMU inputs. |
reset |
Reset the INS attitude, position, and/or velocity. |
Attributes:
| Name | Type | Description |
|---|---|---|
state |
SimulationState
|
Simulation 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.
initialize(
pose: GlobalPose | None = None,
angular_rate: Vector | Measurement | None = None,
specific_force: Vector | Measurement | None = None,
) -> INSData | None
Initialize the INS sensor.
Set the initial attitude, position, and velocity of the INS sensor. If
using real-time mode for incremental simulation, users must also
supply the initial angular rate and specific force inputs.
Initial pose should be specified as a GlobalPose object. The navigation frame, gravity, and earth rotation rate models will be inherited from the initial conditions.
If the pose input is None, a local frame with identity initial pose,
zero position, zero velocity, and standard gravity will be used.
All inputs must be a single sample representing the initial conditions at the start of navigation.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
pose
|
GlobalPose | None
|
Initial attitude, position, and velocity of the INS relative to Earth. |
None
|
angular_rate
|
Vector | Measurement | None
|
Initial angular rate of the INS. Only required in |
None
|
specific_force
|
Vector | Measurement | None
|
Initial specific force experienced by the INS. Only required in
|
None
|
Returns:
| Name | Type | Description |
|---|---|---|
ins_data |
INSData | None
|
INSData instance with the initial pose. Only returned in
|
simulate(
*,
angular_rate: Vector | Measurement,
specific_force: Vector | Measurement,
) -> INSData
Simulate INS measurements from IMU inputs.
An INS integrates data from a gyro and an accelerometer to produce
attitude (orientation), position, and velocity, and outputs. Initial
conditions must be specified using the initialize() method before
calling this method.
Inputs must have compatible shape and time. The angular rate input must be the angular rate of the gyro relative to inertial space as measured in gyro coordinates. The specific force input must be the specific force (non-gravitational acceleration) relative to inertial space acting on the accelerometer as measured in accelerometer coordinates.
The effect of Earth's rotation and gravity will be modeled based on the coordinates and datums specified in the initial conditions.
If the numerical integrator (specified in the INS model) is RK4, the
output sample rate will be half the input sample rate. In real-time
mode with the RK4 integrator, consecutive pairwise inputs must be
supplied, e.g. two angular rates and two specific forces at times (1-2,
3-4, 5-6, ...). The first of the two samples is used as the mid-point
of the integration interval and the output is given coincident with the
second sample.
If the input data is itself simulated, see Gyro.simulate, Accelerometer.simulate, and IMU.simulated.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
angular_rate
|
Vector | Measurement
|
Angular rate of the INS relative to inertial space. |
required |
specific_force
|
Vector | Measurement
|
Specific force experienced by the INS relative to inertial space. |
required |
Returns:
| Name | Type | Description |
|---|---|---|
result |
INSData
|
INSData instance. |
reset(
*,
attitude: Rotation | None = None,
position: Vector | Coordinates | None = None,
velocity: Vector | None = None,
) -> None
Reset the INS attitude, position, and/or velocity.
Resets the internal INS attitude (orientation), position, and/or velocity from an external reference. Reset can be used to simulate the behavior of an aided INS sensor. For example, resetting the entire state can simulate the behavior of a sensor where GNSS measurements correct attitude, position, and velocity errors through correlations in a state estimation filter.
All inputs are optional and must be supplied relative to the navigation coordinate system established at initialization.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
attitude
|
Rotation | None
|
Reference attitude. |
None
|
position
|
Vector | Coordinates | None
|
Reference position. |
None
|
velocity
|
Vector | None
|
Reference velocity. |
None
|