Math Engine Reference: Estimation

@brief 고정 차원 constant-velocity 상태 =[px,py,pz,vx,vy,vz]=다.

covariance 는 row-major 6x6이며 위치·속도와 동일한 caller-selected 일관 단위를 사용한다. 값만 담는 caller-owned POD이고 내부 pointer나 보관된 storage가 없다.

typedef struct math_engine_kalman_vec3_cv_state_f64 {
    uint32_t struct_size; /**< Exact state byte 크기 =sizeof(math_engine_kalman_vec3_cv_state_f64_t)=다. */
    uint32_t struct_version; /**< =MATH_ENGINE_KALMAN_VEC3_CV_STATE_F64_VERSION_1=이어야 한다. */
    math_engine_vec3_f64_t position; /**< Caller Cartesian frame의 finite =[px,py,pz]= 위치 vector다. */
    math_engine_vec3_f64_t velocity; /**< 같은 frame에서 position-unit/second인 finite =[vx,vy,vz]= vector다. */
    double covariance[36]; /**< State order =[px,py,pz,vx,vy,vz]=의 finite symmetric PSD row-major 6x6 covariance다. */
    double process_acceleration_variance; /**< 동일 frame 세 축에 적용하는 finite nonnegative acceleration variance다. */
    uint32_t flags; /**< V1 state에는 정의된 bit가 없어 반드시 0이다. */
    uint32_t reserved32; /**< Caller는 0으로 두며 state validator가 nonzero를 거부한다. */
    uint64_t reserved[2]; /**< Caller가 0으로 두어야 하고 state validator가 검사하는 ABI 확장 word다. */
} math_engine_kalman_vec3_cv_state_f64_t;

@brief 선택 가능한 위치·속도 관측과 각 축의 대각 noise variance다.

활성화한 channel의 관측과 variance는 유한해야 하고 variance는 0 이상이어야 한다. 모든 값은 상태와 같은 caller-selected 단위 체계를 사용한다.

typedef struct math_engine_kalman_vec3_measurement_f64 {
    uint32_t struct_size; /**< Exact measurement byte 크기 =sizeof(math_engine_kalman_vec3_measurement_f64_t)=다. */
    uint32_t struct_version; /**< =MATH_ENGINE_KALMAN_VEC3_MEASUREMENT_F64_VERSION_1=이어야 한다. */
    uint32_t measurement_flags; /**< POSITION/VELOCITY bit 중 하나 이상인 active-channel mask다. */
    uint32_t reserved32; /**< Caller는 0으로 두며 measurement validator가 nonzero를 거부한다. */
    math_engine_vec3_f64_t position; /**< POSITION bit가 있으면 상태 frame/unit의 finite 위치 관측이며 아니면 무시된다. */
    math_engine_vec3_f64_t velocity; /**< VELOCITY bit가 있으면 상태 frame의 finite 위치-unit/second 관측이며 아니면 무시된다. */
    math_engine_vec3_f64_t position_variance; /**< 활성 position x/y/z 각각의 finite nonnegative noise variance다. */
    math_engine_vec3_f64_t velocity_variance; /**< 활성 velocity x/y/z 각각의 finite nonnegative noise variance다. */
    uint64_t reserved[2]; /**< Caller가 0으로 두어야 하고 measurement validator가 검사하는 ABI word다. */
} math_engine_kalman_vec3_measurement_f64_t;

@brief 고정·일반 Kalman 경로가 공유하는 provenance와 covariance 진단 결과다.

typedef struct math_engine_kalman_result_f64 {
    uint32_t struct_size; /**< Caller가 exact result byte 크기로 미리 설정한다. */
    uint32_t struct_version; /**< =MATH_ENGINE_KALMAN_RESULT_F64_VERSION_1=이어야 한다. */
    uint32_t flags; /**< VALUE와 predicted/updated/path/covariance provenance bit의 OR다. */
    uint32_t state_dimension; /**< 성공한 state vector element 수; fixed 경로는 6, general은 1..16이다. */
    uint32_t measurement_dimension; /**< Update에 사용한 scalar channel 수; prediction에서는 0이다. */
    uint32_t mode; /**< General 경로의 =math_engine_mode_t= 값이며 fixed 경로에서는 0이다. */
    uint64_t workspace_used_bytes; /**< General 경로가 소비한 exact scratch byte 수이며 fixed 경로에서는 0이다. */
    double innovation_norm; /**< Update residual vector의 finite nonnegative Euclidean norm; prediction은 0이다. */
    double normalized_innovation_squared; /**< =innovation^T S^-1 innovation=인 finite nonnegative 무차원 값; prediction은 0이다. */
    double covariance_symmetry_error; /**< Commit covariance의 최대 absolute =|Pij-Pji|= 진단값이다. */
    double minimum_covariance_diagonal; /**< Commit covariance diagonal 중 최소값이며 해당 state covariance 단위다. */
    uint64_t operation_fingerprint; /**< Fixed/general predict/update 종류를 구분하는 stable 64-bit operation tag다. */
    uint64_t reserved[2]; /**< Library가 0으로 기록하고 caller가 무시하며 input storage validation 시 0이어야 한다. */
} math_engine_kalman_result_f64_t;

@brief 일반 filter의 borrowed 추정 vector와 row-major covariance 읽기 view다.

두 pointer는 호출 동안 유효해야 하며 함수가 보관하거나 해제하지 않는다.

typedef struct math_engine_kalman_state_const_view_f64 {
    const double* estimate; /**< Non-NULL borrowed finite vector =dimension= elements; API return까지 유효하고 보관되지 않는다. */
    const double* covariance; /**< Non-NULL borrowed row-major PSD matrix; 최소 =covariance_row_stride*dimension= elements가 호출 동안 유효하다. */
    uint32_t dimension; /**< Estimate 길이와 covariance 행/열 수인 포함 범위 1..16이다. */
    uint32_t covariance_row_stride; /**< Covariance 연속 row 시작 사이의 double element 수이며 =dimension= 이상이다. */
} math_engine_kalman_state_const_view_f64_t;

@brief 일반 filter의 caller-owned 쓰기 가능 추정 vector와 covariance view다.

covariance_row_stride 는 double element 단위이며 dimension 이상이어야 한다.

typedef struct math_engine_kalman_state_view_f64 {
    double* estimate; /**< Non-NULL caller-owned mutable output =dimension= elements; 호출 동안 독점 유효하고 보관되지 않는다. */
    double* covariance; /**< Non-NULL caller-owned mutable matrix, 최소 =covariance_row_stride*dimension= elements; estimate와 겹치지 않는다. */
    uint32_t dimension; /**< Output estimate 길이와 covariance 행/열 수이며 input dimension과 정확히 같다. */
    uint32_t covariance_row_stride; /**< Output covariance row 간 double element stride이며 =dimension= 이상이다. */
} math_engine_kalman_state_view_f64_t;

외부 측정 source가 사용할 수 있는 정확한 callback signature다.

• 매개변수 user_data (in,out): callback 소유자가 해석하는 opaque pointer.
• 매개변수 sample_time_seconds (in): 요청 sample의 local time(s).
• 매개변수 out_measurement (out): 성공 시 완전히 기록할 caller-provided measurement.
• 반환: 성공 또는 음수 상태 code.

Math Engine API는 이 typedef의 callback을 호출하거나 보관하지 않는다. 이를 사용하는 외부 adapter가 호출 thread와 user_data lifetime을 소유한다.

• Math Engine ownership: user_data=caller out_measurement=caller
• Math Engine nullable: user_data=true out_measurement=false
• Math Engine thread_safety: conditional
• Math Engine callback: invocation=external thread=external retention=external exception=forbidden

호출 빈도, thread와 pointer retention은 이 typedef를 연결하는 외부 adapter 계약이 정한다. Callback 구현은 C++ exception 또는 다른 unwind를 C ABI 경계 밖으로 전파하면 안 된다.

typedef math_engine_status_t (*math_engine_kalman_vec3_measurement_source_f64_fn)(
    void* user_data,
    double sample_time_seconds,
    math_engine_kalman_vec3_measurement_f64_t* out_measurement);

Scalar estimate와 0 이상 covariance를 보관하는 caller-owned POD다.

typedef struct math_engine_scalar_kalman_f64 {
    uint32_t struct_size; /**< Exact scalar-state byte 크기 =sizeof(math_engine_scalar_kalman_f64_t)=다. */
    uint32_t reserved; /**< Producer/caller는 0으로 두며 scalar state validator가 nonzero를 거부한다. */
    double estimate; /**< Caller-selected state 단위의 finite scalar estimate다. */
    double covariance; /**< State 단위 제곱의 finite nonnegative scalar covariance다. */
} math_engine_scalar_kalman_f64_t;

Scalar measurement update의 진단 값을 보관하는 caller-owned POD다.

typedef struct math_engine_scalar_kalman_update_info_f64 {
    uint32_t struct_size; /**< Library가 exact info byte 크기 =sizeof(math_engine_scalar_kalman_update_info_f64_t)=를 기록한다. */
    uint32_t reserved; /**< Library가 0으로 기록하고 caller가 무시하는 ABI 확장 slot이다. */
    double innovation; /**< =measurement-observation*estimate=인 signed finite residual이다. */
    double innovation_covariance; /**< =observation^2*P+R=인 finite positive residual covariance다. */
    double kalman_gain; /**< =P*observation/innovation_covariance=인 finite update gain이다. */
} math_engine_scalar_kalman_update_info_f64_t;

General update measurement vector의 포함 dimension 상한 16이다.

#define MATH_ENGINE_KALMAN_GENERAL_MAX_MEASUREMENT_DIMENSION UINT32_C(16)

General filter state vector의 포함 dimension 상한 16이다.

#define MATH_ENGINE_KALMAN_GENERAL_MAX_STATE_DIMENSION UINT32_C(16)

Measurement bit 0 (0x01): position과 position_variance 세 channel을 사용한다.

#define MATH_ENGINE_KALMAN_MEASUREMENT_POSITION (UINT32_C(1) << 0u)

Measurement bit 1 (0x02): velocity와 velocity_variance 세 channel을 사용한다.

#define MATH_ENGINE_KALMAN_MEASUREMENT_VELOCITY (UINT32_C(1) << 1u)

Result bit 7 (0x80): Commit 전에 covariance off-diagonal pair를 평균 대칭화했다.

#define MATH_ENGINE_KALMAN_RESULT_COVARIANCE_SYMMETRIZED (UINT32_C(1) << 7u)

Fixed/general diagnostic result POD의 struct_version unsigned 값 1이다.

#define MATH_ENGINE_KALMAN_RESULT_F64_VERSION_1 UINT32_C(1)

Result bit 5 (0x20): General dense matrix 경로에서 생성된 결과다.

#define MATH_ENGINE_KALMAN_RESULT_GENERAL_MATRIX (UINT32_C(1) << 5u)

Result bit 6 (0x40): Posterior covariance를 Joseph form으로 계산했다.

#define MATH_ENGINE_KALMAN_RESULT_JOSEPH_FORM (UINT32_C(1) << 6u)

Result bit 3 (0x08): Fixed update가 position x/y/z channel을 사용했다.

#define MATH_ENGINE_KALMAN_RESULT_POSITION_USED (UINT32_C(1) << 3u)

Result bit 1 (0x02): State-transition prediction 경로를 실행했다.

#define MATH_ENGINE_KALMAN_RESULT_PREDICTED (UINT32_C(1) << 1u)

Result bit 2 (0x04): Measurement posterior update 경로를 실행했다.

#define MATH_ENGINE_KALMAN_RESULT_UPDATED (UINT32_C(1) << 2u)

Result bit 0 (0x01): 유효한 predicted 또는 updated state가 commit됐다.

#define MATH_ENGINE_KALMAN_RESULT_VALUE (UINT32_C(1) << 0u)

Result bit 4 (0x10): Fixed update가 velocity x/y/z channel을 사용했다.

#define MATH_ENGINE_KALMAN_RESULT_VELOCITY_USED (UINT32_C(1) << 4u)

Constant-velocity state POD의 struct_version unsigned 값 1이다.

#define MATH_ENGINE_KALMAN_VEC3_CV_STATE_F64_VERSION_1 UINT32_C(1)

Vec3 measurement POD의 struct_version unsigned 값 1이다.

#define MATH_ENGINE_KALMAN_VEC3_MEASUREMENT_F64_VERSION_1 UINT32_C(1)

대각 covariance를 갖는 6-state constant-velocity filter를 초기화한다.

• 매개변수 initial_position (in): 초기 위치. 세 축은 같은 caller-selected 길이 단위다.
• 매개변수 initial_velocity (in): 초기 속도(위치 단위/s).
• 매개변수 position_variance (in): 0 이상인 축별 동일 위치 variance(위치 단위 제곱).
• 매개변수 velocity_variance (in): 0 이상인 축별 동일 속도 variance.
• 매개변수 process_acceleration_variance (in): 0 이상인 등방 가속도 process variance.
• 매개변수 out_state (out): 성공 시 초기화한 caller-owned 상태.
• 반환: 성공 또는 INVALID_ARGUMENT, NON_FINITE.

입력과 output은 겹치지 않아야 하며 실패 시 out_state 를 보존한다. 동일 입력에서 동일 bit 결과를 생성하고 tolerance나 callback을 사용하지 않는다.

• Math Engine ownership: initial_position=borrowed initial_velocity=borrowed out_state=caller
• Math Engine nullable: initial_position=false initial_velocity=false out_state=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_kalman_vec3_cv_state_f64_init(
    const math_engine_vec3_f64_t* initial_position,
    const math_engine_vec3_f64_t* initial_velocity,
    double position_variance,
    double velocity_variance,
    double process_acceleration_variance,
    math_engine_kalman_vec3_cv_state_f64_t* out_state);

고정 6-state와 symmetric positive-semidefinite covariance를 검증한다.

• 매개변수 state (in): 검증할 borrowed 상태.
• 반환: 성공 또는 size/version/reserved/non-finite/degenerate 상태 code.

Covariance 대칭·PSD 판정은 고정 내부 tolerance를 사용하며 입력을 변경하지 않는다.

• Math Engine ownership: state=borrowed
• Math Engine nullable: state=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_kalman_vec3_cv_state_f64_validate(
    const math_engine_kalman_vec3_cv_state_f64_t* state);

위치 channel만 활성화하고 단위 대각 variance를 갖는 관측을 초기화한다.

• 매개변수 out_measurement (out): 성공 시 초기화한 caller-owned 관측 storage.
• 반환: 성공 또는 INVALID_ARGUMENT.

실패 시 output을 보존하며 외부 상태나 tolerance를 사용하지 않는다.

• Math Engine ownership: out_measurement=caller
• Math Engine nullable: out_measurement=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_kalman_vec3_measurement_f64_init(
    math_engine_kalman_vec3_measurement_f64_t* out_measurement);

고정·일반 Kalman 연산에 전달할 빈 결과 storage를 초기화한다.

• 매개변수 out_result (out): 성공 시 version과 size가 설정된 caller-owned 결과.
• 반환: 성공 또는 INVALID_ARGUMENT.

실패 시 output을 보존한다.

• Math Engine ownership: out_result=caller
• Math Engine nullable: out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_kalman_result_f64_init(
    math_engine_kalman_result_f64_t* out_result);

양의 시간 step으로 constant-velocity 상태와 covariance를 predict한다.

• 매개변수 prior (in): 검증된 이전 6-state.
• 매개변수 delta_seconds (in): 양의 유한 시간 간격(s).
• 매개변수 out_predicted (out): 성공 시 predicted 상태. prior 와 exact alias 가능하다.
• 매개변수 out_result (out): 초기화된 결과 storage. 다른 모든 인자와 겹치면 안 된다.
• 반환: 성공 또는 validation, overflow, degenerate 상태 code.

x'=F*x 와 white-acceleration P'=F*P*F^T+Q 를 계산한 뒤 covariance를 대칭화·PSD 검증한다. 모든 검증이 끝난 뒤 두 output을 함께 commit하므로 실패 시 모두 보존한다. Callback, cancellation, 동적 allocation은 사용하지 않는다.

• Math Engine ownership: prior=borrowed out_predicted=caller out_result=caller
• Math Engine nullable: prior=false out_predicted=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_kalman_vec3_cv_predict_f64(
    const math_engine_kalman_vec3_cv_state_f64_t* prior,
    double delta_seconds,
    math_engine_kalman_vec3_cv_state_f64_t* out_predicted,
    math_engine_kalman_result_f64_t* out_result);

활성 위치·속도 channel을 순서대로 적용해 Joseph-form posterior를 구한다.

• 매개변수 predicted (in): 검증된 predicted 6-state.
• 매개변수 measurement (in): 활성 channel, 관측 값과 축별 variance.
• 매개변수 out_updated (out): 성공 시 posterior 상태. predicted 와 exact alias 가능하다.
• 매개변수 out_result (out): 초기화된 innovation/covariance 진단 결과.
• 반환: 성공 또는 validation, DEGENERATE, OVERFLOW 상태 code.

Position x/y/z, velocity x/y/z 순으로 scalar update하며 매 channel 뒤 covariance를 대칭화·PSD 검증한다. Singular innovation covariance를 포함한 모든 실패에서 두 output을 보존한다. Measurement와 output, 두 output끼리는 겹치면 안 된다.

• Math Engine ownership: predicted=borrowed measurement=borrowed out_updated=caller out_result=caller
• Math Engine nullable: predicted=false measurement=false out_updated=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_kalman_vec3_cv_update_f64(
    const math_engine_kalman_vec3_cv_state_f64_t* predicted,
    const math_engine_kalman_vec3_measurement_f64_t* measurement,
    math_engine_kalman_vec3_cv_state_f64_t* out_updated,
    math_engine_kalman_result_f64_t* out_result);

일반 predictor/updater가 요구하는 scratch byte 수를 계산한다.

• 매개변수 state_dimension (in): 1..=MATH_ENGINE_KALMAN_GENERAL_MAX_STATE_DIMENSION=.
• 매개변수 measurement_dimension (in): prediction은 0, update는 1 이상인 측정 차원.
• 매개변수 out_size (out): 성공 시 필요한 byte 수. 일반 연산의 workspace는 alignof(double) 에 정렬해야 한다.
• 반환: 성공 또는 INVALID_ARGUMENT.

Allocation을 수행하지 않으며 실패 시 out_size 를 보존한다.

• Math Engine ownership: out_size=caller
• Math Engine nullable: out_size=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_kalman_general_workspace_size_f64(
    uint32_t state_dimension,
    uint32_t measurement_dimension,
    uint64_t* out_size);

일반 dense 선형 model의 x'=F*x, P'=F*P*F^T+Q 를 계산한다.

• 매개변수 prior (in): 차원 n 의 borrowed estimate/covariance view.
• 매개변수 transition (in): row-major n x n transition matrix F.
• 매개변수 process_covariance (in): symmetric PSD n x n process covariance Q.
• 매개변수 context (in): PC_PRECISION 또는 FULL mode의 검증된 context.
• 매개변수 workspace (in,out): caller-owned scratch byte span.
• 매개변수 out_predicted (out): 차원 n 의 caller-owned writable view.
• 매개변수 out_result (out): 초기화된 provenance/covariance 진단 결과.
• 반환: 성공 또는 mode, validation, workspace, overflow/degenerate 상태 code.

PSD tolerance는 max(context.absolute_tolerance, 1e-14) 다. Workspace는 반환된 byte 수 이상이고 double 정렬이어야 하며 모든 input/output과 분리한다. Estimate끼리와 covariance끼리는 각각 exact in-place alias 또는 완전 분리만 허용한다. Embedded profile은 UNSUPPORTED 다. 계산을 scratch에서 완료한 뒤 output을 commit하므로 실패 시 보존한다.

• Math Engine ownership: prior=borrowed transition=borrowed process_covariance=borrowed context=borrowed workspace=caller out_predicted=caller out_result=caller
• Math Engine nullable: prior=false transition=false process_covariance=false context=false out_predicted=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_kalman_general_predict_f64(
    const math_engine_kalman_state_const_view_f64_t* prior,
    const math_engine_matrix_const_view_f64_t* transition,
    const math_engine_matrix_const_view_f64_t* process_covariance,
    const math_engine_context_t* context,
    math_engine_mutable_byte_span_t workspace,
    const math_engine_kalman_state_view_f64_t* out_predicted,
    math_engine_kalman_result_f64_t* out_result);

일반 dense 관측 model의 innovation solve와 Joseph covariance update를 수행한다.

• 매개변수 predicted (in): 차원 n 의 borrowed predicted state view.
• 매개변수 observation (in): row-major m x n 관측 matrix H.
• 매개변수 measurement (in): 길이 measurement_count 의 유한 관측 vector.
• 매개변수 measurement_count (in): 1..일반 측정 차원 상한인 m.
• 매개변수 measurement_covariance (in): symmetric PSD m x m noise covariance R.
• 매개변수 context (in): PC_PRECISION 또는 FULL mode의 검증된 context.
• 매개변수 workspace (in,out): caller-owned, double 정렬 scratch byte span.
• 매개변수 out_updated (out): 차원 n 의 caller-owned writable posterior view.
• 매개변수 out_result (out): 초기화된 innovation/covariance 진단 결과.
• 반환: 성공 또는 mode, validation, workspace, singular/overflow 상태 code.

Innovation covariance를 pivoted dense inverse로 풀고 max(context absolute, 1e-14) tolerance로 PSD/singularity를 판정한다. Workspace는 모든 storage와 분리하고 state input/output은 exact in-place alias 또는 완전 분리만 허용한다. Embedded profile은 UNSUPPORTED 다. 모든 검사 후 commit하므로 실패 시 caller output은 보존된다.

• Math Engine ownership: predicted=borrowed observation=borrowed measurement=borrowed measurement_covariance=borrowed context=borrowed workspace=caller out_updated=caller out_result=caller
• Math Engine nullable: predicted=false observation=false measurement=false measurement_covariance=false context=false out_updated=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_kalman_general_update_f64(
    const math_engine_kalman_state_const_view_f64_t* predicted,
    const math_engine_matrix_const_view_f64_t* observation,
    const double* measurement,
    uint32_t measurement_count,
    const math_engine_matrix_const_view_f64_t* measurement_covariance,
    const math_engine_context_t* context,
    math_engine_mutable_byte_span_t workspace,
    const math_engine_kalman_state_view_f64_t* out_updated,
    math_engine_kalman_result_f64_t* out_result);

Scalar Kalman state를 초기화한다.

• 매개변수 initial_estimate: 초기 state estimate.
• 매개변수 initial_covariance: 0 이상인 초기 covariance.
• 매개변수 out_state: 성공 시 초기화된 state를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code.

실패 시 out_state 는 변경하지 않는다.

• Math Engine ownership: out_state=caller
• Math Engine nullable: out_state=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_scalar_kalman_init_f64(
    double initial_estimate,
    double initial_covariance,
    math_engine_scalar_kalman_f64_t* out_state);

x' = transition*x + control_gain*control model로 predict한다.

• 매개변수 prior: 검증할 borrowed prior state.
• 매개변수 transition: scalar state transition 계수.
• 매개변수 control_gain: scalar control 계수.
• 매개변수 control_input: 현재 control input.
• 매개변수 process_variance: 0 이상인 process noise variance.
• 매개변수 out_predicted: 성공 시 predicted state를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code.

Covariance는 transition^2 * prior_covariance + process_variance 로 계산한다. 실패 시 out_predicted 는 변경하지 않는다.

• Math Engine ownership: prior=borrowed out_predicted=caller
• Math Engine nullable: prior=false out_predicted=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_scalar_kalman_predict_f64(
    const math_engine_scalar_kalman_f64_t* prior,
    double transition,
    double control_gain,
    double control_input,
    double process_variance,
    math_engine_scalar_kalman_f64_t* out_predicted);

measurement = observation*state + noise model로 update한다.

• 매개변수 predicted: 검증할 borrowed predicted state.
• 매개변수 observation: scalar observation 계수.
• 매개변수 measurement: 관측 값.
• 매개변수 measurement_variance: 0 이상인 measurement noise variance.
• 매개변수 out_updated: 성공 시 posterior state를 받는 caller-owned storage.
• 매개변수 out_info: 성공 시 innovation과 gain을 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code.

Innovation covariance가 양수가 아니면 MATH_ENGINE_STATUS_DEGENERATE 를 반환한다. Posterior covariance는 수치적으로 안정적인 Joseph form으로 계산한다. 실패 시 두 output을 모두 변경하지 않는다.

• Math Engine ownership: predicted=borrowed out_updated=caller out_info=caller
• Math Engine nullable: predicted=false out_updated=false out_info=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_scalar_kalman_update_f64(
    const math_engine_scalar_kalman_f64_t* predicted,
    double observation,
    double measurement,
    double measurement_variance,
    math_engine_scalar_kalman_f64_t* out_updated,
    math_engine_scalar_kalman_update_info_f64_t* out_info);