Math Engine Reference: Integrator

1계 ODE에 사용할 수 있는 적분법의 append-only ABI 식별자다.

typedef enum math_engine_ode_method_f64 {
    MATH_ENGINE_ODE_EULER_F64 = 1, /**< 시작 derivative 하나로 전진하는 fixed-step first-order explicit Euler다. */
    MATH_ENGINE_ODE_RK4_F64 = 2, /**< Step당 네 derivative stage를 사용하는 fixed-step classical fourth-order Runge-Kutta다. */
    MATH_ENGINE_ODE_DORMAND_PRINCE_54_F64 = 3 /**< Embedded fifth/fourth-order pair로 error를 추정하는 adaptive Dormand-Prince method다. */
} math_engine_ode_method_f64_t;

주어진 time과 state에서 dy/dt 를 계산하는 borrowed callback이다.

• 매개변수 time: 평가 시각. start_time, end_time, step과 같은 caller 선택 시간 단위다.
• 매개변수 state: state_count 개의 borrowed 입력 값. 호출이 끝날 때까지만 유효하다.
• 매개변수 state_count: state와 output derivative의 double 원소 수다.
• 매개변수 user_data: caller가 callback 호출 동안 유효하게 유지하는 opaque pointer다.
• 매개변수 out_derivative: state_count 개의 state/time 값을 기록하는 caller storage다.
• 반환: 성공 시 MATH_ENGINE_STATUS_OK, 계산을 중단하려면 정의된 음수 상태 code다.

Integrator를 호출한 thread에서만 동기적으로 호출되며 저장하거나 다른 thread로 전달하지 않는다. state 와 out_derivative 는 겹치지 않으며 callback은 두 pointer를 보관하거나 C++ exception을 ABI 밖으로 전달하면 안 된다. 성공 시 모든 derivative를 finite 값으로 기록해야 한다.

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

typedef math_engine_status_t (*math_engine_ode_derivative_f64_fn)(
    double time,
    const double* state,
    size_t state_count,
    void* user_data,
    double* out_derivative);

고정/적응 step 정책이다. Step 필드는 caller가 정한 시간 단위이며 adaptive method는 safety_factor 와 [=minimum_scale=, =maximum_scale=]로 다음 step을 제한한다.

typedef struct math_engine_ode_options_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_ode_options_f64_t)=로 설정하는 byte 크기다. */
    uint32_t version; /**< =MATH_ENGINE_ODE_OPTIONS_F64_VERSION_1=인 option ABI version이다. */
    uint32_t method; /**< 실행할 =math_engine_ode_method_f64_t= 값이다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Caller는 0으로 설정해야 하며 nonzero option은 INVALID_ARGUMENT로 거부된다. */
    double initial_step; /**< Caller 시간 단위의 finite positive 최초 step magnitude다. */
    double minimum_step; /**< Adaptive method가 error retry에 사용할 finite positive 최소 step magnitude다. */
    double maximum_step; /**< Adaptive method가 넘지 못하는 finite step magnitude ceiling이다. */
    double safety_factor; /**< Error-based ideal step에 곱하는 finite factor로 0보다 크고 1 이하이다. */
    double minimum_scale; /**< 수락/거부 뒤 다음 step이 현재 step 대비 줄어드는 최소 positive 배율이다. */
    double maximum_scale; /**< 수락 뒤 다음 step이 현재 step 대비 커지는 최대 배율이며 minimum 이상이다. */
} math_engine_ode_options_f64_t;

ODE 실행 통계, 적응 step의 최대 정규화 오차와 deterministic 평가 fingerprint다. maximum_error_norm 은 성분별 abs_error/(abs_tol+rel_tol*state_scale) 의 최댓값이다.

typedef struct math_engine_ode_integration_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_ode_integration_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t version; /**< =MATH_ENGINE_ODE_INTEGRATION_RESULT_F64_VERSION_1=인 result ABI version이다. */
    uint32_t method; /**< 실제 사용한 =math_engine_ode_method_f64_t= 값이다. */
    uint32_t flags; /**< =MATH_ENGINE_ODE_FLAG_*= execution bit의 조합이다. */
    uint64_t accepted_step_count; /**< State에 commit되어 timeline을 전진시킨 step 수다. */
    uint64_t rejected_step_count; /**< Adaptive error test에서 commit하지 않고 더 작은 step으로 재시도한 수다. */
    uint64_t evaluation_count; /**< Derivative callback을 동기 호출한 총횟수다. */
    double final_time; /**< 성공 시 요청 =end_time=과 정확히 같은 caller 시간 단위 endpoint다. */
    double last_step; /**< 마지막 accepted step의 signed duration이다. 역방향이면 음수다. */
    double maximum_error_norm; /**< Adaptive method가 계산한 성분별 normalized local error의 전체 최댓값이다. */
    double final_state_norm; /**< 성공한 final state vector의 deterministic Euclidean diagnostic norm이다. */
    uint64_t evaluation_fingerprint; /**< Stage time/state/derivative 순서를 결합한 deterministic replay fingerprint다. */
    uint64_t reserved_u64[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_ode_integration_result_f64_t;

Fixed-step RK4 실행 통계를 반환하는 caller-owned POD다.

typedef struct math_engine_ode_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_ode_result_f64_t)=로 설정하는 legacy result byte 크기다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    uint64_t step_count; /**< State에 commit한 fixed RK4 step 수다. */
    uint64_t evaluation_count; /**< RK4 derivative callback을 동기 호출한 총횟수다. */
    double final_time; /**< 성공 시 요청 endpoint와 정확히 같은 caller 시간 단위 시각이다. */
} math_engine_ode_result_f64_t;

ODE 실행 결과에 기록되는 적응·방향·step 제한 bit다.

enum {
    MATH_ENGINE_ODE_FLAG_ADAPTIVE = 1u << 0, /**< Embedded error estimate로 하나 이상의 step 크기를 조절했다. */
    MATH_ENGINE_ODE_FLAG_REVERSED = 1u << 1, /**< =end_time < start_time=이라 negative step으로 역방향 적분했다. */
    MATH_ENGINE_ODE_FLAG_STEP_CLAMPED = 1u << 2 /**< Initial/next/final step을 min/max 또는 endpoint에 맞춰 clamp했다. */
};

math_engine_ode_integration_result_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_ODE_INTEGRATION_RESULT_F64_VERSION_1 1u

math_engine_ode_options_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_ODE_OPTIONS_F64_VERSION_1 1u

Euler, RK4 또는 adaptive Dormand–Prince 5(4)의 기본 정책을 초기화한다.

• 매개변수 method: math_engine_ode_method_f64_t 값이다.
• 매개변수 out_options: 성공 시 기본 step 정책을 받는 caller-owned storage다.
• 반환: 성공 시 MATH_ENGINE_STATUS_OK, 지원하지 않는 method이면 MATH_ENGINE_STATUS_UNSUPPORTED, NULL output이면 MATH_ENGINE_STATUS_INVALID_ARGUMENT 다.

성공 시에만 out_options 전체를 commit하며 실패 시 기존 값을 보존한다. 전역 상태를 사용하지 않아 같은 storage를 동시에 공유하지 않는 호출끼리는 deterministic하다.

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

MATH_ENGINE_API math_engine_status_t math_engine_ode_options_f64_init(
    uint32_t method,
    math_engine_ode_options_f64_t* out_options);

적분법과 state 차원에 필요한 정확한 double workspace 원소 수를 계산한다.

• 매개변수 method: math_engine_ode_method_f64_t 값이다.
• 매개변수 state_count: state의 double 원소 수이며 1 이상이어야 한다.
• 매개변수 out_workspace_count: 성공 시 필요한 double 원소 수를 받는 caller storage다.
• 반환: 성공 시 MATH_ENGINE_STATUS_OK. 지원하지 않는 method이면 MATH_ENGINE_STATUS_UNSUPPORTED, 0 또는 곱셈 overflow 크기면 MATH_ENGINE_STATUS_INVALID_SIZE 다.

Euler는 3*state_count, RK4는 6*state_count, Dormand–Prince는 =10*state_count=를 반환한다. 실패 시 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_ode_workspace_count_f64(
    uint32_t method,
    size_t state_count,
    size_t* out_workspace_count);

y'=f(t,y) 를 fixed Euler/RK4 또는 adaptive Dormand–Prince 5(4)로 적분한다.

• 매개변수 derivative: 동기 borrowed derivative callback이다.
• 매개변수 user_data: callback에 그대로 전달하는 borrowed pointer며 NULL일 수 있다.
• 매개변수 initial_state: state_count 개의 finite 초기 state 값이다.
• 매개변수 state_count: state 차원이며 1 이상이다.
• 매개변수 start_time: 적분 시작 시각이다.
• 매개변수 end_time: 적분 종료 시각이며 작으면 역방향 적분한다.
• 매개변수 options: 검증된 borrowed method/step 정책이다.
• 매개변수 context: tolerance, iteration/evaluation budget와 cancellation을 제공하는 borrowed context다.
• 매개변수 workspace: method에 필요한 double 원소를 가진 caller-owned scratch다.
• 매개변수 workspace_count: workspace 의 double 원소 수다.
• 매개변수 out_state: 성공 시 state_count 개의 최종 state를 받는 caller storage다.
• 매개변수 out_result: 성공 시 통계·오차·fingerprint를 받는 caller storage다.
• 반환: 성공 시 MATH_ENGINE_STATUS_OK, 잘못된 인자/크기·non-finite·workspace 부족, callback 오류, budget 소진, 취소 또는 수렴 실패에 해당하는 음수 상태 code다.

State 성분 단위는 caller가 정하지만 callback의 derivative는 같은 성분 단위를 시간 단위로 나눈 값이어야 한다. Euler는 3N, RK4는 6N, Dormand–Prince는 10N doubles를 사용한다. Fixed method는 initial_step 을 쓰고, adaptive method는 [=minimum_step=, maximum_step=]에서 step을 조절하며 context의 =absolute + relative*max(|old|,|candidate|) 로 정규화한 embedded error가 1 이하일 때만 step을 accept한다. 같은 input, context와 callback 결과에는 평가 순서와 fingerprint가 deterministic하다.

Callback과 cancellation은 호출 thread에서 동기 실행되고 저장되지 않는다. Input, workspace, 두 output 범위는 서로 겹치지 않아야 하며, workspace는 성공 여부와 무관하게 변경될 수 있다. 모든 실패는 out_state 와 out_result 를 함께 보존한다.

• Math Engine ownership: derivative=borrowed user_data=borrowed initial_state=borrowed
• Math Engine ownership: options=borrowed context=borrowed workspace=caller
• Math Engine ownership: out_state=caller out_result=caller
• Math Engine nullable: derivative=false user_data=true initial_state=false options=false
• Math Engine nullable: context=false workspace=false out_state=false out_result=false
• Math Engine thread_safety: conditional

MATH_ENGINE_API math_engine_status_t math_engine_integrate_ode_f64(
    math_engine_ode_derivative_f64_fn derivative,
    void* user_data,
    const double* initial_state,
    size_t state_count,
    double start_time,
    double end_time,
    const math_engine_ode_options_f64_t* options,
    const math_engine_context_t* context,
    double* workspace,
    size_t workspace_count,
    double* out_state,
    math_engine_ode_integration_result_f64_t* out_result);

Generic ODE를 fixed-step RK4로 적분한다.

• 매개변수 derivative: derivative callback. NULL이면 오류다.
• 매개변수 user_data: callback에 그대로 전달하는 caller-owned pointer. NULL일 수 있다.
• 매개변수 initial_state: state_count 개의 borrowed 초기 state.
• 매개변수 state_count: state 차원. 0이면 오류다.
• 매개변수 start_time: 초기 time.
• 매개변수 end_time: 목표 time. 역방향 적분도 허용한다.
• 매개변수 step_size: 양수 nominal step 크기.
• 매개변수 context: tolerance, budget와 cancellation을 제공하는 borrowed context.
• 매개변수 workspace: 최소 6 * state_count double의 caller-owned scratch storage.
• 매개변수 workspace_count: workspace의 double 원소 수.
• 매개변수 out_state: 성공 시 최종 state를 받는 state_count 개의 caller-owned storage.
• 매개변수 out_result: 성공 시 실행 통계를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code.

State/time 단위는 generic 함수와 같으며 고정 step마다 callback을 네 번 평가한다. 마지막 step은 종료 시각에 맞게 줄이고, context tolerance 안에 도달하면 정확한 end_time 을 commit한다. 같은 input과 callback에는 평가 순서가 deterministic하다. Callback과 cancellation은 호출 thread에서 동기 실행되고 저장되지 않는다. Input, workspace, 두 output 범위는 서로 겹치지 않아야 한다. 실패 시 out_state 와 out_result 는 변경하지 않지만 workspace 내용은 scratch로 변경될 수 있다.

• Math Engine ownership: derivative=borrowed initial_state=borrowed context=borrowed workspace=caller
• Math Engine ownership: out_state=caller out_result=caller user_data=borrowed
• Math Engine nullable: derivative=false initial_state=false context=false workspace=false
• Math Engine nullable: out_state=false out_result=false user_data=true
• Math Engine thread_safety: conditional

MATH_ENGINE_API math_engine_status_t math_engine_integrate_rk4_f64(
    math_engine_ode_derivative_f64_fn derivative,
    void* user_data,
    const double* initial_state,
    size_t state_count,
    double start_time,
    double end_time,
    double step_size,
    const math_engine_context_t* context,
    double* workspace,
    size_t workspace_count,
    double* out_state,
    math_engine_ode_result_f64_t* out_result);