Math Engine Reference: Trajectory

@brief Trajectory 계산 결과의 수치 해석 품질 분류다.

typedef enum math_engine_trajectory_quality {
    MATH_ENGINE_TRAJECTORY_QUALITY_INVALID = 0, /**< 결과가 초기화 상태이거나 수치 품질이 없음을 나타낸다. */
    MATH_ENGINE_TRAJECTORY_QUALITY_EXACT_ANALYTIC = 1, /**< Closed-form 계산 또는 exact sample knot에서 얻은 결과다. */
    MATH_ENGINE_TRAJECTORY_QUALITY_SECOND_ORDER = 2, /**< Local truncation/error 거동이 step 간격의 제곱 차수인 결과다. */
    MATH_ENGINE_TRAJECTORY_QUALITY_FIRST_ORDER = 3, /**< Local truncation/error 거동이 step 간격의 일차인 결과다. */
    MATH_ENGINE_TRAJECTORY_QUALITY_APPROXIMATE_BOUNDED = 4 /**< 명시된 residual/error bound를 가진 반복 근사 결과다. */
} math_engine_trajectory_quality_t;

@brief 엄격히 증가하는 시간과 strided row-major component의 borrowed view다.

times 는 초, value_stride 는 double element 단위다. Pointer storage는 호출 동안 유효해야 하고 Math Engine이 보관하거나 해제하지 않는다.

typedef struct math_engine_sample_series_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_sample_series_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_SAMPLE_SERIES_F64_VERSION_1=인 view ABI version이다. */
    const double* times; /**< Caller-owned strictly increasing =sample_count=개 시간(s)을 빌려 읽는다. Non-null이며 호출 뒤 보관하지 않는다. */
    const double* values; /**< Caller-owned strided sample-major 값 storage를 빌려 읽는다. 최소 마지막 sample/component까지 유효하며 보관하지 않는다. */
    size_t sample_count; /**< =times=와 =values=에 존재하는 sample row 수다. 1 이상이어야 한다. */
    size_t component_count; /**< Sample row마다 의미 있는 연속 component 수다. 1 이상이어야 한다. */
    size_t value_stride; /**< 인접 sample row 시작 사이의 =double= 원소 수다. =component_count= 이상이다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Caller는 모두 0으로 설정하고 callee는 무시한다. */
} math_engine_sample_series_f64_t;

@brief 보간·미분·cut·resampling이 공유하는 caller-owned 결과 metadata다.

typedef struct math_engine_trajectory_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_trajectory_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_TRAJECTORY_RESULT_F64_VERSION_1=인 result ABI version이다. */
    uint32_t flags; /**< =MATH_ENGINE_TRAJECTORY_RESULT_*= bit의 조합이다. */
    int32_t quality; /**< 수치 결과의 =math_engine_trajectory_quality_t= 값이다. */
    uint32_t derivative_order; /**< 반환 값이 원 series의 몇 차 시간 미분인지 나타낸다. 원 값은 0이다. */
    uint32_t reserved32; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    uint64_t segment_index; /**< Query를 포함하는 왼쪽 source segment/sample index다. */
    uint64_t written_count; /**< 성공 시 caller output에 실제 기록한 sample 또는 scalar 원소 수다. */
    uint64_t required_count; /**< 전체 결과를 담는 데 필요한 output 원소 수다. Size query/부족 오류에서도 제공될 수 있다. */
    double query_time_seconds; /**< 분석한 local trajectory time(s)다. */
    double interpolation_parameter; /**< 선택 segment 왼쪽 0, 오른쪽 1인 무차원 interpolation parameter다. */
    double error_bound; /**< 반환 값 단위로 표현한 보수적 절대 error bound다. Not-estimated flag이면 0이다. */
    double total_measure; /**< Operation에 따라 전체 duration(s), arc length 또는 적분 measure를 기록한다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_trajectory_result_f64_t;

@brief 비행 시간 오름차순인 최대 두 개의 immutable launch solution이다.

typedef struct math_engine_projectile_solution_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_projectile_solution_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_PROJECTILE_SOLUTION_F64_VERSION_1=인 result ABI version이다. */
    uint32_t flags; /**< VALUE/NO_SOLUTION/MULTIPLE_SOLUTIONS 등 trajectory result bit의 조합이다. */
    int32_t quality; /**< Root/model solution의 =math_engine_trajectory_quality_t= 값이다. */
    uint32_t solution_count; /**< 유효한 leading array slot 수다. 0..2 범위이며 비행시간 오름차순이다. */
    uint32_t reserved32; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    math_engine_vec3_f64_t launch_velocity_mps[2]; /**< 각 solution의 world-frame 초기 속도(m/s)다. Leading =solution_count=개만 유효하다. */
    double flight_time_seconds[2]; /**< 각 solution이 target에 도달하는 positive 비행시간(s)이다. */
    double residual_meters[2]; /**< 계산된 impact와 target 사이의 보수적 signed/absolute residual(m)이다. */
    uint64_t iterations; /**< 모든 solution root refinement에 사용한 총 iteration 수다. */
    uint64_t evaluations; /**< 모든 candidate에 사용한 trajectory/predicate 평가 총횟수다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_projectile_solution_f64_t;

@brief Pure proportional-navigation 가속도 command와 진단 결과다.

typedef struct math_engine_guidance_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_guidance_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_GUIDANCE_RESULT_F64_VERSION_1=인 result ABI version이다. */
    uint32_t flags; /**< VALUE와 clamp/quality를 나타내는 trajectory result bit의 조합이다. */
    int32_t quality; /**< Guidance 계산의 =math_engine_trajectory_quality_t= 값이다. */
    math_engine_vec3_f64_t commanded_acceleration_mps2; /**< Limit 적용 뒤 world-frame proportional-navigation command(m/s²)다. */
    math_engine_vec3_f64_t line_of_sight_rate_radps; /**< Relative position 축 주위 world-frame line-of-sight angular rate(rad/s)다. */
    double closing_speed_mps; /**< 두 물체가 접근하면 positive인 line-of-sight closing speed(m/s)다. */
    double unclamped_acceleration_mps2; /**< Limit 적용 전 command vector magnitude(m/s²)다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_guidance_result_f64_t;

@brief 한 propulsion step의 순수 예측 결과다.

Tank/controller의 mutable state는 consumer가 소유하며 이 POD에는 보관 pointer가 없다.

typedef struct math_engine_propulsion_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_propulsion_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_PROPULSION_RESULT_F64_VERSION_1=인 result ABI version이다. */
    uint32_t flags; /**< VALUE/FUEL_LIMITED/THRUST_ACTIVE 등 trajectory result bit의 조합이다. */
    int32_t quality; /**< Propulsion prediction의 =math_engine_trajectory_quality_t= 값이다. */
    double thrust_newtons; /**< Fuel/command limit 적용 뒤 step 동안의 nonnegative thrust(N)다. */
    double impulse_newton_seconds; /**< Step에 전달한 thrust time integral(N·s)이다. */
    double fuel_used_kg; /**< Step에서 소비한 nonnegative propellant mass(kg)다. */
    double remaining_fuel_kg; /**< Step 종료 뒤 남은 nonnegative propellant mass(kg)다. */
    double delta_velocity_mps; /**< 입력 vehicle mass 기준 ideal velocity increment(m/s)다. */
    double remaining_runtime_seconds; /**< 같은 active thrust/mass-flow 조건을 유지할 때 남은 연소시간(s)이다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_propulsion_result_f64_t;

@brief Trajectory·projectile·guidance·propulsion 결과의 상태 bit다.

enum {
    MATH_ENGINE_TRAJECTORY_RESULT_VALUE = 1u << 0, /**< Result POD나 output buffer에 usable value를 commit했다. */
    MATH_ENGINE_TRAJECTORY_RESULT_EXACT_KNOT = 1u << 1, /**< Query time이 source sample knot와 정확히 일치해 보간하지 않았다. */
    MATH_ENGINE_TRAJECTORY_RESULT_INTERPOLATED = 1u << 2, /**< 두 source knot 사이에서 interpolation으로 값을 만들었다. */
    MATH_ENGINE_TRAJECTORY_RESULT_ENDPOINT_INCLUDED = 1u << 3, /**< Cut/resampling output에 닫힌 구간 endpoint를 명시적으로 포함했다. */
    MATH_ENGINE_TRAJECTORY_RESULT_CUT_APPLIED = 1u << 4, /**< Source domain의 일부 구간만 선택하거나 잘라 output을 만들었다. */
    MATH_ENGINE_TRAJECTORY_RESULT_ERROR_NOT_ESTIMATED = 1u << 5, /**< 인접 sample/모델 정보가 부족해 =error_bound=를 제공하지 못했다. */
    MATH_ENGINE_TRAJECTORY_RESULT_NO_SOLUTION = 1u << 6, /**< 유효 입력이지만 요구 조건을 만족하는 projectile/guidance solution이 없다. */
    MATH_ENGINE_TRAJECTORY_RESULT_MULTIPLE_SOLUTIONS = 1u << 7, /**< 비행시간이 다른 둘 이상의 유효 projectile solution을 반환했다. */
    MATH_ENGINE_TRAJECTORY_RESULT_FUEL_LIMITED = 1u << 8, /**< 요청 thrust/step이 남은 fuel 또는 runtime에 의해 제한됐다. */
    MATH_ENGINE_TRAJECTORY_RESULT_THRUST_ACTIVE = 1u << 9 /**< 계산 step 중 positive thrust가 실제 적용됐다. */
};

math_engine_guidance_result_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_GUIDANCE_RESULT_F64_VERSION_1 UINT32_C(1)

math_engine_projectile_solution_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_PROJECTILE_SOLUTION_F64_VERSION_1 UINT32_C(1)

math_engine_propulsion_result_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_PROPULSION_RESULT_F64_VERSION_1 UINT32_C(1)

math_engine_sample_series_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_SAMPLE_SERIES_F64_VERSION_1 UINT32_C(1)

math_engine_trajectory_result_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_TRAJECTORY_RESULT_F64_VERSION_1 UINT32_C(1)

Sample series의 ABI, storage 범위, 유한 값과 시간 단조성을 검증한다.

• 매개변수 series (in): 검증할 borrowed series. 시간은 초이고 값 단위는 caller-defined다.
• 반환: 성공 또는 pointer/size/version/non-finite/순서 오류 상태 code.

sample_count 와 component_count 는 1 이상, value_stride 는 component 수 이상이어야 하며 시간은 엄격히 증가해야 한다. 입력을 변경하지 않고 allocation하지 않는다.

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

MATH_ENGINE_API math_engine_status_t math_engine_sample_series_f64_validate(
    const math_engine_sample_series_f64_t* series);

Trajectory 연산에 전달할 빈 결과 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_trajectory_result_f64_init(
    math_engine_trajectory_result_f64_t* out_result);

Projectile 연산에 전달할 빈 solution storage를 초기화한다.

• 매개변수 out_solution (out): 성공 시 size/version이 설정된 caller-owned 결과.
• 반환: 성공 또는 INVALID_ARGUMENT. 실패 시 output을 보존한다.
• Math Engine ownership: out_solution=caller
• Math Engine nullable: out_solution=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_projectile_solution_f64_init(
    math_engine_projectile_solution_f64_t* out_solution);

Guidance 연산에 전달할 빈 결과 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_guidance_result_f64_init(
    math_engine_guidance_result_f64_t* out_result);

Propulsion 연산에 전달할 빈 결과 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_propulsion_result_f64_init(
    math_engine_propulsion_result_f64_t* out_result);

범위 안 query time에서 piecewise-linear component 값을 sample한다.

• 매개변수 series (in): 시간(s)과 component 값의 검증 가능한 borrowed series.
• 매개변수 query_time_seconds (in): 첫 sample 이상 마지막 sample 이하인 시간(s).
• 매개변수 context (in): 유효한 tolerance/budget context. 이 연산은 cancel을 호출하지 않는다.
• 매개변수 out_components (out): 최소 series->component_count 개인 caller buffer.
• 매개변수 output_component_count (in): out_components 의 double element capacity.
• 매개변수 out_result (out): 초기화된 sample provenance 결과.
• 반환: 성공 또는 validation, range, buffer, overflow 상태 code.

Extrapolation은 하지 않고 exact knot 또는 해당 segment의 선형식을 deterministic하게 사용한다. Borrowed input, context, 두 output은 서로 겹치면 안 되며 실패 시 output을 보존한다.

• Math Engine ownership: series=borrowed context=borrowed out_components=caller out_result=caller
• Math Engine nullable: series=false context=false out_components=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_trajectory_linear_sample_f64(
    const math_engine_sample_series_f64_t* series,
    double query_time_seconds,
    const math_engine_context_t* context,
    double* out_components,
    size_t output_component_count,
    math_engine_trajectory_result_f64_t* out_result);

Local nonuniform Lagrange polynomial의 1차 또는 2차 미분을 계산한다.

• 매개변수 series (in): 엄격히 증가하는 시간(s)과 component 값의 borrowed series.
• 매개변수 query_time_seconds (in): series 범위 안의 미분 평가 시간(s).
• 매개변수 derivative_order (in): 지원하는 차수 1 또는 2.
• 매개변수 context (in): 검증할 runtime context. Callback/cancel은 호출하지 않는다.
• 매개변수 out_components (out): 값 단위/s^=derivative_order= 결과 buffer.
• 매개변수 output_component_count (in): output의 double element capacity.
• 매개변수 out_result (out): 사용한 stencil, 차수와 quality 결과.
• 반환: 성공 또는 unsupported, sample 부족, range/buffer/overflow 상태 code.

1차는 2개 이상, 2차는 3개 이상 sample이 필요하다. 가능한 경우 local 3-point polynomial을 사용하며 error estimate는 제공하지 않는다. 모든 storage는 분리해야 하고 실패 시 output을 보존한다.

• Math Engine ownership: series=borrowed context=borrowed out_components=caller out_result=caller
• Math Engine nullable: series=false context=false out_components=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_trajectory_derivative_f64(
    const math_engine_sample_series_f64_t* series,
    double query_time_seconds,
    uint32_t derivative_order,
    const math_engine_context_t* context,
    double* out_components,
    size_t output_component_count,
    math_engine_trajectory_result_f64_t* out_result);

Series 시작부터 명시 endpoint까지 sample을 복사하고 필요하면 endpoint를 보간한다.

• 매개변수 series (in): 원본 시간(s)과 component 값의 borrowed series.
• 매개변수 has_cut (in): 1이면 cut_time_seconds 사용, 0이면 마지막 sample까지 복사한다.
• 매개변수 cut_time_seconds (in): =has_cut==1=일 때 series 범위 안의 endpoint(s).
• 매개변수 context (in): 검증할 runtime context. Callback/cancel은 호출하지 않는다.
• 매개변수 out_times (out): packed output 시간 buffer(s).
• 매개변수 out_values (out): sample-major packed component output buffer.
• 매개변수 output_sample_capacity (in): 두 output이 수용하는 sample 수.
• 매개변수 out_result (out): written/required count와 endpoint provenance.
• 반환: 성공 또는 validation, range, buffer, overflow 상태 code.

has_cut 은 정확히 0 또는 1이며 별도 flag이므로 0초 cut도 모호하지 않다. Endpoint는 정확히 한 번 포함한다. 모든 input/output은 분리하고 실패 시 output을 보존한다.

• Math Engine ownership: series=borrowed context=borrowed out_times=caller out_values=caller out_result=caller
• Math Engine nullable: series=false context=false out_times=false out_values=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_trajectory_cut_f64(
    const math_engine_sample_series_f64_t* series,
    int32_t has_cut,
    double cut_time_seconds,
    const math_engine_context_t* context,
    double* out_times,
    double* out_values,
    size_t output_sample_capacity,
    math_engine_trajectory_result_f64_t* out_result);

일정 시간 grid로 선형 resample하고 요청 endpoint를 정확히 한 번 포함한다.

• 매개변수 series (in): 원본 시간(s)과 component 값의 borrowed series.
• 매개변수 start_time_seconds (in): series 범위 안의 시작 시간(s).
• 매개변수 end_time_seconds (in): 시작 이상이고 series 범위 안인 끝 시간(s).
• 매개변수 interval_seconds (in): 양의 grid 간격(s).
• 매개변수 context (in): endpoint 근접 tolerance와 max_evaluations budget.
• 매개변수 out_times (out): packed output 시간 buffer(s).
• 매개변수 out_values (out): sample-major packed component output buffer.
• 매개변수 output_sample_capacity (in): 두 output이 수용하는 sample 수.
• 매개변수 out_result (out): written/required count와 전체 시간 span.
• 반환: 성공 또는 validation, range, buffer, budget, overflow 상태 code.

마지막 regular grid와 endpoint 차이가 context tolerance 이내면 endpoint로 대체하고, 아니면 endpoint를 추가한다. 필요한 sample 수가 max_evaluations 를 넘으면 BUDGET_EXHAUSTED 다. Cancel callback은 호출하지 않는다. Storage는 모두 분리하고 실패 시 outputs를 보존한다.

• Math Engine ownership: series=borrowed context=borrowed out_times=caller out_values=caller out_result=caller
• Math Engine nullable: series=false context=false out_times=false out_values=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_trajectory_resample_time_f64(
    const math_engine_sample_series_f64_t* series,
    double start_time_seconds,
    double end_time_seconds,
    double interval_seconds,
    const math_engine_context_t* context,
    double* out_times,
    double* out_values,
    size_t output_sample_capacity,
    math_engine_trajectory_result_f64_t* out_result);

Arc-length resampling에 필요한 누적 길이 workspace element 수를 반환한다.

• 매개변수 series (in): 검증할 borrowed series.
• 매개변수 out_workspace_count (out): 성공 시 sample_count + 1 인 double element 수.
• 반환: 성공 또는 series validation/size 상태 code.

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

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

MATH_ENGINE_API math_engine_status_t math_engine_trajectory_arc_workspace_count_f64(
    const math_engine_sample_series_f64_t* series,
    size_t* out_workspace_count);

3-component 위치 series를 명시 endpoint까지 일정 arc length로 resample한다.

• 매개변수 series (in): 정확히 3개 위치 component를 가진 borrowed series; 값 단위는 m다.
• 매개변수 end_time_seconds (in): series 범위 안의 포함할 끝 시간(s).
• 매개변수 spacing_meters (in): 양의 regular arc 간격(m).
• 매개변수 context (in): length tolerance와 max_evaluations budget.
• 매개변수 workspace (in,out): 누적 길이를 담는 caller scratch double array.
• 매개변수 workspace_count (in): workspace의 double element 수.
• 매개변수 out_times (out): resampled 시간(s) buffer.
• 매개변수 out_positions (out): resampled 위치(m) buffer.
• 매개변수 output_sample_capacity (in): 두 output의 sample capacity.
• 매개변수 out_result (out): written/required count, cut 위치와 total arc length(m).
• 반환: 성공 또는 validation, workspace/buffer/budget, range/overflow 상태 code.

Zero-length 경로는 시작과 필요 시 endpoint만 생성한다. Endpoint는 한 번만 포함한다. Input, workspace, outputs와 context는 상호 non-overlap이어야 한다. 실패 시 결과 outputs는 보존하지만 scratch workspace 내용은 미지정이다. Cancel callback은 호출하지 않는다.

• Math Engine ownership: series=borrowed context=borrowed workspace=caller out_times=caller out_positions=caller out_result=caller
• Math Engine nullable: series=false context=false workspace=false out_times=false out_positions=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_trajectory_resample_arc_f64(
    const math_engine_sample_series_f64_t* series,
    double end_time_seconds,
    double spacing_meters,
    const math_engine_context_t* context,
    double* workspace,
    size_t workspace_count,
    double* out_times,
    math_engine_vec3_f64_t* out_positions,
    size_t output_sample_capacity,
    math_engine_trajectory_result_f64_t* out_result);

일정 중력에서 고정 속력으로 displacement에 도달하는 launch velocity를 푼다.

• 매개변수 displacement_m (in): 발사점에서 목표까지의 변위(m).
• 매개변수 launch_speed_mps (in): 양의 발사 속력(m/s).
• 매개변수 gravity_mps2 (in): 일정 중력 가속도 vector(m/s^2).
• 매개변수 context (in): FINANCE_FIXED가 아닌 검증된 tolerance context.
• 매개변수 out_solution (out): 초기화된 caller-owned solution.
• 반환: 유효 계산이면 OK; validation, unsupported, overflow 상태 code.

Analytic quadratic을 풀며 비행 시간 오름차순으로 최대 두 해를 기록한다. 해가 없어도 OK 와 NO_SOLUTION flag를 반환한다. Tolerance 이내 zero displacement는 시간·속도 0인 한 해다. Input/output은 겹치면 안 되고 실패 시 output을 보존한다.

• Math Engine ownership: displacement_m=borrowed gravity_mps2=borrowed context=borrowed out_solution=caller
• Math Engine nullable: displacement_m=false gravity_mps2=false context=false out_solution=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_projectile_ballistic_launch_f64(
    const math_engine_vec3_f64_t* displacement_m,
    double launch_speed_mps,
    const math_engine_vec3_f64_t* gravity_mps2,
    const math_engine_context_t* context,
    math_engine_projectile_solution_f64_t* out_solution);

등속 목표를 고정 projectile 속력으로 맞히는 가장 이른 analytic 해를 구한다.

• 매개변수 relative_position_m (in): 발사점 기준 현재 목표 위치(m).
• 매개변수 target_velocity_mps (in): 일정 목표 속도(m/s).
• 매개변수 projectile_speed_mps (in): 양의 projectile 속력(m/s).
• 매개변수 maximum_time_seconds (in): 0 이상인 허용 비행 시간 상한(s).
• 매개변수 context (in): FINANCE_FIXED가 아닌 검증된 tolerance context.
• 매개변수 out_solution (out): 초기화된 caller-owned solution.
• 반환: 유효 계산이면 OK; validation, unsupported, overflow 상태 code.

Tolerance보다 큰 양의 quadratic root 중 가장 이른 것을 선택한다. 해가 없으면 OK 와 NO_SOLUTION 이며, 이미 목표 위치에 있으면 0초 한 해다. Storage는 겹치면 안 되고 실패 시 output을 보존한다.

• Math Engine ownership: relative_position_m=borrowed target_velocity_mps=borrowed context=borrowed out_solution=caller
• Math Engine nullable: relative_position_m=false target_velocity_mps=false context=false out_solution=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_projectile_intercept_f64(
    const math_engine_vec3_f64_t* relative_position_m,
    const math_engine_vec3_f64_t* target_velocity_mps,
    double projectile_speed_mps,
    double maximum_time_seconds,
    const math_engine_context_t* context,
    math_engine_projectile_solution_f64_t* out_solution);

등가속 목표의 가장 이른 intercept를 bounded bracket/bisection으로 근사한다.

• 매개변수 relative_position_m (in): 발사점 기준 목표 위치(m).
• 매개변수 target_velocity_mps (in): 초기 목표 속도(m/s).
• 매개변수 target_acceleration_mps2 (in): 일정 목표 가속도(m/s^2).
• 매개변수 projectile_speed_mps (in): 양의 projectile 속력(m/s).
• 매개변수 maximum_time_seconds (in): 양의 탐색 시간 상한(s).
• 매개변수 context (in): tolerance, mode, iteration/evaluation budget와 cancel callback.
• 매개변수 out_solution (out): 초기화된 caller-owned approximate solution.
• 반환: OK 또는 validation, CANCELLED, BUDGET_EXHAUSTED, NOT_CONVERGED, overflow 상태 code.

GAME_FAST는 64, 다른 지원 mode는 256개 고정 segment로 deterministic scan한 뒤 context budget 안에서 bisection한다. 해가 없으면 OK 와 NO_SOLUTION 이다. Callback은 호출 thread에서 동기 호출하고 보관하지 않으며, cancel/budget을 포함한 실패 시 output을 보존한다. 모든 input/output은 분리해야 한다.

• Math Engine ownership: relative_position_m=borrowed target_velocity_mps=borrowed target_acceleration_mps2=borrowed context=borrowed out_solution=caller
• Math Engine nullable: relative_position_m=false target_velocity_mps=false target_acceleration_mps2=false context=false out_solution=false
• Math Engine thread_safety: conditional

MATH_ENGINE_API math_engine_status_t math_engine_projectile_intercept_accelerated_f64(
    const math_engine_vec3_f64_t* relative_position_m,
    const math_engine_vec3_f64_t* target_velocity_mps,
    const math_engine_vec3_f64_t* target_acceleration_mps2,
    double projectile_speed_mps,
    double maximum_time_seconds,
    const math_engine_context_t* context,
    math_engine_projectile_solution_f64_t* out_solution);

Relative state에서 bounded proportional-navigation 가속도를 계산한다.

• 매개변수 relative_position_m (in): pursuer 기준 target 위치(m).
• 매개변수 relative_velocity_mps (in): target-minus-pursuer 상대 속도(m/s).
• 매개변수 navigation_gain (in): 0 이상인 무차원 navigation 상수.
• 매개변수 maximum_acceleration_mps2 (in): 0 이상인 command magnitude 상한(m/s^2).
• 매개변수 context (in): FINANCE_FIXED가 아닌 검증된 tolerance context.
• 매개변수 out_result (out): command, line-of-sight rate(rad/s), closing speed(m/s) 결과.
• 반환: 성공 또는 validation, DEGENERATE, overflow 상태 code.

Range가 absolute tolerance 이하이면 방향이 정의되지 않아 DEGENERATE 다. 계산한 command를 magnitude 상한으로 clamp한다. Storage는 겹치면 안 되고 실패 시 output을 보존하며 callback/cancellation은 사용하지 않는다.

• Math Engine ownership: relative_position_m=borrowed relative_velocity_mps=borrowed context=borrowed out_result=caller
• Math Engine nullable: relative_position_m=false relative_velocity_mps=false context=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_guidance_proportional_navigation_f64(
    const math_engine_vec3_f64_t* relative_position_m,
    const math_engine_vec3_f64_t* relative_velocity_mps,
    double navigation_gain,
    double maximum_acceleration_mps2,
    const math_engine_context_t* context,
    math_engine_guidance_result_f64_t* out_result);

한 propulsion interval의 thrust, impulse, fuel과 ideal delta-v를 예측한다.

• 매개변수 throttle (in): 0..1 범위의 throttle fraction.
• 매개변수 maximum_thrust_newtons (in): 0 이상인 최대 추력(N).
• 매개변수 specific_impulse_seconds (in): 양의 specific impulse(s).
• 매개변수 fuel_kg (in): 현재 0 이상 fuel mass(kg).
• 매개변수 dry_mass_kg (in): 양의 dry mass(kg).
• 매개변수 delta_seconds (in): 0 이상인 step 시간(s).
• 매개변수 context (in): FINANCE_FIXED가 아닌 검증된 context.
• 매개변수 out_result (out): 실제 thrust/impulse/fuel, Tsiolkovsky delta-v와 잔여 runtime.
• 반환: 성공 또는 validation, unsupported, overflow 상태 code.

표준 중력 9.80665 m/s^2=를 사용한다. 요청 연료가 부족하면 가용 연료까지만 사용하고 =FUEL_LIMITED 를 기록한다. Context callback/tolerance는 계산에 사용하지 않는다. context 와 output은 겹치면 안 되며 실패 시 output을 보존한다.

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

MATH_ENGINE_API math_engine_status_t math_engine_propulsion_step_f64(
    double throttle,
    double maximum_thrust_newtons,
    double specific_impulse_seconds,
    double fuel_kg,
    double dry_mass_kg,
    double delta_seconds,
    const math_engine_context_t* context,
    math_engine_propulsion_result_f64_t* out_result);