Math Engine Reference: Root Solver

문서 탐색

개요

실수 polynomial root를 계산하는 Math Engine C API를 선언한다.

명시적 tolerance context를 사용해 1–3차 다항식과 bracketed scalar 함수의 실수 root, normalized residual과 error evidence를 반환한다. 다항식 차수는 선행 계수가 정확히 0일 때만 낮춘다.

실행 원본: include/math_engine/math_engine_root_solver.h
분류: 일반 수학·수치 알고리즘

공개 API

Header 사용 시작

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

#include <math_engine/math_engine_root_solver.h>

Type과 callback

`math_engine_quadratic_result_f64_t`

최대 두 실수 root와 각 normalized residual을 보관하는 caller-owned POD다.

typedef struct math_engine_quadratic_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_quadratic_result_f64_t)=로 설정하는 legacy result byte 크기다. */
    uint32_t root_count; /**< 오름차순 =roots=와 =residuals=에서 유효한 leading 원소 수다. 0..2 범위다. */
    double roots[2]; /**< 서로 다른 real root를 오름차순으로 담는다. Leading =root_count=개만 유효하다. */
    double residuals[2]; /**< 대응 root에서 polynomial을 평가한 normalized residual이다. */
} math_engine_quadratic_result_f64_t;

math_engine_quadratic_result_f64_t.struct_size
Caller가 sizeof(math_engine_quadratic_result_f64_t) 로 설정하는 legacy result byte 크기다.
```
uint32_t struct_size;
```
math_engine_quadratic_result_f64_t.root_count
오름차순 roots 와 residuals 에서 유효한 leading 원소 수다. 0..2 범위다.
```
uint32_t root_count;
```
math_engine_quadratic_result_f64_t.roots
서로 다른 real root를 오름차순으로 담는다. Leading root_count 개만 유효하다.
```
double roots[2];
```
math_engine_quadratic_result_f64_t.residuals
대응 root에서 polynomial을 평가한 normalized residual이다.
```
double residuals[2];
```

`math_engine_scalar_function_f64_fn`

Bracket solver가 scalar 함수값 또는 derivative를 계산할 때 쓰는 callback이다.

매개변수 x: options의 bracket과 같은 독립변수 단위인 finite 평가점이다.
매개변수 user_data: caller가 solve 호출 동안 유효하게 유지하는 opaque pointer다.
매개변수 out_value: 성공 시 함수값 또는 derivative를 기록할 caller-provided storage다.
반환: 성공 시 MATH_ENGINE_STATUS_OK, 평가 실패 시 정의된 음수 상태 code다.

호출 thread에서 동기적으로 실행되고 저장되지 않는다. Pointer를 보관하거나 C++ exception을 ABI 밖으로 전달하면 안 되며 성공 시 finite 값을 기록해야 한다. Derivative callback이면 결과 단위는 function-value/x 다.

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

typedef math_engine_status_t (*math_engine_scalar_function_f64_fn)(
    double x, void* user_data, double* out_value);

`math_engine_root_method_t`

Deterministic bracket-preserving scalar root algorithms.

typedef enum math_engine_root_method {
    MATH_ENGINE_ROOT_METHOD_INVALID = 0, /**< 초기화되지 않았거나 지원하지 않는 root-method sentinel이다. */
    MATH_ENGINE_ROOT_METHOD_BISECTION = 1, /**< 매 iteration bracket 중점을 평가하는 linear-convergence 보존 method다. */
    MATH_ENGINE_ROOT_METHOD_BRENT_DEKKER = 2, /**< Bisection, secant와 inverse quadratic interpolation을 결합한 bracketed method다. */
    MATH_ENGINE_ROOT_METHOD_SAFEGUARDED_NEWTON = 3 /**< Derivative Newton candidate를 bracket 안에서만 허용하고 실패 시 bisection하는 method다. */
} math_engine_root_method_t;

math_engine_root_method_t.MATH_ENGINE_ROOT_METHOD_INVALID
초기화되지 않았거나 지원하지 않는 root-method sentinel이다.
```
MATH_ENGINE_ROOT_METHOD_INVALID = 0,
```
math_engine_root_method_t.MATH_ENGINE_ROOT_METHOD_BISECTION
매 iteration bracket 중점을 평가하는 linear-convergence 보존 method다.
```
MATH_ENGINE_ROOT_METHOD_BISECTION = 1,
```
math_engine_root_method_t.MATH_ENGINE_ROOT_METHOD_BRENT_DEKKER
Bisection, secant와 inverse quadratic interpolation을 결합한 bracketed method다.
```
MATH_ENGINE_ROOT_METHOD_BRENT_DEKKER = 2,
```
math_engine_root_method_t.MATH_ENGINE_ROOT_METHOD_SAFEGUARDED_NEWTON
Derivative Newton candidate를 bracket 안에서만 허용하고 실패 시 bisection하는 method다.
```
MATH_ENGINE_ROOT_METHOD_SAFEGUARDED_NEWTON = 3,
```

`math_engine_polynomial_result_f64_t`

1–3차 실수 polynomial 결과다. Root는 오름차순이며 normalized residual은 dimensionless, absolute_error_bounds 는 root 단위, condition estimate는 local sensitivity 진단값이다.

typedef struct math_engine_polynomial_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_polynomial_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_POLYNOMIAL_RESULT_F64_VERSION_1=인 result ABI version이다. */
    uint32_t declared_degree; /**< Caller가 coefficient count로 선언한 polynomial degree 1..3이다. */
    uint32_t effective_degree; /**< 정확히 0인 leading coefficient를 제거한 실제 degree다. */
    uint32_t root_count; /**< 오름차순 root/multiplicity/evidence 배열에서 유효한 leading 원소 수다. */
    uint32_t flags; /**< =MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_*= primary/quality bit의 조합이다. */
    double coefficient_scale; /**< Residual normalization에 사용한 coefficient 절댓값의 finite positive scale이다. */
    double roots[MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS]; /**< 서로 다른 finite real root를 오름차순으로 담는다. */
    uint32_t multiplicities[MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS]; /**< 각 유효 root의 1 이상 algebraic multiplicity 또는 best certified multiplicity다. */
    uint32_t reserved32; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    double normalized_residuals[MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS]; /**< Coefficient 공통 배율에 불변인 각 root의 nonnegative residual이다. */
    double absolute_error_bounds[MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS]; /**< 각 root 독립변수 단위의 보수적 absolute error bound다. */
    double condition_estimates[MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS]; /**< 각 root의 coefficient perturbation local sensitivity estimate다. */
    uint64_t result_fingerprint; /**< Coefficients, context와 canonical sorted root evidence를 결합한 fingerprint다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_polynomial_result_f64_t;

math_engine_polynomial_result_f64_t.struct_size
Caller가 sizeof(math_engine_polynomial_result_f64_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_polynomial_result_f64_t.struct_version
MATH_ENGINE_POLYNOMIAL_RESULT_F64_VERSION_1 인 result ABI version이다.
```
uint32_t struct_version;
```
math_engine_polynomial_result_f64_t.declared_degree
Caller가 coefficient count로 선언한 polynomial degree 1..3이다.
```
uint32_t declared_degree;
```
math_engine_polynomial_result_f64_t.effective_degree
정확히 0인 leading coefficient를 제거한 실제 degree다.
```
uint32_t effective_degree;
```
math_engine_polynomial_result_f64_t.root_count
오름차순 root/multiplicity/evidence 배열에서 유효한 leading 원소 수다.
```
uint32_t root_count;
```
math_engine_polynomial_result_f64_t.flags
MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_* primary/quality bit의 조합이다.
```
uint32_t flags;
```
math_engine_polynomial_result_f64_t.coefficient_scale
Residual normalization에 사용한 coefficient 절댓값의 finite positive scale이다.
```
double coefficient_scale;
```
math_engine_polynomial_result_f64_t.roots
서로 다른 finite real root를 오름차순으로 담는다.
```
double roots[MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS];
```
math_engine_polynomial_result_f64_t.multiplicities
각 유효 root의 1 이상 algebraic multiplicity 또는 best certified multiplicity다.
```
uint32_t multiplicities[MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS];
```
math_engine_polynomial_result_f64_t.reserved32
향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다.
```
uint32_t reserved32;
```
math_engine_polynomial_result_f64_t.normalized_residuals
Coefficient 공통 배율에 불변인 각 root의 nonnegative residual이다.
```
double normalized_residuals[MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS];
```
math_engine_polynomial_result_f64_t.absolute_error_bounds
각 root 독립변수 단위의 보수적 absolute error bound다.
```
double absolute_error_bounds[MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS];
```
math_engine_polynomial_result_f64_t.condition_estimates
각 root의 coefficient perturbation local sensitivity estimate다.
```
double condition_estimates[MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS];
```
math_engine_polynomial_result_f64_t.result_fingerprint
Coefficients, context와 canonical sorted root evidence를 결합한 fingerprint다.
```
uint64_t result_fingerprint;
```
math_engine_polynomial_result_f64_t.reserved
향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다.
```
uint64_t reserved[2];
```

`math_engine_root_options_f64_t`

Bracketed scalar solve의 pointer-free 정책이다. lower < upper 여야 하며 Newton method의 initial_guess 는 bracket 밖이면 구현이 안전한 bracket step으로 대체한다.

typedef struct math_engine_root_options_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_root_options_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_ROOT_OPTIONS_F64_VERSION_1=인 option ABI version이다. */
    uint32_t method; /**< 실행할 =math_engine_root_method_t= 값이다. */
    uint32_t flags; /**< Version 1 root-option flag bitset이다. 정의되지 않은 bit는 0이어야 한다. */
    double lower; /**< 함수값 부호가 반대인 finite closed bracket 하한이다. */
    double upper; /**< =lower=보다 큰 finite closed bracket 상한이다. */
    double initial_guess; /**< Safeguarded Newton의 finite 첫 candidate다. Bracket 밖이면 안전 step으로 대체한다. */
    uint64_t reserved[3]; /**< 향후 ABI 확장용 세 slot이다. Caller는 모두 0으로 설정해야 하며 nonzero option은 INVALID_ARGUMENT로 거부된다. */
} math_engine_root_options_f64_t;

math_engine_root_options_f64_t.struct_size
Caller가 sizeof(math_engine_root_options_f64_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_root_options_f64_t.struct_version
MATH_ENGINE_ROOT_OPTIONS_F64_VERSION_1 인 option ABI version이다.
```
uint32_t struct_version;
```
math_engine_root_options_f64_t.method
실행할 math_engine_root_method_t 값이다.
```
uint32_t method;
```
math_engine_root_options_f64_t.flags
Version 1 root-option flag bitset이다. 정의되지 않은 bit는 0이어야 한다.
```
uint32_t flags;
```
math_engine_root_options_f64_t.lower
함수값 부호가 반대인 finite closed bracket 하한이다.
```
double lower;
```
math_engine_root_options_f64_t.upper
lower 보다 큰 finite closed bracket 상한이다.
```
double upper;
```
math_engine_root_options_f64_t.initial_guess
Safeguarded Newton의 finite 첫 candidate다. Bracket 밖이면 안전 step으로 대체한다.
```
double initial_guess;
```
math_engine_root_options_f64_t.reserved
향후 ABI 확장용 세 slot이다. Caller는 모두 0으로 설정해야 하며 nonzero option은 INVALID_ARGUMENT로 거부된다.
```
uint64_t reserved[3];
```

`math_engine_root_result_f64_t`

Root, residual, final bracket, error bounds and execution trace committed together.

typedef struct math_engine_root_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_root_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_ROOT_RESULT_F64_VERSION_1=인 result ABI version이다. */
    uint32_t method; /**< 실제 실행한 =math_engine_root_method_t= 값이다. */
    uint32_t flags; /**< =MATH_ENGINE_ROOT_RESULT_FLAG_*= convergence/evidence bit의 조합이다. */
    uint32_t reserved32[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
    double root; /**< Final bracket 안에서 선택한 finite root approximation이다. */
    double value; /**< =root=에서 callback이 반환한 finite function value다. */
    double bracket_lower; /**< Root를 포함하는 final closed bracket의 finite 하한이다. */
    double bracket_upper; /**< Root를 포함하는 final closed bracket의 finite 상한이다. */
    double absolute_error; /**< Bracket과 residual에서 얻은 root 단위의 보수적 absolute error bound다. */
    double relative_error; /**< =max(abs(root),1)=로 정규화한 무차원 error bound다. */
    double normalized_residual; /**< Function-value scale로 정규화한 nonnegative residual이다. */
    uint64_t iterations; /**< Bracket-preserving update를 수행한 iteration 수다. */
    uint64_t evaluations; /**< Function callback을 동기 호출한 총횟수다. */
    uint64_t derivative_evaluations; /**< Derivative callback을 동기 호출한 총횟수다. */
    uint64_t result_fingerprint; /**< Options, ordered callback observations와 final evidence의 deterministic fingerprint다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_root_result_f64_t;

math_engine_root_result_f64_t.struct_size
Caller가 sizeof(math_engine_root_result_f64_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_root_result_f64_t.struct_version
MATH_ENGINE_ROOT_RESULT_F64_VERSION_1 인 result ABI version이다.
```
uint32_t struct_version;
```
math_engine_root_result_f64_t.method
실제 실행한 math_engine_root_method_t 값이다.
```
uint32_t method;
```
math_engine_root_result_f64_t.flags
MATH_ENGINE_ROOT_RESULT_FLAG_* convergence/evidence bit의 조합이다.
```
uint32_t flags;
```
math_engine_root_result_f64_t.reserved32
향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다.
```
uint32_t reserved32[2];
```
math_engine_root_result_f64_t.root
Final bracket 안에서 선택한 finite root approximation이다.
```
double root;
```
math_engine_root_result_f64_t.value
root 에서 callback이 반환한 finite function value다.
```
double value;
```
math_engine_root_result_f64_t.bracket_lower
Root를 포함하는 final closed bracket의 finite 하한이다.
```
double bracket_lower;
```
math_engine_root_result_f64_t.bracket_upper
Root를 포함하는 final closed bracket의 finite 상한이다.
```
double bracket_upper;
```
math_engine_root_result_f64_t.absolute_error
Bracket과 residual에서 얻은 root 단위의 보수적 absolute error bound다.
```
double absolute_error;
```
math_engine_root_result_f64_t.relative_error
max(abs(root),1) 로 정규화한 무차원 error bound다.
```
double relative_error;
```
math_engine_root_result_f64_t.normalized_residual
Function-value scale로 정규화한 nonnegative residual이다.
```
double normalized_residual;
```
math_engine_root_result_f64_t.iterations
Bracket-preserving update를 수행한 iteration 수다.
```
uint64_t iterations;
```
math_engine_root_result_f64_t.evaluations
Function callback을 동기 호출한 총횟수다.
```
uint64_t evaluations;
```
math_engine_root_result_f64_t.derivative_evaluations
Derivative callback을 동기 호출한 총횟수다.
```
uint64_t derivative_evaluations;
```
math_engine_root_result_f64_t.result_fingerprint
Options, ordered callback observations와 final evidence의 deterministic fingerprint다.
```
uint64_t result_fingerprint;
```
math_engine_root_result_f64_t.reserved
향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다.
```
uint64_t reserved[2];
```

Macro와 constant

`MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS`

지원하는 cubic polynomial 하나가 가질 수 있는 최대 서로 다른 real root 수다.

#define MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS UINT32_C(3)

`MATH_ENGINE_POLYNOMIAL_RESULT_F64_VERSION_1`

math_engine_polynomial_result_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_POLYNOMIAL_RESULT_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_DEGREE_REDUCED`

하나 이상의 leading coefficient가 정확히 0이라 effective degree가 낮아졌음을 나타낸다.

#define MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_DEGREE_REDUCED UINT32_C(0x00000100)

`MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_MISS`

유효 nonconstant polynomial에 real root가 없음을 나타내는 primary result bit다.

#define MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_MISS UINT32_C(0x00000002)

`MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_REPEATED_ROOT`

적어도 한 real root의 algebraic multiplicity가 2 이상임을 인증했음을 나타낸다.

#define MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_REPEATED_ROOT UINT32_C(0x00000200)

`MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_UNCERTAIN_MULTIPLICITY`

Tolerance 안에서 합친 root의 exact multiplicity를 수치적으로 인증하지 못했음을 나타낸다.

#define MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_UNCERTAIN_MULTIPLICITY UINT32_C(0x00000400)

`MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_VALUE`

Polynomial solve가 하나 이상의 real root를 commit했음을 나타내는 primary result bit다.

#define MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_VALUE UINT32_C(0x00000001)

`MATH_ENGINE_ROOT_OPTIONS_F64_VERSION_1`

math_engine_root_options_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_ROOT_OPTIONS_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_ROOT_RESULT_F64_VERSION_1`

math_engine_root_result_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_ROOT_RESULT_F64_VERSION_1 UINT32_C(1)

`MATH_ENGINE_ROOT_RESULT_FLAG_BRACKET_VALID`

Root result의 final bracket이 finite, ordered이고 root를 포함함을 인증한다.

#define MATH_ENGINE_ROOT_RESULT_FLAG_BRACKET_VALID UINT32_C(0x00000100)

`MATH_ENGINE_ROOT_RESULT_FLAG_DERIVATIVE_USED`

Safeguarded Newton이 적어도 한 accepted derivative step을 사용했음을 나타낸다.

#define MATH_ENGINE_ROOT_RESULT_FLAG_DERIVATIVE_USED UINT32_C(0x00001000)

`MATH_ENGINE_ROOT_RESULT_FLAG_ENDPOINT_ROOT`

입력 bracket endpoint 중 하나가 residual tolerance 안의 root였음을 나타낸다.

#define MATH_ENGINE_ROOT_RESULT_FLAG_ENDPOINT_ROOT UINT32_C(0x00000200)

`MATH_ENGINE_ROOT_RESULT_FLAG_FALLBACK_USED`

Interpolation/Newton candidate를 거부하고 bracket-preserving bisection step으로 대체했음을 나타낸다.

#define MATH_ENGINE_ROOT_RESULT_FLAG_FALLBACK_USED UINT32_C(0x00002000)

`MATH_ENGINE_ROOT_RESULT_FLAG_INTERVAL_CONVERGED`

Final bracket 폭이 absolute/relative x tolerance 이하라 종료했음을 나타낸다.

#define MATH_ENGINE_ROOT_RESULT_FLAG_INTERVAL_CONVERGED UINT32_C(0x00000800)

`MATH_ENGINE_ROOT_RESULT_FLAG_RESIDUAL_CONVERGED`

Normalized residual이 context convergence threshold 이하라 종료했음을 나타낸다.

#define MATH_ENGINE_ROOT_RESULT_FLAG_RESIDUAL_CONVERGED UINT32_C(0x00000400)

Function

`math_engine_solve_polynomial_f64`

선언 차수가 1–3인 real polynomial의 서로 다른 real root를 계산한다.

매개변수 coefficients: 최고차항부터 상수항 순서인 coefficient_count 개 배열이다.
매개변수 coefficient_count: 계수 수이며 2–4다.
매개변수 context: root 병합과 residual 판정 tolerance를 제공하는 borrowed context다.
매개변수 out_result: caller가 size/version을 미리 설정한 output storage다.
반환: 성공 시 MATH_ENGINE_STATUS_OK. 항등식은 MATH_ENGINE_STATUS_DEGENERATE, 그 밖의 invalid size/version, non-finite, overflow에는 해당 음수 상태 code다.

선행 계수가 정확히 0일 때만 effective degree를 낮춘다. 상대적으로 작은 계수만으로 먼 root를 버리지 않는다. Nonzero 상수식과 real root가 없는 식은 성공한 MISS 다. Root는 오름차순이고 context tolerance 안에서 구별되지 않는 root는 합쳐 multiplicity와 uncertainty flag를 기록한다. Normalized residual은 coefficient 공통 scale에 불변이며 error bound/root는 독립변수 단위다.

입력 배열은 output/context와 겹치지 않아야 한다. Heap, callback, cancellation 또는 budget을 사용하지 않으며 같은 input bit pattern과 context에는 deterministic하다. 모든 실패에서 out_result 전체를 보존한다.

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

MATH_ENGINE_API math_engine_status_t math_engine_solve_polynomial_f64(
    const double* coefficients,
    uint32_t coefficient_count,
    const math_engine_context_t* context,
    math_engine_polynomial_result_f64_t* out_result);

`math_engine_solve_linear_f64`

=a*x+b=0=을 common polynomial result로 계산한다.

매개변수 a: x 의 coefficient다.
매개변수 b: 상수 coefficient다.
매개변수 context: root/residual tolerance를 제공하는 borrowed context다.
매개변수 out_result: caller가 size/version을 미리 설정한 output storage다.
반환: math_engine_solve_polynomial_f64 과 같은 성공·오류 상태 code다.

a==0,b!=0=은 성공한 MISS, 둘 다 0이면 DEGENERATE다. Root와 error bound 단위는 =x 단위다. 실패 시 output을 보존하고 같은 input에는 deterministic하다.

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_solve_linear_f64(
    double a,
    double b,
    const math_engine_context_t* context,
    math_engine_polynomial_result_f64_t* out_result);

`math_engine_solve_cubic_f64`

=a*x^3+b*x^2+c*x+d=0=의 서로 다른 real root를 계산한다.

매개변수 a: 3차 coefficient다.
매개변수 b: 2차 coefficient다.
매개변수 c: 1차 coefficient다.
매개변수 d: 상수 coefficient다.
매개변수 context: root 병합과 residual tolerance를 제공하는 borrowed context다.
매개변수 out_result: caller가 size/version을 미리 설정한 output storage다.
반환: math_engine_solve_polynomial_f64 과 같은 성공·오류 상태 code다.

=a==0=이면 정확히 lower-degree 문제로 분류한다. Root는 오름차순이고 반복 root의 multiplicity를 기록한다. 실패 시 output을 보존하며 같은 input에는 deterministic하다.

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_solve_cubic_f64(
    double a,
    double b,
    double c,
    double d,
    const math_engine_context_t* context,
    math_engine_polynomial_result_f64_t* out_result);

`math_engine_solve_root_f64`

부호가 다른 bracket에서 선택한 deterministic method로 scalar root를 계산한다.

매개변수 function: 함수값을 반환하는 동기 borrowed callback이다.
매개변수 derivative: safeguarded Newton에서만 필요한 borrowed derivative callback이며 다른 method에서는 NULL일 수 있고 무시된다.
매개변수 user_data: 두 callback에 그대로 전달하는 borrowed pointer며 NULL일 수 있다.
매개변수 options: method, bracket와 initial guess를 담은 borrowed options다.
매개변수 context: tolerance, iteration/evaluation budget와 cancellation을 제공한다.
매개변수 out_result: caller가 size/version을 미리 설정한 output storage다.
반환: Residual 증거로 수렴하면 MATH_ENGINE_STATUS_OK. Same-sign/접선 bracket은 DEGENERATE, 좁은 불연속 bracket은 UNCERTAIN 이며 그 밖의 callback, budget, cancel, validation, non-finite와 non-convergence는 해당 음수 상태 code다.

함수값 단위를 Y, 독립변수를 X라 하면 root/bracket/absolute error는 X, value는 Y, normalized residual은 dimensionless다. Endpoint의 정확한 0도 성공한다. Interval 축소만으로 성공하지 않고 absolute+relative*endpoint-value-scale residual 근거를 요구한다. Newton proposal이 bracket을 벗어나거나 derivative가 쓸 수 없으면 bracket-preserving step으로 fallback한다.

Callback과 cancellation은 호출 thread에서 동기적으로 실행되며 저장되지 않는다. 같은 input과 callback 결과에는 평가 순서와 fingerprint가 deterministic하다. out_result 는 options/context/callback state와 겹치지 않아야 하며 모든 실패에서 보존된다.

Math Engine ownership: function=borrowed derivative=borrowed user_data=borrowed
Math Engine ownership: options=borrowed context=borrowed out_result=caller
Math Engine nullable: function=false derivative=true user_data=true options=false
Math Engine nullable: context=false out_result=false
Math Engine thread_safety: conditional

MATH_ENGINE_API math_engine_status_t math_engine_solve_root_f64(
    math_engine_scalar_function_f64_fn function,
    math_engine_scalar_function_f64_fn derivative,
    void* user_data,
    const math_engine_root_options_f64_t* options,
    const math_engine_context_t* context,
    math_engine_root_result_f64_t* out_result);

`math_engine_solve_quadratic_f64`

=a*x^2 + b*x + c = 0=의 서로 다른 실수 root를 오름차순으로 계산한다.

매개변수 a: 이차항 계수.
매개변수 b: 일차항 계수.
매개변수 c: 상수항 계수.
매개변수 context: 검증된 borrowed 계산 context. NULL이면 오류다.
매개변수 out_result: 성공 시 결과를 받는 caller-owned storage. NULL이면 오류다.
반환: 성공 시 MATH_ENGINE_STATUS_OK. 항등식이면 MATH_ENGINE_STATUS_DEGENERATE, 그 밖의 실패는 해당 음수 상태 code다.

실수 root가 없으면 성공하며 root_count 는 0이다. 실패 시 out_result 는 변경하지 않는다. a==0=일 때만 정확히 선형식으로 낮추고, 계수가 non-finite이면 =MATH_ENGINE_STATUS_NON_FINITE 를 반환한다. Root/residual 분류에는 context tolerance를 사용하며 같은 input에는 오름차순 root와 결과가 deterministic하다. Output은 context와 겹치지 않아야 한다.

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_solve_quadratic_f64(
    double a,
    double b,
    double c,
    const math_engine_context_t* context,
    math_engine_quadratic_result_f64_t* out_result);

`math_engine_solve_bracketed_f64`

부호가 다른 두 끝점 사이 root를 deterministic bisection으로 계산한다.

매개변수 function: scalar 값을 계산하는 callback.
매개변수 user_data: callback에 그대로 전달하는 borrowed pointer. NULL일 수 있다.
매개변수 lower: 닫힌 bracket의 작은 끝점.
매개변수 upper: 닫힌 bracket의 큰 끝점.
매개변수 context: tolerance, budget와 cancellation을 제공하는 borrowed context.
매개변수 out_root: 성공 시 root를 받을 caller storage.
매개변수 out_info: 성공 시 반복·평가·오차를 받을 caller storage.
반환: 성공 또는 음수 상태 code. 부호가 같으면 MATH_ENGINE_STATUS_DEGENERATE 다.

Root와 absolute_error 는 bounds와 같은 X 단위이고 callback 값은 caller가 정한 Y 단위다. Callback은 호출 thread에서 동기 실행되고 저장되지 않으며 성공 시 finite 값을 기록해야 한다. Context tolerance로 interval과 normalized residual을 판정하고 iteration/ evaluation budget 및 cancellation을 적용한다. 같은 input/callback에는 evaluation order가 deterministic하다. 두 output은 input/context/callback state 및 서로 겹치지 않아야 하며 모든 실패에서 함께 보존된다.

Math Engine ownership: function=borrowed user_data=borrowed context=borrowed out_root=caller out_info=caller
Math Engine nullable: function=false user_data=true context=false out_root=false out_info=false
Math Engine thread_safety: conditional

MATH_ENGINE_API math_engine_status_t math_engine_solve_bracketed_f64(
    math_engine_scalar_function_f64_fn function,
    void* user_data,
    double lower,
    double upper,
    const math_engine_context_t* context,
    double* out_root,
    math_engine_result_info_t* out_info);

Math Engine Reference: Root Solver

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_quadratic_result_f64_t

math_engine_scalar_function_f64_fn

math_engine_root_method_t

math_engine_polynomial_result_f64_t

math_engine_root_options_f64_t

math_engine_root_result_f64_t

Macro와 constant

MATH_ENGINE_POLYNOMIAL_MAX_REAL_ROOTS

MATH_ENGINE_POLYNOMIAL_RESULT_F64_VERSION_1

MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_DEGREE_REDUCED

MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_MISS

MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_REPEATED_ROOT

MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_UNCERTAIN_MULTIPLICITY

MATH_ENGINE_POLYNOMIAL_RESULT_FLAG_VALUE

MATH_ENGINE_ROOT_OPTIONS_F64_VERSION_1

MATH_ENGINE_ROOT_RESULT_F64_VERSION_1

MATH_ENGINE_ROOT_RESULT_FLAG_BRACKET_VALID

MATH_ENGINE_ROOT_RESULT_FLAG_DERIVATIVE_USED

MATH_ENGINE_ROOT_RESULT_FLAG_ENDPOINT_ROOT

MATH_ENGINE_ROOT_RESULT_FLAG_FALLBACK_USED

MATH_ENGINE_ROOT_RESULT_FLAG_INTERVAL_CONVERGED

MATH_ENGINE_ROOT_RESULT_FLAG_RESIDUAL_CONVERGED