Math Engine Reference: Mpc

문서 탐색

Math Engine 전체 목차

개요

Scalar finite-horizon candidate MPC Math Engine C API를 선언한다.

Caller-owned control sequence 후보를 deterministic하게 평가하여 bounded scalar linear system의 최저 비용 feasible 후보를 선택한다.

실행 원본: include/math_engine/math_engine_mpc.h
분류: 물리·운동·제어

공개 API

Header 사용 시작

이 module의 public declaration을 사용하려면 installed SDK의 다음 header를 include한다.

#include <math_engine/math_engine_mpc.h>

Type과 callback

`math_engine_scalar_mpc_problem_f64_t`

Scalar linear system, quadratic cost와 control bound를 정의하는 borrowed POD다.

typedef struct math_engine_scalar_mpc_problem_f64 {
    uint32_t struct_size; /**< Exact byte size of this legacy scalar problem. */
    uint32_t reserved; /**< Reserved for ABI growth; must be 0. */
    double transition; /**< Finite scalar state coefficient in =x[k+1]=A*x[k]+B*u[k]=. */
    double control_gain; /**< Finite scalar control coefficient B. */
    double initial_state; /**< Finite state at prediction step 0. */
    double target_state; /**< Finite state target used at every stage and terminal. */
    double state_weight; /**< Finite nonnegative stage state-error weight. */
    double control_weight; /**< Finite nonnegative stage control-square weight. */
    double terminal_weight; /**< Finite nonnegative terminal state-error weight. */
    double control_minimum; /**< Finite inclusive feasible control lower bound. */
    double control_maximum; /**< Finite inclusive upper bound, not below minimum. */
} math_engine_scalar_mpc_problem_f64_t;

math_engine_scalar_mpc_problem_f64_t.struct_size
Exact byte size of this legacy scalar problem.
```
uint32_t struct_size;
```
math_engine_scalar_mpc_problem_f64_t.reserved
Reserved for ABI growth; must be 0.
```
uint32_t reserved;
```
math_engine_scalar_mpc_problem_f64_t.transition
Finite scalar state coefficient in x[k+1]=A*x[k]+B*u[k].
```
double transition;
```
math_engine_scalar_mpc_problem_f64_t.control_gain
Finite scalar control coefficient B.
```
double control_gain;
```
math_engine_scalar_mpc_problem_f64_t.initial_state
Finite state at prediction step 0.
```
double initial_state;
```
math_engine_scalar_mpc_problem_f64_t.target_state
Finite state target used at every stage and terminal.
```
double target_state;
```
math_engine_scalar_mpc_problem_f64_t.state_weight
Finite nonnegative stage state-error weight.
```
double state_weight;
```
math_engine_scalar_mpc_problem_f64_t.control_weight
Finite nonnegative stage control-square weight.
```
double control_weight;
```
math_engine_scalar_mpc_problem_f64_t.terminal_weight
Finite nonnegative terminal state-error weight.
```
double terminal_weight;
```
math_engine_scalar_mpc_problem_f64_t.control_minimum
Finite inclusive feasible control lower bound.
```
double control_minimum;
```
math_engine_scalar_mpc_problem_f64_t.control_maximum
Finite inclusive upper bound, not below minimum.
```
double control_maximum;
```

`math_engine_scalar_mpc_result_f64_t`

Candidate selection 결과와 평가 통계를 보관하는 caller-owned POD다.

typedef struct math_engine_scalar_mpc_result_f64 {
    uint32_t struct_size; /**< Exact byte size written for this legacy result. */
    uint32_t reserved; /**< Reserved for ABI growth; written as 0. */
    uint64_t best_candidate_index; /**< Zero-based lowest-cost feasible candidate index. */
    uint64_t evaluated_candidate_count; /**< Candidate prefixes visited before completion. */
    uint64_t feasible_candidate_count; /**< Candidates whose controls all satisfied bounds. */
    double best_cost; /**< Finite minimum quadratic cost in caller-defined cost units. */
    double terminal_state; /**< Final scalar state produced by the selected candidate. */
} math_engine_scalar_mpc_result_f64_t;

math_engine_scalar_mpc_result_f64_t.struct_size
Exact byte size written for this legacy result.
```
uint32_t struct_size;
```
math_engine_scalar_mpc_result_f64_t.reserved
Reserved for ABI growth; written as 0.
```
uint32_t reserved;
```
math_engine_scalar_mpc_result_f64_t.best_candidate_index
Zero-based lowest-cost feasible candidate index.
```
uint64_t best_candidate_index;
```
math_engine_scalar_mpc_result_f64_t.evaluated_candidate_count
Candidate prefixes visited before completion.
```
uint64_t evaluated_candidate_count;
```
math_engine_scalar_mpc_result_f64_t.feasible_candidate_count
Candidates whose controls all satisfied bounds.
```
uint64_t feasible_candidate_count;
```
math_engine_scalar_mpc_result_f64_t.best_cost
Finite minimum quadratic cost in caller-defined cost units.
```
double best_cost;
```
math_engine_scalar_mpc_result_f64_t.terminal_state
Final scalar state produced by the selected candidate.
```
double terminal_state;
```

`math_engine_mpc_dynamics_f64_fn`

한 step의 custom discrete dynamics를 계산하는 borrowed callback이다.

매개변수 state: state_dimension 개의 현재 state 값이다.
매개변수 state_dimension: state와 output의 double 원소 수다.
매개변수 control: control_dimension 개의 현재 control 값이다.
매개변수 control_dimension: control의 double 원소 수다.
매개변수 step_seconds: problem time grid의 양수 step이며 단위는 second다.
매개변수 user_data: problem이 보유하고 caller가 solve 동안 유지하는 opaque pointer다.
매개변수 out_next_state: state_dimension 개의 다음 state를 기록하는 caller scratch다.
반환: 성공 시 MATH_ENGINE_STATUS_OK, 중단하려면 정의된 음수 상태 code다.

Solve를 호출한 thread에서 동기적으로 실행되고 pointer를 저장하지 않는다. Input과 output은 겹치지 않는다. 성공 시 모든 next state를 finite로 기록하고 C++ exception을 ABI 밖으로 전달하면 안 된다.

Math Engine ownership: state=borrowed control=borrowed user_data=borrowed
Math Engine ownership: out_next_state=caller
Math Engine nullable: state=false control=false user_data=true out_next_state=false
Math Engine thread_safety: conditional
Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

typedef math_engine_status_t (*math_engine_mpc_dynamics_f64_fn)(
    const double* state,
    uint32_t state_dimension,
    const double* control,
    uint32_t control_dimension,
    double step_seconds,
    void* user_data,
    double* out_next_state);

`math_engine_mpc_cost_f64_fn`

Custom non-negative stage 또는 terminal cost를 계산하는 borrowed callback이다.

매개변수 state: state_dimension 개의 predicted state다.
매개변수 state_dimension: state의 double 원소 수다.
매개변수 control: stage이면 control_dimension 개 control, terminal이면 NULL이다.
매개변수 control_dimension: control 차원이며 terminal 호출에서도 problem의 M 값이다.
매개변수 stage_index: stage는 [0,horizon_steps), terminal은 horizon_steps 다.
매개변수 terminal: terminal 호출이면 1, stage 호출이면 0이다.
매개변수 user_data: caller가 solve 동안 유지하는 opaque pointer다.
매개변수 out_cost: 성공 시 finite non-negative cost를 기록할 caller storage다.
반환: 성공 시 MATH_ENGINE_STATUS_OK, 중단하려면 정의된 음수 상태 code다.

Solve를 호출한 thread에서 동기적으로 실행되고 pointer를 저장하지 않는다. Cost 단위는 모든 stage/terminal 호출에서 같아야 하며 C++ exception을 전달하면 안 된다.

Math Engine ownership: state=borrowed control=borrowed user_data=borrowed out_cost=caller
Math Engine nullable: state=false control=true user_data=true out_cost=false
Math Engine thread_safety: conditional
Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

typedef math_engine_status_t (*math_engine_mpc_cost_f64_fn)(
    const double* state,
    uint32_t state_dimension,
    const double* control,
    uint32_t control_dimension,
    uint32_t stage_index,
    uint32_t terminal,
    void* user_data,
    double* out_cost);

`math_engine_mpc_problem_f64_t`

Versioned neutral discrete MPC problem이다. Matrix는 row-major이며 transition은 NxN, control_matrix는 NxM이다. Horizon time grid는 k*step_seconds 다. Callback flag가 없으면 matrix와 per-component non-negative quadratic weight를 사용하며, control bounds는 항상 필요하고 state bounds는 flag로 선택한다. 모든 pointer는 solve가 끝날 때까지 borrowed다.

typedef struct math_engine_mpc_problem_f64 {
    uint32_t struct_size; /**< Exact byte size of this neutral problem. */
    uint32_t struct_version; /**< =MATH_ENGINE_MPC_PROBLEM_VERSION_1=. */
    uint32_t state_dimension; /**< State dimension N in inclusive [1, 32]. */
    uint32_t control_dimension; /**< Control dimension M in inclusive [1, 16]. */
    uint32_t horizon_steps; /**< Prediction step count in inclusive [1, 128]. */
    uint32_t flags; /**< Bitwise =MATH_ENGINE_MPC_PROBLEM_FLAG_*= surface selection. */
    uint32_t reserved0; /**< Reserved for ABI growth; must be 0. */
    uint32_t reserved1; /**< Reserved for ABI growth; must be 0. */
    double step_seconds; /**< Finite positive time-grid spacing in seconds. */
    double initial_step_fraction; /**< Initial box-search fraction in (0, 1]. */
    double minimum_step_fraction; /**< Positive stopping fraction not above the initial fraction. */
    /**
     * Borrowed nullable row-major NxN matrix with N*N readable elements. It is required
     * without the dynamics callback, must remain immutable through solve, and is never retained.
     */
    const double* transition;
    /**
     * Borrowed nullable row-major NxM matrix with N*M readable elements. It is required
     * without the dynamics callback, must remain immutable through solve, and is never retained.
     */
    const double* control_matrix;
    /** Non-null borrowed N-element initial state; immutable through solve and never retained. */
    const double* initial_state;
    /** Non-null borrowed N-element target state; immutable through solve and never retained. */
    const double* target_state;
    /**
     * Borrowed nullable N-element nonnegative stage weights. They are required without the
     * cost callback, remain immutable through solve, and are never retained.
     */
    const double* state_weight;
    /**
     * Borrowed nullable M-element nonnegative stage weights. They are required without the
     * cost callback, remain immutable through solve, and are never retained.
     */
    const double* control_weight;
    /**
     * Borrowed nullable N-element nonnegative terminal weights. They are required without the
     * cost callback, remain immutable through solve, and are never retained.
     */
    const double* terminal_weight;
    /** Non-null borrowed M-element inclusive lower bounds; immutable through solve, never retained. */
    const double* control_minimum;
    /** Non-null borrowed M-element inclusive upper bounds; immutable through solve, never retained. */
    const double* control_maximum;
    /**
     * Borrowed nullable N-element state lower bounds, non-null iff STATE_BOUNDS is set;
     * immutable through solve and never retained.
     */
    const double* state_minimum;
    /**
     * Borrowed nullable N-element state upper bounds, non-null iff STATE_BOUNDS is set;
     * immutable through solve and never retained.
     */
    const double* state_maximum;
    /**
     * Nullable synchronous dynamics callback, non-null iff DYNAMICS_CALLBACK is set;
     * invoked only during solve and never retained.
     */
    math_engine_mpc_dynamics_f64_fn dynamics;
    /**
     * Nullable synchronous cost callback, non-null iff COST_CALLBACK is set; invoked only
     * during solve and never retained.
     */
    math_engine_mpc_cost_f64_fn cost;
    /**
     * Nullable borrowed caller context passed unchanged to callbacks; valid through solve
     * and never retained.
     */
    void* user_data;
    uint64_t reserved[2]; /**< Reserved words; both elements must be 0. */
} math_engine_mpc_problem_f64_t;

math_engine_mpc_problem_f64_t.struct_size
Exact byte size of this neutral problem.
```
uint32_t struct_size;
```
math_engine_mpc_problem_f64_t.struct_version
MATH_ENGINE_MPC_PROBLEM_VERSION_1.
```
uint32_t struct_version;
```
math_engine_mpc_problem_f64_t.state_dimension
State dimension N in inclusive [1, 32].
```
uint32_t state_dimension;
```
math_engine_mpc_problem_f64_t.control_dimension
Control dimension M in inclusive [1, 16].
```
uint32_t control_dimension;
```
math_engine_mpc_problem_f64_t.horizon_steps
Prediction step count in inclusive [1, 128].
```
uint32_t horizon_steps;
```
math_engine_mpc_problem_f64_t.flags
Bitwise MATH_ENGINE_MPC_PROBLEM_FLAG_* surface selection.
```
uint32_t flags;
```
math_engine_mpc_problem_f64_t.reserved0
Reserved for ABI growth; must be 0.
```
uint32_t reserved0;
```
math_engine_mpc_problem_f64_t.reserved1
Reserved for ABI growth; must be 0.
```
uint32_t reserved1;
```
math_engine_mpc_problem_f64_t.step_seconds
Finite positive time-grid spacing in seconds.
```
double step_seconds;
```
math_engine_mpc_problem_f64_t.initial_step_fraction
Initial box-search fraction in (0, 1].
```
double initial_step_fraction;
```
math_engine_mpc_problem_f64_t.minimum_step_fraction
Positive stopping fraction not above the initial fraction.
```
double minimum_step_fraction;
```

math_engine_mpc_problem_f64_t.transition

Borrowed nullable row-major NxN matrix with N*N readable elements. It is required without the dynamics callback, must remain immutable through solve, and is never retained.

/**
     * Borrowed nullable row-major NxN matrix with N*N readable elements. It is required
     * without the dynamics callback, must remain immutable through solve, and is never retained.
     */
    const double* transition;

math_engine_mpc_problem_f64_t.control_matrix

Borrowed nullable row-major NxM matrix with N*M readable elements. It is required without the dynamics callback, must remain immutable through solve, and is never retained.

/**
     * Borrowed nullable row-major NxM matrix with N*M readable elements. It is required
     * without the dynamics callback, must remain immutable through solve, and is never retained.
     */
    const double* control_matrix;

math_engine_mpc_problem_f64_t.initial_state
Non-null borrowed N-element initial state; immutable through solve and never retained.
```
/** Non-null borrowed N-element initial state; immutable through solve and never retained. */
    const double* initial_state;
```
math_engine_mpc_problem_f64_t.target_state
Non-null borrowed N-element target state; immutable through solve and never retained.
```
/** Non-null borrowed N-element target state; immutable through solve and never retained. */
    const double* target_state;
```

math_engine_mpc_problem_f64_t.state_weight

Borrowed nullable N-element nonnegative stage weights. They are required without the cost callback, remain immutable through solve, and are never retained.

/**
     * Borrowed nullable N-element nonnegative stage weights. They are required without the
     * cost callback, remain immutable through solve, and are never retained.
     */
    const double* state_weight;

math_engine_mpc_problem_f64_t.control_weight

Borrowed nullable M-element nonnegative stage weights. They are required without the cost callback, remain immutable through solve, and are never retained.

/**
     * Borrowed nullable M-element nonnegative stage weights. They are required without the
     * cost callback, remain immutable through solve, and are never retained.
     */
    const double* control_weight;

math_engine_mpc_problem_f64_t.terminal_weight

Borrowed nullable N-element nonnegative terminal weights. They are required without the cost callback, remain immutable through solve, and are never retained.

/**
     * Borrowed nullable N-element nonnegative terminal weights. They are required without the
     * cost callback, remain immutable through solve, and are never retained.
     */
    const double* terminal_weight;

math_engine_mpc_problem_f64_t.control_minimum
Non-null borrowed M-element inclusive lower bounds; immutable through solve, never retained.
```
/** Non-null borrowed M-element inclusive lower bounds; immutable through solve, never retained. */
    const double* control_minimum;
```
math_engine_mpc_problem_f64_t.control_maximum
Non-null borrowed M-element inclusive upper bounds; immutable through solve, never retained.
```
/** Non-null borrowed M-element inclusive upper bounds; immutable through solve, never retained. */
    const double* control_maximum;
```

math_engine_mpc_problem_f64_t.state_minimum

Borrowed nullable N-element state lower bounds, non-null iff STATE_BOUNDS is set; immutable through solve and never retained.

/**
     * Borrowed nullable N-element state lower bounds, non-null iff STATE_BOUNDS is set;
     * immutable through solve and never retained.
     */
    const double* state_minimum;

math_engine_mpc_problem_f64_t.state_maximum

Borrowed nullable N-element state upper bounds, non-null iff STATE_BOUNDS is set; immutable through solve and never retained.

/**
     * Borrowed nullable N-element state upper bounds, non-null iff STATE_BOUNDS is set;
     * immutable through solve and never retained.
     */
    const double* state_maximum;

math_engine_mpc_problem_f64_t.dynamics

Nullable synchronous dynamics callback, non-null iff DYNAMICS_CALLBACK is set; invoked only during solve and never retained.

/**
     * Nullable synchronous dynamics callback, non-null iff DYNAMICS_CALLBACK is set;
     * invoked only during solve and never retained.
     */
    math_engine_mpc_dynamics_f64_fn dynamics;

math_engine_mpc_problem_f64_t.cost

Nullable synchronous cost callback, non-null iff COST_CALLBACK is set; invoked only during solve and never retained.

/**
     * Nullable synchronous cost callback, non-null iff COST_CALLBACK is set; invoked only
     * during solve and never retained.
     */
    math_engine_mpc_cost_f64_fn cost;

math_engine_mpc_problem_f64_t.user_data

Nullable borrowed caller context passed unchanged to callbacks; valid through solve and never retained.

/**
     * Nullable borrowed caller context passed unchanged to callbacks; valid through solve
     * and never retained.
     */
    void* user_data;

math_engine_mpc_problem_f64_t.reserved
Reserved words; both elements must be 0.
```
uint64_t reserved[2];
```

`math_engine_mpc_result_f64_t`

Solver provenance와 feasibility/quality 진단을 함께 commit하는 caller-owned POD다. predicted_time_seconds=horizon_steps*step_seconds 이고 residual은 box optimizer의 최종 step 진단값, max_constraint_violation 은 state bound의 최대 절대 위반량이다.

typedef struct math_engine_mpc_result_f64 {
    uint32_t struct_size; /**< Exact byte size supplied by the caller. */
    uint32_t struct_version; /**< =MATH_ENGINE_MPC_RESULT_VERSION_1=. */
    uint32_t mode; /**< Context =math_engine_mode_t= used for solver limits. */
    uint32_t quality; /**< Selected =math_engine_algorithm_quality_t=. */
    uint32_t flags; /**< Bitwise =MATH_ENGINE_MPC_RESULT_FLAG_*= provenance. */
    uint32_t state_dimension; /**< Solved state dimension N. */
    uint32_t control_dimension; /**< Solved control dimension M. */
    uint32_t horizon_steps; /**< Solved prediction horizon step count. */
    uint64_t iteration_count; /**< Completed box-optimizer iterations. */
    uint64_t evaluation_count; /**< Objective evaluations including final verification. */
    uint64_t feasible_evaluation_count; /**< Evaluations satisfying enabled state bounds. */
    uint64_t workspace_used_bytes; /**< Required scratch prefix consumed, in bytes. */
    uint64_t operation_fingerprint; /**< Deterministic identity of optimizer and terminal state. */
    double best_cost; /**< Finite minimum stage-plus-terminal cost. */
    double residual; /**< Final box-search step/residual diagnostic. */
    double max_constraint_violation; /**< Maximum absolute enabled state-bound violation. */
    double predicted_time_seconds; /**< =horizon_steps*step_seconds=. */
    uint64_t reserved[2]; /**< Reserved words; both elements must be 0. */
} math_engine_mpc_result_f64_t;

math_engine_mpc_result_f64_t.struct_size
Exact byte size supplied by the caller.
```
uint32_t struct_size;
```
math_engine_mpc_result_f64_t.struct_version
MATH_ENGINE_MPC_RESULT_VERSION_1.
```
uint32_t struct_version;
```
math_engine_mpc_result_f64_t.mode
Context math_engine_mode_t used for solver limits.
```
uint32_t mode;
```
math_engine_mpc_result_f64_t.quality
Selected math_engine_algorithm_quality_t.
```
uint32_t quality;
```
math_engine_mpc_result_f64_t.flags
Bitwise MATH_ENGINE_MPC_RESULT_FLAG_* provenance.
```
uint32_t flags;
```
math_engine_mpc_result_f64_t.state_dimension
Solved state dimension N.
```
uint32_t state_dimension;
```
math_engine_mpc_result_f64_t.control_dimension
Solved control dimension M.
```
uint32_t control_dimension;
```
math_engine_mpc_result_f64_t.horizon_steps
Solved prediction horizon step count.
```
uint32_t horizon_steps;
```
math_engine_mpc_result_f64_t.iteration_count
Completed box-optimizer iterations.
```
uint64_t iteration_count;
```
math_engine_mpc_result_f64_t.evaluation_count
Objective evaluations including final verification.
```
uint64_t evaluation_count;
```
math_engine_mpc_result_f64_t.feasible_evaluation_count
Evaluations satisfying enabled state bounds.
```
uint64_t feasible_evaluation_count;
```
math_engine_mpc_result_f64_t.workspace_used_bytes
Required scratch prefix consumed, in bytes.
```
uint64_t workspace_used_bytes;
```
math_engine_mpc_result_f64_t.operation_fingerprint
Deterministic identity of optimizer and terminal state.
```
uint64_t operation_fingerprint;
```
math_engine_mpc_result_f64_t.best_cost
Finite minimum stage-plus-terminal cost.
```
double best_cost;
```
math_engine_mpc_result_f64_t.residual
Final box-search step/residual diagnostic.
```
double residual;
```
math_engine_mpc_result_f64_t.max_constraint_violation
Maximum absolute enabled state-bound violation.
```
double max_constraint_violation;
```
math_engine_mpc_result_f64_t.predicted_time_seconds
horizon_steps*step_seconds.
```
double predicted_time_seconds;
```
math_engine_mpc_result_f64_t.reserved
Reserved words; both elements must be 0.
```
uint64_t reserved[2];
```

`math_engine_route_progress_t`

Caller가 소유하는 ordered route cursor다. Geometry와 waypoint storage를 소유하지 않는다.

typedef struct math_engine_route_progress {
    uint32_t struct_size; /**< Exact byte size of this route cursor. */
    uint32_t struct_version; /**< =MATH_ENGINE_ROUTE_PROGRESS_VERSION_1=. */
    uint32_t waypoint_count; /**< Immutable positive count of ordered external waypoints. */
    uint32_t current_index; /**< Zero-based active waypoint index below =waypoint_count=. */
    uint64_t completed_lap_count; /**< Completed wrap count for a looping route. */
    uint32_t loop; /**< Boolean: 1 wraps the final waypoint to index 0. */
    uint32_t completed; /**< Boolean: 1 after reaching the final non-looping waypoint. */
    uint64_t reserved[2]; /**< Reserved words; both elements must be 0. */
} math_engine_route_progress_t;

math_engine_route_progress_t.struct_size
Exact byte size of this route cursor.
```
uint32_t struct_size;
```
math_engine_route_progress_t.struct_version
MATH_ENGINE_ROUTE_PROGRESS_VERSION_1.
```
uint32_t struct_version;
```
math_engine_route_progress_t.waypoint_count
Immutable positive count of ordered external waypoints.
```
uint32_t waypoint_count;
```
math_engine_route_progress_t.current_index
Zero-based active waypoint index below waypoint_count.
```
uint32_t current_index;
```
math_engine_route_progress_t.completed_lap_count
Completed wrap count for a looping route.
```
uint64_t completed_lap_count;
```
math_engine_route_progress_t.loop
Boolean: 1 wraps the final waypoint to index 0.
```
uint32_t loop;
```
math_engine_route_progress_t.completed
Boolean: 1 after reaching the final non-looping waypoint.
```
uint32_t completed;
```
math_engine_route_progress_t.reserved
Reserved words; both elements must be 0.
```
uint64_t reserved[2];
```

Macro와 constant

`MATH_ENGINE_MPC_PROBLEM_FLAG_COST_CALLBACK`

Use cost instead of the three nonnegative quadratic-weight arrays.

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

`MATH_ENGINE_MPC_PROBLEM_FLAG_DYNAMICS_CALLBACK`

Use dynamics instead of the row-major transition/control matrices.

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

`MATH_ENGINE_MPC_PROBLEM_FLAG_STATE_BOUNDS`

Enforce component-wise state bounds throughout the prediction horizon.

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

`MATH_ENGINE_MPC_PROBLEM_VERSION_1`

Initial layout version for math_engine_mpc_problem_f64_t.

#define MATH_ENGINE_MPC_PROBLEM_VERSION_1 UINT32_C(1)

`MATH_ENGINE_MPC_RESULT_FLAG_DETERMINISTIC`

Search order, solution and fingerprint are deterministic for reproducible callbacks.

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

`MATH_ENGINE_MPC_RESULT_FLAG_FEASIBLE`

Final trajectory satisfies enabled state bounds within context tolerance.

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

`MATH_ENGINE_MPC_RESULT_FLAG_REFINED`

Desktop/FULL mode used the refined optimization quality policy.

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

`MATH_ENGINE_MPC_RESULT_FLAG_WARM_STARTED`

Solver initialized its control sequence from the caller's warm start.

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

`MATH_ENGINE_MPC_RESULT_VERSION_1`

Initial layout version for math_engine_mpc_result_f64_t.

#define MATH_ENGINE_MPC_RESULT_VERSION_1 UINT32_C(1)

`MATH_ENGINE_ROUTE_PROGRESS_VERSION_1`

Initial layout version for math_engine_route_progress_t.

#define MATH_ENGINE_ROUTE_PROGRESS_VERSION_1 UINT32_C(1)

Function

`math_engine_scalar_mpc_select_f64`

Scalar finite-horizon control sequence 후보 중 최저 비용 후보를 선택한다.

매개변수 problem: 검증할 borrowed scalar system과 cost 정의.
매개변수 candidate_controls: candidate-major layout의 borrowed control 배열. 원소 수는 candidate_count * horizon 이다.
매개변수 candidate_count: 평가할 후보 수. 1 이상이어야 한다.
매개변수 horizon: 각 후보의 control step 수. 1 이상이어야 한다.
매개변수 context: budget, deterministic policy와 cancellation을 제공하는 borrowed context.
매개변수 out_result: 성공 시 선택 결과를 받는 caller-owned storage.
반환: 성공 또는 음수 상태 code.

Dynamics는 x[k+1] = transition*x[k] + control_gain*u[k]=이다. 비용은 각 step의 =state_weight*(x[k]-target)^2 + control_weight*u[k]^2 합과 terminal state 비용이다. Bound 밖 control을 가진 후보는 infeasible로 제외한다. Feasible 후보가 없으면 MATH_ENGINE_STATUS_DEGENERATE 를 반환한다. 동률이면 낮은 candidate index를 선택한다. Horizon은 context iteration budget, 후보 수는 evaluation budget을 소비한다. 함수는 allocation을 수행하지 않는다. State/control/time/cost의 단위는 problem 전 항에서 일관돼야 한다. Candidate-major input은 read-only이고 output과 겹치면 안 된다. Cancellation callback은 호출 thread에서 후보마다 확인하며 같은 input에는 낮은 index 우선 순서로 deterministic하다. 모든 실패에서 partial selection을 commit하지 않고 out_result 를 보존한다.

Math Engine ownership: problem=borrowed candidate_controls=borrowed context=borrowed
Math Engine ownership: out_result=caller
Math Engine nullable: problem=false candidate_controls=false context=false out_result=false
Math Engine thread_safety: conditional

MATH_ENGINE_API math_engine_status_t math_engine_scalar_mpc_select_f64(
    const math_engine_scalar_mpc_problem_f64_t* problem,
    const double* candidate_controls,
    size_t candidate_count,
    size_t horizon,
    const math_engine_context_t* context,
    math_engine_scalar_mpc_result_f64_t* out_result);

`math_engine_mpc_problem_f64_init`

Neutral MPC problem의 dimension과 time-grid 기본값을 초기화한다.

매개변수 state_dimension: state 차원 N이며 1–32다.
매개변수 control_dimension: control 차원 M이며 1–16이다.
매개변수 horizon_steps: prediction step 수이며 1–128이다.
매개변수 step_seconds: finite 양수 time-grid 간격이며 단위는 second다.
매개변수 out_problem: 성공 시 pointer가 비어 있는 기본 problem을 받는 caller storage다.
반환: 성공 시 MATH_ENGINE_STATUS_OK, 범위/NULL 오류 또는 non-finite에는 해당 음수 상태 code다.

기본 search fraction은 0.25, minimum fraction은 =1e-6=이다. 성공 시에만 전체 POD를 commit하며 실패 시 output을 보존한다.

Math Engine ownership: out_problem=caller
Math Engine nullable: out_problem=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_mpc_problem_f64_init(
    uint32_t state_dimension,
    uint32_t control_dimension,
    uint32_t horizon_steps,
    double step_seconds,
    math_engine_mpc_problem_f64_t* out_problem);

`math_engine_mpc_problem_f64_validate`

Problem의 version, dimension, pointer, cost, bound와 callback 계약을 검증한다.

매개변수 problem: 검증할 borrowed problem과 그 배열/callback binding이다.
반환: 유효하면 MATH_ENGINE_STATUS_OK, size/version, pointer/flag 불일치, non-finite, 음수 weight 또는 역전 bound에는 해당 음수 상태 code다.

Callback dynamics를 선택하면 matrix pointer는 사용하지 않고, callback cost를 선택하면 weight pointer는 사용하지 않는다. State-bound flag가 없으면 state bound pointer도 NULL이어야 한다. 읽기만 수행하고 output, allocation, callback 호출 또는 tolerance 판정은 없다.

Math Engine ownership: problem=borrowed
Math Engine nullable: problem=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_mpc_problem_f64_validate(
    const math_engine_mpc_problem_f64_t* problem);

`math_engine_mpc_result_f64_init`

MPC result의 size/version과 나머지 0 기본값을 초기화한다.

매개변수 out_result: 성공 시 초기화된 caller-owned result storage다.
반환: 성공 시 MATH_ENGINE_STATUS_OK, NULL이면 MATH_ENGINE_STATUS_INVALID_ARGUMENT 다.

성공 시에만 전체 POD를 commit하며 실패 시 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_mpc_result_f64_init(
    math_engine_mpc_result_f64_t* out_result);

`math_engine_mpc_workspace_size_f64`

Problem과 context mode에 필요한 caller scratch byte 수를 계산한다.

매개변수 problem: validated borrowed neutral MPC problem이다.
매개변수 context: mode ceiling을 제공하는 validated borrowed context다.
매개변수 out_size: 성공 시 필요한 byte 수를 받는 caller storage다.
반환: 성공 시 MATH_ENGINE_STATUS_OK. Problem/context 오류, 지원하지 않는 mode 또는 mode dimension/horizon ceiling 초과에는 해당 음수 상태 code다.

정확한 크기는 (5*M*horizon+2*N)*sizeof(double)=이다. Game/PC/FULL mode는 각각 N/M/horizon 최대 8/4/16, 16/8/64, 32/16/128을 허용하며 Finance mode는 지원하지 않는다. 실패 시 =out_size 를 보존하고 같은 input에는 deterministic하다.

Math Engine ownership: problem=borrowed context=borrowed out_size=caller
Math Engine nullable: problem=false context=false out_size=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_mpc_workspace_size_f64(
    const math_engine_mpc_problem_f64_t* problem,
    const math_engine_context_t* context,
    uint64_t* out_size);

`math_engine_mpc_solve_f64`

Caller-workspace box optimizer로 neutral finite-horizon MPC를 푼다.

매개변수 problem: solve 동안 배열과 callback binding이 유효한 borrowed problem이다.
매개변수 warm_start: nullable horizon_steps * control_dimension control sequence.
매개변수 context: mode, tolerance, deterministic policy, budget와 cancellation을 제공한다.
매개변수 workspace: 모든 input/output과 겹치지 않는 double-aligned scratch.
매개변수 out_controls: 성공 시 전체 control sequence를 받는 caller storage.
매개변수 out_terminal_state: 성공 시 같은 solution의 terminal state를 받는 N개 storage.
매개변수 out_result: 성공 provenance. 미리 size/version을 초기화해야 한다.
반환: Feasible하고 수렴한 solution만 OK. 실패하면 세 output을 모두 보존한다.

Default model은 x[k+1]=A*x[k]+B*u[k] 이고 matrix는 row-major다. Callback flag가 있으면 dynamics/cost를 호출 thread에서 동기 실행하며 저장하지 않는다. Custom cost는 finite non-negative여야 하고 dynamics output은 모두 finite여야 한다. Feasibility는 state-bound 최대 위반이 absolute+relative 이하일 때 확증된다. Control/state/time/cost 단위는 problem 전체에서 일관돼야 한다.

Context mode ceiling과 evaluation/iteration budget을 적용하고 cancellation을 callback 평가 사이에서 확인한다. =deterministic!=0=이고 callback 결과가 재현 가능하면 search 순서, solution과 operation fingerprint도 재현된다. Workspace는 성공 여부와 무관하게 변경될 수 있다. Workspace, warm start, problem 배열과 세 output은 서로 겹치지 않아야 한다.

Math Engine ownership: problem=borrowed warm_start=borrowed context=borrowed workspace=caller
Math Engine ownership: out_controls=caller out_terminal_state=caller out_result=caller
Math Engine nullable: problem=false warm_start=true context=false workspace.data=false
Math Engine nullable: out_controls=false out_terminal_state=false out_result=false
Math Engine thread_safety: separate_workspace

MATH_ENGINE_API math_engine_status_t math_engine_mpc_solve_f64(
    const math_engine_mpc_problem_f64_t* problem,
    const double* warm_start,
    const math_engine_context_t* context,
    math_engine_mutable_byte_span_t workspace,
    double* out_controls,
    double* out_terminal_state,
    math_engine_mpc_result_f64_t* out_result);

`math_engine_route_progress_init`

Ordered route cursor를 첫 waypoint에 초기화한다.

매개변수 waypoint_count: route의 waypoint 수이며 1 이상이다.
매개변수 loop: 1이면 마지막 waypoint 다음에 0번으로 순환하고 0이면 완료한다.
매개변수 out_progress: 성공 시 초기 cursor를 받는 caller-owned storage다.
반환: 성공 시 MATH_ENGINE_STATUS_OK, 잘못된 count/loop 또는 NULL이면 MATH_ENGINE_STATUS_INVALID_ARGUMENT 다.

Geometry와 거리 단위를 다루지 않고 index만 초기화한다. 성공 시에만 전체 POD를 commit하며 실패 시 output을 보존한다.

Math Engine ownership: out_progress=caller
Math Engine nullable: out_progress=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_route_progress_init(
    uint32_t waypoint_count,
    uint32_t loop,
    math_engine_route_progress_t* out_progress);

`math_engine_route_progress_advance`

Caller가 현재 waypoint 도달을 판정한 경우에만 순서대로 한 칸 전진한다.

매개변수 current: 검증할 borrowed current cursor다.
매개변수 reached: 현재 waypoint에 도달했으면 1, 아니면 0이다.
매개변수 out_progress: 성공 시 다음 cursor를 받는 caller-owned storage다.
반환: 성공 시 MATH_ENGINE_STATUS_OK. Size/version, flag/index, NULL 또는 lap counter overflow 오류에는 해당 음수 상태 code다.

최근접점 탐색, skip 또는 backtrack을 수행하지 않으며 실패 시 output을 보존한다. current==out_progress 인 in-place advance도 허용되며 local copy 뒤 commit한다. 외부 geometry/callback/tolerance/budget을 사용하지 않고 같은 input에 deterministic하다.

Math Engine ownership: current=borrowed out_progress=caller
Math Engine nullable: current=false out_progress=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_route_progress_advance(
    const math_engine_route_progress_t* current,
    uint32_t reached,
    math_engine_route_progress_t* out_progress);

Math Engine Reference: Mpc

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_scalar_mpc_problem_f64_t

math_engine_scalar_mpc_result_f64_t

math_engine_mpc_dynamics_f64_fn

math_engine_mpc_cost_f64_fn

math_engine_mpc_problem_f64_t

math_engine_mpc_result_f64_t

math_engine_route_progress_t

Macro와 constant

MATH_ENGINE_MPC_PROBLEM_FLAG_COST_CALLBACK

MATH_ENGINE_MPC_PROBLEM_FLAG_DYNAMICS_CALLBACK

MATH_ENGINE_MPC_PROBLEM_FLAG_STATE_BOUNDS

MATH_ENGINE_MPC_PROBLEM_VERSION_1

MATH_ENGINE_MPC_RESULT_FLAG_DETERMINISTIC

MATH_ENGINE_MPC_RESULT_FLAG_FEASIBLE

MATH_ENGINE_MPC_RESULT_FLAG_REFINED

MATH_ENGINE_MPC_RESULT_FLAG_WARM_STARTED

MATH_ENGINE_MPC_RESULT_VERSION_1

MATH_ENGINE_ROUTE_PROGRESS_VERSION_1