Math Engine Reference: Physics

공개 physics 식 또는 명시적 model의 안정된 식별자다.

typedef enum math_engine_physics_model_id {
    MATH_ENGINE_PHYSICS_MODEL_INVALID = 0, /**< 초기화되지 않았거나 알려지지 않은 model sentinel이다. */
    MATH_ENGINE_PHYSICS_MODEL_UNIFORM_GRAVITY_V1 = 1, /**< 공간·시간에 일정한 acceleration과 mass의 =F=m g= law다. */
    MATH_ENGINE_PHYSICS_MODEL_IDEAL_GAS_DRY_AIR_V1 = 2, /**< 명시 gas constant를 사용하는 dry ideal-gas =rho=p/(R T)= model이다. */
    MATH_ENGINE_PHYSICS_MODEL_SOLID_SPHERE_INERTIA_V1 = 3, /**< 균질 solid sphere 중심 inertia =2/5 m r²= model이다. */
    MATH_ENGINE_PHYSICS_MODEL_SOLID_BOX_INERTIA_V1 = 4, /**< 균질 axis-aligned solid box 중심 principal inertia model이다. */
    MATH_ENGINE_PHYSICS_MODEL_EXPONENTIAL_DAMPING_V1 = 5, /**< Rate와 duration에서 =exp(-rate*time)= decay를 적용하는 model이다. */
    MATH_ENGINE_PHYSICS_MODEL_COULOMB_KINETIC_FRICTION_V1 = 6, /**< Normal force와 kinetic coefficient로 slip 반대 마찰력을 계산하는 law다. */
    MATH_ENGINE_PHYSICS_MODEL_PERIODIC_VECTOR_FIELD_V1 = 7 /**< 명시 amplitude/frequency/phase를 가진 deterministic periodic signal model이다. */
} math_engine_physics_model_id_t;

Model 자체의 성격이다. Product preset과 tuning heuristic은 포함하지 않는다.

typedef enum math_engine_physics_model_class {
    MATH_ENGINE_PHYSICS_MODEL_CLASS_INVALID = 0, /**< 초기화되지 않았거나 알려지지 않은 class sentinel이다. */
    MATH_ENGINE_PHYSICS_MODEL_CLASS_LAW = 1, /**< Kinematic/dynamic state 사이의 명시 물리 법칙이다. */
    MATH_ENGINE_PHYSICS_MODEL_CLASS_CONSTITUTIVE = 2, /**< Material/medium 속성을 근사하는 constitutive relation이다. */
    MATH_ENGINE_PHYSICS_MODEL_CLASS_SIGNAL = 3 /**< 외부 state 없이 시간/위치에서 deterministic vector/scalar signal을 만든다. */
} math_engine_physics_model_class_t;

선택 mode에서 실제 사용한 수치 평가 품질이다.

typedef enum math_engine_physics_quality {
    MATH_ENGINE_PHYSICS_QUALITY_INVALID = 0, /**< Result가 초기화 상태이거나 평가 quality가 없음을 나타낸다. */
    MATH_ENGINE_PHYSICS_QUALITY_EXACT_ANALYTIC = 1, /**< 선택 scalar representation에서 식을 closed-form으로 직접 평가했다. */
    MATH_ENGINE_PHYSICS_QUALITY_FAST_APPROXIMATION = 2, /**< GAME_FAST bounded approximation을 사용해 latency를 우선했다. */
    MATH_ENGINE_PHYSICS_QUALITY_REFINED_BINARY = 3 /**< Binary64/refinement로 residual과 error evidence를 강화했다. */
} math_engine_physics_quality_t;

Model별 mode capability와 FULL 승격 경계를 기술한다.

typedef struct math_engine_physics_model_info {
    uint32_t struct_size; /**< Producer가 =sizeof(math_engine_physics_model_info_t)=로 기록하는 byte 크기다. */
    uint32_t struct_version; /**< Producer가 =MATH_ENGINE_PHYSICS_MODEL_INFO_VERSION_1=로 기록하는 descriptor ABI version이다. */
    int32_t model_id; /**< 설명하는 =math_engine_physics_model_id_t= 값이다. */
    uint32_t model_version; /**< 해당 식/상수/parameterization의 append-only semantic version이다. */
    int32_t model_class; /**< Model 성격을 나타내는 =math_engine_physics_model_class_t= 값이다. */
    int32_t game_quality; /**< GAME_FAST mode가 사용하는 =math_engine_physics_quality_t= 값이다. */
    int32_t pc_quality; /**< PC_PRECISION mode가 사용하는 =math_engine_physics_quality_t= 값이다. */
    int32_t unlimited_quality; /**< FULL mode가 이 model 자체에서 제공하는 =math_engine_physics_quality_t= 값이다. */
    uint64_t supported_mode_bits; /**< Model을 실행할 수 있는 =MATH_ENGINE_MODE_MASK_*= bit의 합집합이다. */
    uint32_t unlimited_requires_higher_fidelity_model; /**< FULL에서 model-form 정확도를 높이려면 별도 model이 필요할 경우 1이다. */
    uint32_t reserved[3]; /**< 향후 ABI 확장용 세 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_physics_model_info_t;

Physics 식의 caller-owned 공통 결과다. 함수별로 scalar/secondary/vector의 의미는 해당 함수 문서가 고정한다. residual과 error_bound는 model-form 오차가 아니라 반환값을 같은 식에 대입한 수치 residual과 그 계산 bound다.

typedef struct math_engine_physics_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_physics_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_PHYSICS_RESULT_F64_VERSION_1=인 result ABI version이다. */
    uint32_t flags; /**< =MATH_ENGINE_RESULT_FLAG_*= primary/quality bit의 조합이다. */
    int32_t model_id; /**< 결과를 만든 =math_engine_physics_model_id_t= 값이다. */
    uint32_t model_version; /**< 평가에 사용한 model semantic version이다. */
    int32_t quality; /**< 실제 수치 평가의 =math_engine_physics_quality_t= 값이다. */
    uint32_t reserved0; /**< 향후 ABI 확장용이다. Caller는 호출 전에 0으로 설정해야 하고 producer도 0을 기록한다. */
    double scalar_value; /**< 함수별 문서가 정한 첫 scalar 결과와 SI 단위다. */
    double secondary_value; /**< 함수별 문서가 정한 둘째 scalar/diagnostic 결과와 SI 단위다. 미사용이면 0이다. */
    math_engine_vec3_f64_t vector_value; /**< 함수별 문서가 정한 world/model-frame vector 결과와 SI 단위다. */
    double residual; /**< 반환 값을 defining equation에 대입한 signed 또는 absolute 수치 residual이다. */
    double error_bound; /**< 반환 result 값 단위의 보수적 numerical evaluation error bound다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Caller는 호출 전에 모두 0으로 설정해야 하고 producer도 0을 기록한다. */
} math_engine_physics_result_f64_t;

math_engine_physics_model_info_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_PHYSICS_MODEL_INFO_VERSION_1 1u

math_engine_physics_result_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_PHYSICS_RESULT_F64_VERSION_1 1u

Physics 공통 결과를 ABI version 1의 빈 값으로 초기화한다.

• 매개변수 out_result: 초기화할 caller-owned result storage.
• 반환: 유효한 storage면 OK, null이면 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_physics_result_f64_init(
    math_engine_physics_result_f64_t* out_result);

Model ID의 version, class와 mode별 평가 quality를 조회한다.

• 매개변수 model_id: 조회할 안정된 physics model ID.
• 매개변수 out_info: 성공 시 producer가 size/version을 포함해 전체 기록하는 model descriptor output.
• 반환: 알려진 model과 non-null output이면 OK, 아니면 해당 음수 상태 code이며 실패하면 out_info 를 보존한다.
• Math Engine ownership: out_info=caller
• Math Engine nullable: out_info=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_physics_model_info_get(
    math_engine_physics_model_id_t model_id,
    math_engine_physics_model_info_t* out_info);

명시적 uniform gravity acceleration에서 질량에 작용하는 힘을 계산한다.

• 매개변수 gravity_mps2: 중력 가속도(m/s^2). 방향과 크기를 caller가 정한다.
• 매개변수 mass_kg: 0 이상의 질량(kg). 0이면 zero force다.
• 매개변수 context: 실행 mode를 제공한다. Finance fixed는 지원하지 않는다.
• 매개변수 out_result: vector_value=force(N), scalar_value=mass(kg).
• 반환: finite 입력과 지원 mode면 OK, 음수 질량·non-finite·잘못된 pointer는 해당 음수 상태 code이며 실패하면 out_result 를 보존한다.
• Math Engine ownership: gravity_mps2=borrowed context=borrowed out_result=caller
• Math Engine nullable: gravity_mps2=false context=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_uniform_gravity_force_f64(
    const math_engine_vec3_f64_t* gravity_mps2,
    double mass_kg,
    const math_engine_context_t* context,
    math_engine_physics_result_f64_t* out_result);

dry ideal-gas 식 rho=p/(R*T)로 density를 계산한다.

• 매개변수 pressure_pa: 양의 absolute pressure(Pa).
• 매개변수 temperature_k: 양의 absolute temperature(K).
• 매개변수 specific_gas_constant_j_kg_k: 양의 명시적 gas constant(J/(kg*K)).
• 매개변수 context: 실행 mode와 수치 평가 quality를 선택하는 borrowed context.
• 매개변수 out_result: scalar_value=density(kg/m^3), residual=rho*R*T-p(Pa).
• 반환: 양의 finite thermodynamic 입력과 지원 mode면 OK, 아니면 해당 음수 상태 code이며 실패하면 out_result 를 보존한다.

이 함수는 humidity나 실제 atmosphere profile을 숨기지 않는다. FULL에서도 model-form 정확도를 높이려면 별도 higher-fidelity model이 필요하다.

• 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_ideal_gas_density_f64(
    double pressure_pa,
    double temperature_k,
    double specific_gas_constant_j_kg_k,
    const math_engine_context_t* context,
    math_engine_physics_result_f64_t* out_result);

균질 solid sphere의 중심 관성 대각 I=2/5*m*r^2를 계산한다.

• 매개변수 mass_kg: 0 이상의 finite 질량(kg).
• 매개변수 radius_m: 0 이상의 finite sphere radius(m).
• 매개변수 context: 실행 mode와 수치 평가 quality를 선택하는 borrowed context.
• 매개변수 out_result: vector_value=(Ixx,Iyy,Izz)(kg*m^2).
• 반환: 유효한 입력과 지원 mode면 OK, 음수·non-finite·overflow는 해당 음수 상태 code이며 실패하면 out_result 를 보존한다.
• 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_solid_sphere_inertia_f64(
    double mass_kg,
    double radius_m,
    const math_engine_context_t* context,
    math_engine_physics_result_f64_t* out_result);

축 정렬 균질 solid box의 중심 관성 대각을 계산한다.

• 매개변수 mass_kg: 0 이상의 finite 질량(kg).
• 매개변수 dimensions_m: 전체 폭 (x,y,z)(m). 각 성분은 양수다.
• 매개변수 context: 실행 mode와 수치 평가 quality를 선택하는 borrowed context.
• 매개변수 out_result: vector_value=(Ixx,Iyy,Izz)(kg*m^2).
• 반환: 유효한 입력과 지원 mode면 OK, 음수·non-finite·overflow는 해당 음수 상태 code이며 실패하면 out_result 를 보존한다.
• Math Engine ownership: dimensions_m=borrowed context=borrowed out_result=caller
• Math Engine nullable: dimensions_m=false context=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_solid_box_inertia_f64(
    double mass_kg,
    const math_engine_vec3_f64_t* dimensions_m,
    const math_engine_context_t* context,
    math_engine_physics_result_f64_t* out_result);

v_next=v*exp(-rate*dt)의 exponential linear damping을 계산한다.

• 매개변수 velocity_mps: damping 전 borrowed 선형 속도(m/s).
• 매개변수 mass_kg: dissipated energy 계산에 사용하는 0 이상의 질량(kg).
• 매개변수 damping_rate_per_sec: 0 이상의 decay rate(1/s). 무차원 friction이 아니다.
• 매개변수 delta_seconds: 0 이상의 명시적 step(s).
• 매개변수 context: 실행 mode와 exponential 평가 quality를 선택하는 borrowed context.
• 매개변수 out_result: vector_value=next velocity(m/s), scalar_value=dissipated energy(J),

secondary_value=velocity retention factor.

• 반환: finite 비음수 parameter와 지원 mode면 OK, 아니면 해당 음수 상태 code이며 실패하면 out_result 를 보존한다.
• Math Engine ownership: velocity_mps=borrowed context=borrowed out_result=caller
• Math Engine nullable: velocity_mps=false context=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_exponential_damping_step_f64(
    const math_engine_vec3_f64_t* velocity_mps,
    double mass_kg,
    double damping_rate_per_sec,
    double delta_seconds,
    const math_engine_context_t* context,
    math_engine_physics_result_f64_t* out_result);

운동 방향 반대의 Coulomb kinetic friction F=-mu*N*v/|v|를 계산한다.

• 매개변수 tangential_velocity_mps: 접촉면의 접선 상대 속도(m/s).
• 매개변수 normal_force_newtons: 0 이상의 normal force 크기(N).
• 매개변수 kinetic_friction_coefficient: 0 이상의 무차원 mu_k.
• 매개변수 context: 정지 속도 tolerance와 실행 mode를 제공하는 borrowed context.
• 매개변수 out_result: vector_value=friction force(N), scalar_value=force magnitude(N).
• 반환: 유효한 입력과 지원 mode면 OK, 아니면 해당 음수 상태 code이며 정지 tolerance 안에서는 zero force를 반환한다. 실패하면 output을 보존한다.
• Math Engine ownership: tangential_velocity_mps=borrowed context=borrowed out_result=caller
• Math Engine nullable: tangential_velocity_mps=false context=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_coulomb_friction_force_f64(
    const math_engine_vec3_f64_t* tangential_velocity_mps,
    double normal_force_newtons,
    double kinetic_friction_coefficient,
    const math_engine_context_t* context,
    math_engine_physics_result_f64_t* out_result);

base+amplitude*sin(2*pi*frequency*time+phase)를 explicit time에 평가한다.

• 매개변수 base: 신호의 borrowed offset vector.
• 매개변수 amplitude: 각 성분의 borrowed signed amplitude vector.
• 매개변수 frequency_hz: 0 이상의 frequency(Hz).
• 매개변수 phase_radians: 초기 phase(rad).
• 매개변수 sample_time_seconds: caller가 소유하는 sample time(s); 내부 elapsed state가 없다.
• 매개변수 context: mode와 phase reduction quality를 선택하는 borrowed context.
• 매개변수 out_result: vector_value=sample, scalar_value=reduced phase(rad),

secondary_value=sin(reduced phase).

• 반환: finite 입력과 지원 mode면 OK, 아니면 해당 음수 상태 code이며 실패하면 out_result 를 보존한다. 같은 입력과 mode는 같은 결과를 낸다.
• Math Engine ownership: base=borrowed amplitude=borrowed context=borrowed out_result=caller
• Math Engine nullable: base=false amplitude=false context=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_periodic_vector_sample_f64(
    const math_engine_vec3_f64_t* base,
    const math_engine_vec3_f64_t* amplitude,
    double frequency_hz,
    double phase_radians,
    double sample_time_seconds,
    const math_engine_context_t* context,
    math_engine_physics_result_f64_t* out_result);

일정한 가속도에서 position과 velocity를 해석적으로 전진한다.

• 매개변수 position_m: 초기 위치(m).
• 매개변수 velocity_mps: 초기 속도(m/s).
• 매개변수 acceleration_mps2: 일정한 가속도(m/s^2).
• 매개변수 delta_seconds: 시간 간격(s). 0 이상이어야 한다.
• 매개변수 out_position_m: 결과 위치를 받을 caller storage.
• 매개변수 out_velocity_mps: 결과 속도를 받을 caller storage.
• 반환: 성공 또는 음수 상태 code. 실패 시 output은 변경하지 않는다.
• Math Engine ownership: position_m=borrowed velocity_mps=borrowed acceleration_mps2=borrowed out_position_m=caller out_velocity_mps=caller
• Math Engine nullable: position_m=false velocity_mps=false acceleration_mps2=false out_position_m=false out_velocity_mps=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_kinematics_step_f64(
    const math_engine_vec3_f64_t* position_m,
    const math_engine_vec3_f64_t* velocity_mps,
    const math_engine_vec3_f64_t* acceleration_mps2,
    double delta_seconds,
    math_engine_vec3_f64_t* out_position_m,
    math_engine_vec3_f64_t* out_velocity_mps);

힘과 질량으로 가속도를 계산한다.

• 매개변수 force_newtons: 입력 힘(N).
• 매개변수 mass_kg: 양의 질량(kg).
• 매개변수 out_acceleration_mps2: 결과를 받을 caller storage.
• 반환: 성공 또는 음수 상태 code. 실패 시 output은 변경하지 않는다.
• Math Engine ownership: force_newtons=borrowed out_acceleration_mps2=caller
• Math Engine nullable: force_newtons=false out_acceleration_mps2=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_acceleration_from_force_f64(
    const math_engine_vec3_f64_t* force_newtons,
    double mass_kg,
    math_engine_vec3_f64_t* out_acceleration_mps2);

선형·이차 항을 결합한 drag 힘을 계산한다.

• 매개변수 relative_velocity_mps: 유체에 대한 물체의 속도(m/s).
• 매개변수 linear_coefficient: 음이 아닌 선형 계수(kg/s).
• 매개변수 quadratic_coefficient: 음이 아닌 이차 계수(kg/m).
• 매개변수 out_force_newtons: 결과 drag 힘(N)을 받을 caller storage.
• 반환: 성공 또는 음수 상태 code. 실패 시 output은 변경하지 않는다.
• Math Engine ownership: relative_velocity_mps=borrowed out_force_newtons=caller
• Math Engine nullable: relative_velocity_mps=false out_force_newtons=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_drag_force_f64(
    const math_engine_vec3_f64_t* relative_velocity_mps,
    double linear_coefficient,
    double quadratic_coefficient,
    math_engine_vec3_f64_t* out_force_newtons);

접촉 normal에 대한 반발과 접선 마찰을 적용한다.

• 매개변수 velocity_mps: 충돌 전 속도(m/s).
• 매개변수 unit_normal: 물체 바깥쪽을 향하는 unit normal.
• 매개변수 restitution: 0 이상 1 이하의 반발 계수.
• 매개변수 tangential_retention: 0 이상 1 이하의 접선 속도 보존율.
• 매개변수 context: tolerance를 제공하는 borrowed context.
• 매개변수 out_velocity_mps: 충돌 후 속도를 받을 caller storage.
• 반환: 성공 또는 음수 상태 code. 분리 중이면 입력 속도를 반환한다.
• Math Engine ownership: velocity_mps=borrowed unit_normal=borrowed context=borrowed out_velocity_mps=caller
• Math Engine nullable: velocity_mps=false unit_normal=false context=false out_velocity_mps=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_bounce_velocity_f64(
    const math_engine_vec3_f64_t* velocity_mps,
    const math_engine_vec3_f64_t* unit_normal,
    double restitution,
    double tangential_retention,
    const math_engine_context_t* context,
    math_engine_vec3_f64_t* out_velocity_mps);

공기 밀도·면적·계수로 drag와 지정 방향 lift의 합력을 계산한다.

• 매개변수 relative_velocity_mps: 공기에 대한 물체의 속도(m/s).
• 매개변수 unit_lift_direction: 속도와 직교하는 unit lift 방향.
• 매개변수 air_density_kg_m3: 음이 아닌 공기 밀도(kg/m^3).
• 매개변수 reference_area_m2: 음이 아닌 기준 면적(m^2).
• 매개변수 drag_coefficient: 음이 아닌 무차원 drag 계수.
• 매개변수 lift_coefficient: 유한한 signed lift 계수.
• 매개변수 context: tolerance를 제공하는 borrowed context.
• 매개변수 out_force_newtons: 결과 공력(N)을 받을 caller storage.
• 반환: 성공 또는 음수 상태 code. 정지 상태에서는 0을 반환한다.
• Math Engine ownership: relative_velocity_mps=borrowed unit_lift_direction=borrowed context=borrowed out_force_newtons=caller
• Math Engine nullable: relative_velocity_mps=false unit_lift_direction=false context=false out_force_newtons=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_aerodynamic_force_f64(
    const math_engine_vec3_f64_t* relative_velocity_mps,
    const math_engine_vec3_f64_t* unit_lift_direction,
    double air_density_kg_m3,
    double reference_area_m2,
    double drag_coefficient,
    double lift_coefficient,
    const math_engine_context_t* context,
    math_engine_vec3_f64_t* out_force_newtons);