Math Engine Reference: Dynamics

@brief 독립 second-order 알고리즘 식별자다. 값은 append-only ABI다.

typedef enum math_engine_second_order_method_f64 {
    MATH_ENGINE_SECOND_ORDER_EXPLICIT_EULER_F64 = 1, /**< 현재 velocity로 position, 현재 acceleration으로 velocity를 갱신하는 1차 explicit Euler다. */
    MATH_ENGINE_SECOND_ORDER_SEMI_IMPLICIT_EULER_F64 = 2, /**< 먼저 velocity를 갱신한 뒤 새 velocity로 position을 갱신하는 symplectic Euler다. */
    MATH_ENGINE_SECOND_ORDER_POSITION_VERLET_F64 = 3, /**< Position 중심 2차 Verlet step이며 새 endpoint acceleration을 평가한다. */
    MATH_ENGINE_SECOND_ORDER_VELOCITY_VERLET_F64 = 4 /**< 시작/끝 acceleration 평균으로 velocity를 갱신하는 2차 velocity Verlet다. */
} math_engine_second_order_method_f64_t;

@brief Rigid adapter 알고리즘 식별자다. AUTO는 runtime mode로 resolve된다.

typedef enum math_engine_rigid_integrator_method_f64 {
    MATH_ENGINE_RIGID_INTEGRATOR_AUTO_F64 = 0, /**< Context mode가 canonical rigid method를 결정하도록 요청한다. */
    MATH_ENGINE_RIGID_INTEGRATOR_EXPLICIT_EULER_F64 = 1, /**< Position·orientation·velocity를 시작 derivative로 전진하는 1차 method다. */
    MATH_ENGINE_RIGID_INTEGRATOR_SEMI_IMPLICIT_EULER_F64 = 2, /**< 속도를 먼저 갱신하고 새 속도로 pose를 전진하는 1차 symplectic method다. */
    MATH_ENGINE_RIGID_INTEGRATOR_VELOCITY_VERLET_F64 = 3, /**< 시작/끝 acceleration을 사용하는 2차 rigid velocity-Verlet adapter다. */
    MATH_ENGINE_RIGID_INTEGRATOR_RK4_F64 = 4, /**< 고정 step classical fourth-order Runge-Kutta rigid adapter다. */
    MATH_ENGINE_RIGID_INTEGRATOR_DORMAND_PRINCE_54_F64 = 5 /**< Embedded 5(4) error estimate로 step을 수락/거부하는 adaptive Dormand-Prince adapter다. */
} math_engine_rigid_integrator_method_f64_t;

한 forward local step의 method, 시간과 선택적 event boundary request다.

requested_step_seconds must be positive. If EVENT_BOUNDARY is set, event_boundary_local_seconds must lie in the closed requested interval and becomes the accepted endpoint. Without the flag the boundary field must remain zero.

typedef struct math_engine_integrator_step_request_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_integrator_step_request_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_INTEGRATOR_STEP_REQUEST_F64_VERSION_1=인 request ABI version이다. */
    uint32_t method; /**< Second-order 또는 rigid method enum의 지원 값이다. */
    uint32_t flags; /**< =MATH_ENGINE_INTEGRATOR_REQUEST_*= bit의 조합이다. */
    double local_start_seconds; /**< Caller-defined local timeline에서 finite step 시작 시간(s)이다. */
    double requested_step_seconds; /**< Forward integration에 요청한 finite positive duration(s)이다. */
    double event_boundary_local_seconds; /**< Event flag가 있으면 requested interval 안의 exact stop time(s), 없으면 0이다. */
    double reserved_scalar; /**< 향후 ABI 확장용이다. Caller는 +0.0 또는 -0.0으로 설정해야 하며 nonzero request는 INVALID_ARGUMENT로 거부된다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Caller는 모두 0으로 설정해야 하며 nonzero request는 INVALID_ARGUMENT로 거부된다. */
} math_engine_integrator_step_request_f64_t;

@brief Accepted/rejected count, local error와 정확한 accepted endpoint 결과다.

typedef struct math_engine_integrator_step_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_integrator_step_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_INTEGRATOR_STEP_RESULT_F64_VERSION_1=인 result ABI version이다. */
    uint32_t method; /**< AUTO resolution 뒤 실제 실행한 second-order/rigid method 식별자다. */
    uint32_t method_order; /**< 선택 method의 nominal global convergence order다. */
    uint32_t flags; /**< =MATH_ENGINE_INTEGRATOR_STEP_*= result bit의 조합이다. */
    uint32_t reserved0; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    uint64_t accepted_step_count; /**< Output state에 commit된 internal substep 수다. */
    uint64_t rejected_step_count; /**< Adaptive error test에서 commit하지 않고 재시도한 substep 수다. */
    uint64_t evaluation_count; /**< Acceleration callback을 동기 호출한 총횟수다. */
    double local_start_seconds; /**< 검증된 request의 local start time(s)다. */
    double local_end_seconds; /**< 마지막 accepted state가 대응하는 exact local time(s)다. */
    double requested_step_seconds; /**< Caller가 요청한 원래 forward duration(s)이다. */
    double accepted_step_seconds; /**< 실제로 전진한 =local_end-local_start= duration(s)이다. */
    double maximum_local_error_norm; /**< Adaptive method가 수락한 substep 중 최대 무차원 normalized error다. */
    double final_state_norm; /**< 마지막 accepted position/velocity 또는 rigid-state의 deterministic diagnostic norm이다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_integrator_step_result_f64_t;

position''=a(t,position,velocity) 를 평가하는 동기 acceleration callback이다.

• 매개변수 local_time_seconds (in): 현재 integration stage의 local time(s).
• 매개변수 position (in): 길이 state_count 인 borrowed stage 위치 vector.
• 매개변수 velocity (in): 길이 state_count 인 borrowed stage 속도 vector.
• 매개변수 state_count (in): input/output array의 double element 수.
• 매개변수 user_data (in,out): caller가 소유하고 해석하는 opaque pointer.
• 매개변수 out_acceleration (out): 모든 element를 기록할 engine-owned stage buffer.
• 반환: 성공 또는 즉시 상위 step으로 전파할 음수 상태 code.

Callback은 API를 호출한 thread에서 동기 호출되고 반환 뒤 input/output pointer를 보관하면 안 된다. Math Engine은 user_data 를 보관하거나 해제하지 않는다.

• Math Engine ownership: position=borrowed velocity=borrowed user_data=caller out_acceleration=borrowed
• Math Engine nullable: position=false velocity=false user_data=true out_acceleration=false
• Math Engine thread_safety: conditional
• Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

typedef math_engine_status_t (*math_engine_second_order_acceleration_f64_fn)(
    double local_time_seconds,
    const double* position,
    const double* velocity,
    size_t state_count,
    void* user_data,
    double* out_acceleration);

Rigid motion stage의 선형·각가속도를 평가하는 동기 callback이다.

• 매개변수 local_time_seconds (in): 현재 integration stage의 local time(s).
• 매개변수 state (in): engine-owned borrowed stage state.
• 매개변수 user_data (in,out): caller가 소유하고 해석하는 opaque pointer.
• 매개변수 out_linear_acceleration_mps2 (out): 완전히 기록할 world-frame 선형 가속도(m/s^2).
• 매개변수 out_angular_acceleration_radps2 (out): 완전히 기록할 state frame 각가속도(rad/s^2).
• 반환: 성공 또는 즉시 상위 step으로 전파할 음수 상태 code.

Orientation maps body coordinates into state->frame_id. Angular velocity and angular acceleration are expressed in that frame and quaternion differentiation uses q'=0.5*(0,omega)*q. Position, velocity, orientation and angular velocity are the integration stage variables. The two acceleration fields are last-accepted diagnostics and must not be used as implicit force inputs. Callback은 호출 thread에서 동기 실행되고 모든 pointer를 반환 뒤 보관하면 안 되며 두 output을 완전히 기록해야 한다.

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

typedef math_engine_status_t (*math_engine_rigid_acceleration_f64_fn)(
    double local_time_seconds,
    const math_engine_motion_state_f64_t* state,
    void* user_data,
    math_engine_vec3_f64_t* out_linear_acceleration_mps2,
    math_engine_vec3_f64_t* out_angular_acceleration_radps2);

@brief 명시적 local event boundary가 있음을 나타내는 request bit다.

enum {
    MATH_ENGINE_INTEGRATOR_REQUEST_EVENT_BOUNDARY = UINT32_C(1) << 0 /**< =event_boundary_local_seconds=를 exact accepted endpoint로 사용한다. */
};

@brief Step acceptance, event, adaptivity와 error-estimate 상태 bit다.

enum {
    MATH_ENGINE_INTEGRATOR_STEP_ACCEPTED = UINT32_C(1) << 0, /**< 적어도 한 substep이 수락되어 output state에 commit됐다. */
    MATH_ENGINE_INTEGRATOR_STEP_EVENT_BOUNDARY_REACHED = UINT32_C(1) << 1, /**< Accepted endpoint가 요청한 local event boundary와 정확히 같다. */
    MATH_ENGINE_INTEGRATOR_STEP_ADAPTIVE = UINT32_C(1) << 2, /**< Method가 embedded error estimate로 하나 이상의 step 크기를 조절했다. */
    MATH_ENGINE_INTEGRATOR_STEP_ERROR_NOT_ESTIMATED = UINT32_C(1) << 3 /**< 선택 method가 local error estimate를 제공하지 않아 관련 값이 0이다. */
};

math_engine_integrator_step_request_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_INTEGRATOR_STEP_REQUEST_F64_VERSION_1 UINT32_C(1)

math_engine_integrator_step_result_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_INTEGRATOR_STEP_RESULT_F64_VERSION_1 UINT32_C(1)

지정한 rigid method의 local step request를 초기화한다.

• 매개변수 method (in): AUTO 또는 지원 rigid integrator 식별자.
• 매개변수 out_request (out): 성공 시 0.01초 기본 step과 ABI identity가 설정된 request.
• 반환: 성공 또는 INVALID_ARGUMENT, UNSUPPORTED.

실패 시 output을 보존하고 외부 state를 사용하지 않는다.

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

MATH_ENGINE_API math_engine_status_t math_engine_integrator_step_request_f64_init(
    uint32_t method,
    math_engine_integrator_step_request_f64_t* out_request);

Dynamics step의 빈 결과 storage를 초기화한다.

• 매개변수 out_result (out): 성공 시 size/version이 설정된 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_integrator_step_result_f64_init(
    math_engine_integrator_step_result_f64_t* out_result);

Second-order method와 dimension에 필요한 정확한 workspace element 수를 구한다.

• 매개변수 method (in): 지원하는 explicit/semi-implicit/position/velocity Verlet 식별자.
• 매개변수 state_count (in): 1 이상이고 SIZE_MAX/4 이하인 state dimension.
• 매개변수 out_workspace_count (out): 성공 시 4*state_count=인 =double element 수.
• 반환: 성공 또는 INVALID_ARGUMENT, INVALID_SIZE, UNSUPPORTED.

Byte 수가 아니며 실패 시 output을 보존한다.

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

MATH_ENGINE_API math_engine_status_t math_engine_second_order_workspace_count_f64(
    uint32_t method,
    size_t state_count,
    size_t* out_workspace_count);

Immutable input에서 한 second-order local step을 실행한다.

• 매개변수 acceleration (in): stage acceleration callback. 동기 호출되고 보관되지 않는다.
• 매개변수 user_data (in,out): callback에 그대로 전달할 caller-owned opaque pointer.
• 매개변수 position (in): 길이 state_count 인 현재 위치 array.
• 매개변수 velocity (in): 길이 state_count 인 현재 속도 array.
• 매개변수 previous_position (in): Position Verlet에 필수인 이전 위치, 다른 method는 NULL 가능.
• 매개변수 state_count (in): 모든 state array의 double element 수.
• 매개변수 request (in): method, local start/step과 선택적 event boundary.
• 매개변수 context (in): evaluation budget와 cancel callback을 가진 검증된 context.
• 매개변수 workspace (in,out): 최소 query 결과 크기의 caller scratch double array.
• 매개변수 workspace_count (in): workspace의 double element 수.
• 매개변수 out_position (out): accepted endpoint 위치 array.
• 매개변수 out_velocity (out): accepted endpoint 속도 array.
• 매개변수 out_previous_position (out): 성공 시 현재 position 복사본.
• 매개변수 out_result (out): method/order, endpoint, evaluation과 error-estimate flag.
• 반환: 성공 또는 validation, workspace, callback, CANCELLED, BUDGET_EXHAUSTED, non-finite 상태 code.

Position Verlet requires previous_position and derives velocity with the centered difference. Other methods ignore a NULL previous position. Velocity Verlet evaluates acceleration at the current state and at a predicted endpoint; velocity-dependent force is supported but does not receive a second-order accuracy claim. All three output arrays, all supplied input arrays and workspace must be mutually non-overlapping. On failure all outputs and out_result are preserved; workspace is scratch. Callback과 cancel은 호출 thread에서만 동기 실행한다. Workspace와 모든 input/output array는 상호 non-overlap이고 out_result 도 이 storage와 분리해야 한다.

• Math Engine ownership: acceleration=borrowed user_data=caller position=borrowed velocity=borrowed previous_position=borrowed request=borrowed context=borrowed workspace=caller out_position=caller out_velocity=caller out_previous_position=caller out_result=caller
• Math Engine nullable: acceleration=false user_data=true position=false velocity=false previous_position=true request=false context=false workspace=false out_position=false out_velocity=false out_previous_position=false out_result=false
• Math Engine thread_safety: conditional

MATH_ENGINE_API math_engine_status_t math_engine_second_order_step_f64(
    math_engine_second_order_acceleration_f64_fn acceleration,
    void* user_data,
    const double* position,
    const double* velocity,
    const double* previous_position,
    size_t state_count,
    const math_engine_integrator_step_request_f64_t* request,
    const math_engine_context_t* context,
    double* workspace,
    size_t workspace_count,
    double* out_position,
    double* out_velocity,
    double* out_previous_position,
    math_engine_integrator_step_result_f64_t* out_result);

검증된 runtime context에 맞는 canonical rigid method를 resolve한다.

• 매개변수 context (in): mode를 읽을 borrowed context.
• 매개변수 out_method (out): 성공 시 concrete rigid method 식별자.
• 반환: 성공 또는 context validation/unsupported 상태 code.

GAME_FAST selects fixed semi-implicit Euler. PC_PRECISION and FULL select adaptive Dormand-Prince 5(4). FINANCE_FIXED rejects binary rigid dynamics. 실패 시 output을 보존하며 callback/cancellation은 사용하지 않는다.

• Math Engine ownership: context=borrowed out_method=caller
• Math Engine nullable: context=false out_method=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_rigid_integrator_default_method_f64(
    const math_engine_context_t* context,
    uint32_t* out_method);

Resolved rigid method에 필요한 정확한 workspace element 수를 구한다.

• 매개변수 method (in): AUTO 또는 concrete rigid method 식별자.
• 매개변수 out_workspace_count (out): 성공 시 caller가 제공할 double element 수.
• 반환: 성공 또는 INVALID_ARGUMENT, UNSUPPORTED.

AUTO/DP5(4)는 130, RK4는 78, fixed method는 1 element다. 실패 시 output을 보존한다.

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

MATH_ENGINE_API math_engine_status_t math_engine_rigid_integrator_workspace_count_f64(
    uint32_t method,
    size_t* out_workspace_count);

한 neutral rigid-motion state를 명시 local interval 동안 integrate한다.

• 매개변수 acceleration (in): stage별 선형·각가속도 callback.
• 매개변수 user_data (in,out): callback에 전달할 caller-owned opaque pointer.
• 매개변수 current (in): 검증된 현재 SI motion state.
• 매개변수 request (in): method, local time/step과 선택적 event boundary.
• 매개변수 context (in): mode, tolerance, budget와 cancel callback.
• 매개변수 workspace (in,out): method query 이상 크기의 caller scratch double array.
• 매개변수 workspace_count (in): workspace의 double element 수.
• 매개변수 out_state (out): accepted endpoint의 caller-owned motion state.
• 매개변수 out_result (out): resolved method, step/evaluation과 local error 진단.
• 반환: 성공 또는 validation, workspace, callback/integrator, CANCELLED, BUDGET_EXHAUSTED 상태 code.

AUTO is resolved from context. Fixed algorithms use one caller-owned scratch double; RK4 uses 78 and adaptive DP5(4) uses 130. The adapter normalizes every committed orientation, never owns events/collisions, and only stops at an explicitly supplied local boundary. Fixed algorithms are deterministic for identical callback results; adaptive DP5(4)는 context tolerance/budget를 따른다. Callback과 cancel은 호출 thread에서 동기 실행되고 보관되지 않는다. current, workspace, out_state, out_result 는 상호 non-overlap이며 실패 시 output을 보존하고 scratch 내용은 미지정이다.

• Math Engine ownership: acceleration=borrowed user_data=caller current=borrowed request=borrowed context=borrowed workspace=caller out_state=caller out_result=caller
• Math Engine nullable: acceleration=false user_data=true current=false request=false context=false workspace=false out_state=false out_result=false
• Math Engine thread_safety: conditional

MATH_ENGINE_API math_engine_status_t math_engine_rigid_integrator_step_f64(
    math_engine_rigid_acceleration_f64_fn acceleration,
    void* user_data,
    const math_engine_motion_state_f64_t* current,
    const math_engine_integrator_step_request_f64_t* request,
    const math_engine_context_t* context,
    double* workspace,
    size_t workspace_count,
    math_engine_motion_state_f64_t* out_state,
    math_engine_integrator_step_result_f64_t* out_result);