Math Engine Reference: Interpolation

단일 query의 값, source 구간과 국소 기울기 변화 오차 추정치를 담는다.

interval_index 는 선택된 왼쪽 source knot이고 parameter 는 해당 구간의 무차원 선형 좌표다. local_spacing 은 source 위치와 같은 단위이며 absolute_error_estimate 는 source 값과 같은 단위다.

typedef struct math_engine_interpolation_result_f64 {
    uint32_t struct_size; /**< Producer가 기록한 이 결과 구조체의 byte 크기다. */
    uint32_t version; /**< =MATH_ENGINE_INTERPOLATION_RESULT_F64_VERSION_1=인 결과 ABI version이다. */
    uint32_t flags; /**< =MATH_ENGINE_INTERPOLATION_FLAG_*= bit의 조합이다. 정의되지 않은 bit는 0이다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    uint64_t interval_index; /**< 선택된 왼쪽 source knot index다. 마지막 endpoint에서는 마지막 유효 구간을 가리킨다. */
    double value; /**< Query 위치에서 piecewise-linear로 보간한 scalar 값이다. */
    double parameter; /**< 선택 구간 왼쪽 0, 오른쪽 1인 무차원 선형 parameter다. */
    double local_spacing; /**< 선택 구간의 오른쪽 위치와 왼쪽 위치 차이다. Source position과 같은 단위다. */
    double absolute_error_estimate; /**< Source 값 단위의 국소 보간 오차 proxy다. unavailable flag이면 0이다. */
    uint64_t reserved_u64; /**< 향후 ABI 확장용 64-bit slot이다. Producer는 0을 기록하고 consumer는 무시한다. */
} math_engine_interpolation_result_f64_t;

단일 query 결과의 knot/endpoint/grid 품질 및 오차 추정 가용성 flag다.

enum {
    MATH_ENGINE_INTERPOLATION_FLAG_KNOT_HIT = 1u << 0, /**< Query가 tolerance 없이 source knot와 정확히 일치했다. */
    MATH_ENGINE_INTERPOLATION_FLAG_ENDPOINT = 1u << 1, /**< Query가 source domain의 첫째 또는 마지막 endpoint다. */
    MATH_ENGINE_INTERPOLATION_FLAG_NONUNIFORM_GRID = 1u << 2, /**< Source knot 간격이 전체 grid에서 균일하지 않다. */
    MATH_ENGINE_INTERPOLATION_FLAG_ERROR_ESTIMATE_UNAVAILABLE = 1u << 3 /**< 인접 기울기가 부족해 국소 오차 추정치를 제공할 수 없다. */
};

math_engine_interpolation_result_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_INTERPOLATION_RESULT_F64_VERSION_1 1u

두 scalar 값 사이를 선형 보간한다.

• 매개변수 start: parameter 0에 대응하는 값.
• 매개변수 end: parameter 1에 대응하는 값.
• 매개변수 parameter: 보간 parameter. [0, 1] 밖의 finite 값은 선형 외삽한다.
• 매개변수 out_value: 성공 시 결과를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code.

입력 또는 계산 결과가 non-finite이면 실패한다. 실패 시 out_value 는 변경하지 않는다.

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

MATH_ENGINE_API math_engine_status_t math_engine_lerp_f64(
    double start,
    double end,
    double parameter,
    double* out_value);

Strictly increasing sample grid에서 scalar query 하나를 선형 보간한다.

• 매개변수 source_positions: source_count 개의 strictly increasing borrowed 위치 배열.
• 매개변수 source_values: 위치마다 대응하는 source_count 개의 borrowed scalar 값 배열.
• 매개변수 source_count: source sample 수. 2 이상이어야 한다.
• 매개변수 query_position: 닫힌 source domain 안의 finite query 위치.
• 매개변수 out_result: 성공 시 값과 선택 구간을 받는 caller-owned storage.
• 반환: 성공하면 OK, null·작은 count·비증가 grid·non-finite 값·domain 밖 query는 해당 음수 상태 code이며 실패하면 out_result 를 보존한다.

결과는 선택한 source 구간과 인접 기울기 변화에서 유도한 국소 오차 proxy를 기록한다. Knot에서는 추정치가 정확히 0이고, sample이 둘뿐이면 값은 유효하지만 ERROR_ESTIMATE_UNAVAILABLE flag가 설정된다. 입력 배열과 output은 겹치면 안 된다.

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

MATH_ENGINE_API math_engine_status_t math_engine_interpolate_linear_f64(
    const double* source_positions,
    const double* source_values,
    size_t source_count,
    double query_position,
    math_engine_interpolation_result_f64_t* out_result);

Strictly increasing source 축에서 piecewise-linear resampling을 수행한다.

• 매개변수 source_positions: source_count 개의 strictly increasing borrowed 위치 배열.
• 매개변수 source_values: sample-major layout의 borrowed 값 배열. 원소 수는 source_count * channel_count 다.
• 매개변수 source_count: source sample 수. 2 이상이어야 한다.
• 매개변수 channel_count: sample마다 연속 배치된 channel 수. 1 이상이어야 한다.
• 매개변수 query_positions: query_count 개의 borrowed query 위치 배열. 순서는 자유롭다.
• 매개변수 query_count: query sample 수. 1 이상이어야 한다.
• 매개변수 out_values: 성공 시 sample-major 결과를 받는 caller-owned 배열. 원소 수는 query_count * channel_count 다.
• 반환: 성공 또는 음수 상태 code.

모든 위치와 값은 finite여야 하며 query는 닫힌 source domain 안에 있어야 한다. 입력 배열과 out_values 는 겹치지 않아야 하며 겹치면 MATH_ENGINE_STATUS_INVALID_ARGUMENT 를 반환한다. 함수는 allocation을 수행하지 않으며 실패 시 out_values 를 변경하지 않는다.

• Math Engine ownership: source_positions=borrowed source_values=borrowed query_positions=borrowed out_values=caller
• Math Engine nullable: source_positions=false source_values=false query_positions=false out_values=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_resample_linear_f64(
    const double* source_positions,
    const double* source_values,
    size_t source_count,
    size_t channel_count,
    const double* query_positions,
    size_t query_count,
    double* out_values);