HAIDOX
HAIDOX Help

Math Engine Reference: Calculator

개요

@file math_engine_calculator.h Python/CLI/GUI가 canonical expression·quantity·CAS를 사용하는 얇은 desktop facade.

공개 API

Header 사용 시작

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

#include <math_engine/math_engine_calculator.h>

Type과 callback

math_engine_calculator_angle_mode_t

삼각함수 입력과 역삼각함수 출력에 적용할 angle 단위다.

typedef enum math_engine_calculator_angle_mode {
    MATH_ENGINE_CALCULATOR_ANGLE_INVALID = 0, /**< 초기화되지 않았거나 지원하지 않는 angle mode sentinel이다. */
    MATH_ENGINE_CALCULATOR_ANGLE_RADIANS = 1, /**< 원형 삼각함수 입력과 역삼각함수 출력을 radian으로 해석한다. */
    MATH_ENGINE_CALCULATOR_ANGLE_DEGREES = 2 /**< 원형 삼각함수 입력과 역삼각함수 출력을 degree로 변환한다. */
} math_engine_calculator_angle_mode_t;
  • math_engine_calculator_angle_mode_t.MATH_ENGINE_CALCULATOR_ANGLE_INVALID

    초기화되지 않았거나 지원하지 않는 angle mode sentinel이다.

    MATH_ENGINE_CALCULATOR_ANGLE_INVALID = 0,
    
  • math_engine_calculator_angle_mode_t.MATH_ENGINE_CALCULATOR_ANGLE_RADIANS

    원형 삼각함수 입력과 역삼각함수 출력을 radian으로 해석한다.

    MATH_ENGINE_CALCULATOR_ANGLE_RADIANS = 1,
    
  • math_engine_calculator_angle_mode_t.MATH_ENGINE_CALCULATOR_ANGLE_DEGREES

    원형 삼각함수 입력과 역삼각함수 출력을 degree로 변환한다.

    MATH_ENGINE_CALCULATOR_ANGLE_DEGREES = 2,
    

math_engine_calculator_variable_t

UTF-8 ASCII identifier와 UTF-8 expression/quantity 값의 fixed-capacity binding이다.

typedef struct math_engine_calculator_variable {
    uint32_t name_size; /**< Trailing NUL을 제외한 =name= UTF-8 byte 수다. 1 이상이고 capacity보다 작아야 한다. */
    uint32_t value_size; /**< Trailing NUL을 제외한 =value= UTF-8 byte 수다. 1 이상이고 capacity보다 작아야 한다. */
    char name[MATH_ENGINE_CALCULATOR_VARIABLE_NAME_CAPACITY]; /**< ASCII identifier와 trailing NUL을 담는 fixed caller-owned 배열이다. */
    char value[MATH_ENGINE_CALCULATOR_VARIABLE_VALUE_CAPACITY]; /**< Expression 또는 quantity UTF-8와 trailing NUL을 담는 fixed caller-owned 배열이다. */
} math_engine_calculator_variable_t;
  • math_engine_calculator_variable_t.name_size

    Trailing NUL을 제외한 name UTF-8 byte 수다. 1 이상이고 capacity보다 작아야 한다.

    uint32_t name_size;
    
  • math_engine_calculator_variable_t.value_size

    Trailing NUL을 제외한 value UTF-8 byte 수다. 1 이상이고 capacity보다 작아야 한다.

    uint32_t value_size;
    
  • math_engine_calculator_variable_t.name

    ASCII identifier와 trailing NUL을 담는 fixed caller-owned 배열이다.

    char name[MATH_ENGINE_CALCULATOR_VARIABLE_NAME_CAPACITY];
    
  • math_engine_calculator_variable_t.value

    Expression 또는 quantity UTF-8와 trailing NUL을 담는 fixed caller-owned 배열이다.

    char value[MATH_ENGINE_CALCULATOR_VARIABLE_VALUE_CAPACITY];
    

math_engine_calculator_request_t

Calculator 호출 전체에 적용하는 immutable request다. variables=NULL 은 variable_count=0=일 때만 허용한다. RNG snapshot flag가 없으면 =seed 에서 새 stream을 만들고, 있으면 rng_state/rng_increment 를 검증해 이어서 사용한다.

typedef struct math_engine_calculator_request {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_calculator_request_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_CALCULATOR_REQUEST_VERSION_1=인 request ABI version이다. */
    uint32_t mode; /**< 계산 backend policy를 선택하는 =math_engine_mode_t= 값이다. */
    uint32_t angle_mode; /**< 원형 삼각함수에 적용하는 =math_engine_calculator_angle_mode_t= 값이다. */
    int32_t fixed_scale; /**< FINANCE_FIXED 또는 fixed numeric output의 inclusive decimal scale이다. */
    uint32_t rounding; /**< Fixed decimal 결과에 적용하는 =math_engine_decimal_rounding_t= 값이다. */
    const math_engine_calculator_variable_t* variables; /**< Caller-owned =variable_count=개 binding 배열을 빌려 읽는다. Count가 0일 때만 NULL 가능하며 보관하지 않는다. */
    uint64_t variable_count; /**< =variables= 배열 원소 수다. 0..=MATH_ENGINE_CALCULATOR_MAX_VARIABLES= 범위다. */
    uint64_t seed; /**< Snapshot flag가 없을 때 새 deterministic RNG stream을 만드는 seed다. */
    uint32_t flags; /**< =MATH_ENGINE_CALCULATOR_REQUEST_FLAG_*= bit의 조합이다. 정의되지 않은 bit는 0이어야 한다. */
    uint32_t reserved32; /**< 향후 ABI 확장용이다. Caller는 0으로 설정해야 하며 nonzero request는 INVALID_ARGUMENT로 거부된다. */
    uint64_t rng_state; /**< Snapshot flag가 있을 때 복원할 PCG state word다. */
    uint64_t rng_increment; /**< Snapshot flag가 있을 때 복원할 odd PCG stream increment다. */
} math_engine_calculator_request_t;
  • math_engine_calculator_request_t.struct_size

    Caller가 sizeof(math_engine_calculator_request_t) 로 설정하는 byte 크기다.

    uint32_t struct_size;
    
  • math_engine_calculator_request_t.struct_version

    MATH_ENGINE_CALCULATOR_REQUEST_VERSION_1 인 request ABI version이다.

    uint32_t struct_version;
    
  • math_engine_calculator_request_t.mode

    계산 backend policy를 선택하는 math_engine_mode_t 값이다.

    uint32_t mode;
    
  • math_engine_calculator_request_t.angle_mode

    원형 삼각함수에 적용하는 math_engine_calculator_angle_mode_t 값이다.

    uint32_t angle_mode;
    
  • math_engine_calculator_request_t.fixed_scale

    FINANCE_FIXED 또는 fixed numeric output의 inclusive decimal scale이다.

    int32_t fixed_scale;
    
  • math_engine_calculator_request_t.rounding

    Fixed decimal 결과에 적용하는 math_engine_decimal_rounding_t 값이다.

    uint32_t rounding;
    
  • math_engine_calculator_request_t.variables

    Caller-owned variable_count 개 binding 배열을 빌려 읽는다. Count가 0일 때만 NULL 가능하며 보관하지 않는다.

    const math_engine_calculator_variable_t* variables;
    
  • math_engine_calculator_request_t.variable_count

    variables 배열 원소 수다. 0..=MATH_ENGINE_CALCULATOR_MAX_VARIABLES= 범위다.

    uint64_t variable_count;
    
  • math_engine_calculator_request_t.seed

    Snapshot flag가 없을 때 새 deterministic RNG stream을 만드는 seed다.

    uint64_t seed;
    
  • math_engine_calculator_request_t.flags

    MATH_ENGINE_CALCULATOR_REQUEST_FLAG_* bit의 조합이다. 정의되지 않은 bit는 0이어야 한다.

    uint32_t flags;
    
  • math_engine_calculator_request_t.reserved32

    향후 ABI 확장용이다. Caller는 0으로 설정해야 하며 nonzero request는 INVALID_ARGUMENT로 거부된다.

    uint32_t reserved32;
    
  • math_engine_calculator_request_t.rng_state

    Snapshot flag가 있을 때 복원할 PCG state word다.

    uint64_t rng_state;
    
  • math_engine_calculator_request_t.rng_increment

    Snapshot flag가 있을 때 복원할 odd PCG stream increment다.

    uint64_t rng_increment;
    

math_engine_calculator_result_t

Locale-independent NUL-terminated UTF-8 text와 deterministic provenance를 담는 output이다. text_size 는 NUL을 제외한 byte 수다. 다음 호출까지 library storage를 참조하지 않는다.

typedef struct math_engine_calculator_result {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_calculator_result_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_CALCULATOR_RESULT_VERSION_1=인 result ABI version이다. */
    int32_t execution_status; /**< Native calculation이 반환한 =math_engine_status_t= 값이다. Facade 호출 status와 함께 해석한다. */
    uint32_t flags; /**< =MATH_ENGINE_CALCULATOR_RESULT_FLAG_*= bit의 조합이다. */
    uint32_t mode; /**< Request에 지정되어 facade가 적용한 =math_engine_mode_t= 값이다. FULL 요청도 FULL로 기록한다. */
    uint32_t numeric_kind; /**< Numeric/quantity text의 =math_engine_quantity_numeric_kind_t= 값이다. Symbolic CAS text처럼 numeric representation이 없으면 INVALID다. */
    uint32_t angle_mode; /**< 원형 삼각함수에 실제 적용된 =math_engine_calculator_angle_mode_t= 값이다. */
    uint32_t text_size; /**< Trailing NUL을 제외한 =text= UTF-8 byte 수다. */
    char text[MATH_ENGINE_CALCULATOR_TEXT_CAPACITY]; /**< Locale-independent result UTF-8와 trailing NUL을 담는 caller-owned fixed 배열이다. */
    uint64_t evaluation_fingerprint; /**< 입력, policy와 결과를 결합한 deterministic evaluation fingerprint다. */
    uint64_t program_fingerprint; /**< Compile된 expression program 구조를 식별하는 deterministic fingerprint다. */
    uint64_t registry_fingerprint; /**< 평가에 사용한 function registry revision fingerprint다. */
    uint64_t unit_catalog_fingerprint; /**< 변환·format에 사용한 immutable unit catalog fingerprint다. */
    uint64_t rng_state; /**< 평가가 끝난 뒤 deterministic RNG state word다. */
    uint64_t rng_increment; /**< 평가가 끝난 뒤 deterministic RNG stream increment다. */
} math_engine_calculator_result_t;
  • math_engine_calculator_result_t.struct_size

    Caller가 sizeof(math_engine_calculator_result_t) 로 설정하는 byte 크기다.

    uint32_t struct_size;
    
  • math_engine_calculator_result_t.struct_version

    MATH_ENGINE_CALCULATOR_RESULT_VERSION_1 인 result ABI version이다.

    uint32_t struct_version;
    
  • math_engine_calculator_result_t.execution_status

    Native calculation이 반환한 math_engine_status_t 값이다. Facade 호출 status와 함께 해석한다.

    int32_t execution_status;
    
  • math_engine_calculator_result_t.flags

    MATH_ENGINE_CALCULATOR_RESULT_FLAG_* bit의 조합이다.

    uint32_t flags;
    
  • math_engine_calculator_result_t.mode

    Request에 지정되어 facade가 적용한 math_engine_mode_t 값이다. FULL 요청도 FULL로 기록한다.

    uint32_t mode;
    
  • math_engine_calculator_result_t.numeric_kind

    Numeric/quantity text의 math_engine_quantity_numeric_kind_t 값이다. Symbolic CAS text처럼 numeric representation이 없으면 INVALID다.

    uint32_t numeric_kind;
    
  • math_engine_calculator_result_t.angle_mode

    원형 삼각함수에 실제 적용된 math_engine_calculator_angle_mode_t 값이다.

    uint32_t angle_mode;
    
  • math_engine_calculator_result_t.text_size

    Trailing NUL을 제외한 text UTF-8 byte 수다.

    uint32_t text_size;
    
  • math_engine_calculator_result_t.text

    Locale-independent result UTF-8와 trailing NUL을 담는 caller-owned fixed 배열이다.

    char text[MATH_ENGINE_CALCULATOR_TEXT_CAPACITY];
    
  • math_engine_calculator_result_t.evaluation_fingerprint

    입력, policy와 결과를 결합한 deterministic evaluation fingerprint다.

    uint64_t evaluation_fingerprint;
    
  • math_engine_calculator_result_t.program_fingerprint

    Compile된 expression program 구조를 식별하는 deterministic fingerprint다.

    uint64_t program_fingerprint;
    
  • math_engine_calculator_result_t.registry_fingerprint

    평가에 사용한 function registry revision fingerprint다.

    uint64_t registry_fingerprint;
    
  • math_engine_calculator_result_t.unit_catalog_fingerprint

    변환·format에 사용한 immutable unit catalog fingerprint다.

    uint64_t unit_catalog_fingerprint;
    
  • math_engine_calculator_result_t.rng_state

    평가가 끝난 뒤 deterministic RNG state word다.

    uint64_t rng_state;
    
  • math_engine_calculator_result_t.rng_increment

    평가가 끝난 뒤 deterministic RNG stream increment다.

    uint64_t rng_increment;
    

math_engine_calculator_mode_resolution_t

FULL 선택을 실제 실행 mode로 해석한 compact provenance다.

typedef struct math_engine_calculator_mode_resolution {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_calculator_mode_resolution_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_CALCULATOR_MODE_RESOLUTION_VERSION_1=인 ABI version이다. */
    uint32_t selected_mode; /**< Caller가 요청한 =math_engine_mode_t= 값이다. */
    uint32_t effective_mode; /**< Capability와 관측치를 적용해 실제 실행할 concrete =math_engine_mode_t= 값이다. */
    uint32_t trace_flags; /**< FULL resolution provenance를 설명하는 =MATH_ENGINE_FULL_TRACE_FLAG_*= bit의 조합이다. */
    uint32_t escalation_reason; /**< Mode 변경 이유를 나타내는 =math_engine_escalation_reason_t= 값이다. */
    uint64_t call_fingerprint; /**< 선택 입력과 immutable capability에서 재현되는 resolution fingerprint다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 0을 기록하고 consumer는 무시한다. */
} math_engine_calculator_mode_resolution_t;
  • math_engine_calculator_mode_resolution_t.struct_size

    Caller가 sizeof(math_engine_calculator_mode_resolution_t) 로 설정하는 byte 크기다.

    uint32_t struct_size;
    
  • math_engine_calculator_mode_resolution_t.struct_version

    MATH_ENGINE_CALCULATOR_MODE_RESOLUTION_VERSION_1 인 ABI version이다.

    uint32_t struct_version;
    
  • math_engine_calculator_mode_resolution_t.selected_mode

    Caller가 요청한 math_engine_mode_t 값이다.

    uint32_t selected_mode;
    
  • math_engine_calculator_mode_resolution_t.effective_mode

    Capability와 관측치를 적용해 실제 실행할 concrete math_engine_mode_t 값이다.

    uint32_t effective_mode;
    
  • math_engine_calculator_mode_resolution_t.trace_flags

    FULL resolution provenance를 설명하는 MATH_ENGINE_FULL_TRACE_FLAG_* bit의 조합이다.

    uint32_t trace_flags;
    
  • math_engine_calculator_mode_resolution_t.escalation_reason

    Mode 변경 이유를 나타내는 math_engine_escalation_reason_t 값이다.

    uint32_t escalation_reason;
    
  • math_engine_calculator_mode_resolution_t.call_fingerprint

    선택 입력과 immutable capability에서 재현되는 resolution fingerprint다.

    uint64_t call_fingerprint;
    
  • math_engine_calculator_mode_resolution_t.reserved

    향후 ABI 확장용 두 slot이다. Producer는 0을 기록하고 consumer는 무시한다.

    uint64_t reserved[2];
    

Macro와 constant

MATH_ENGINE_CALCULATOR_MAX_VARIABLES

단일 calculator request가 제공할 수 있는 variable binding 수의 ceiling이다.

#define MATH_ENGINE_CALCULATOR_MAX_VARIABLES UINT32_C(32)

MATH_ENGINE_CALCULATOR_MODE_RESOLUTION_VERSION_1

math_engine_calculator_mode_resolution_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_CALCULATOR_MODE_RESOLUTION_VERSION_1 UINT32_C(1)

MATH_ENGINE_CALCULATOR_REQUEST_FLAG_USE_RNG_SNAPSHOT

seed 대신 rng_state/rng_increment snapshot에서 deterministic stream을 이어가는 request bit다.

#define MATH_ENGINE_CALCULATOR_REQUEST_FLAG_USE_RNG_SNAPSHOT \
    (UINT32_C(1) << 0u)

MATH_ENGINE_CALCULATOR_REQUEST_VERSION_1

math_engine_calculator_request_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_CALCULATOR_REQUEST_VERSION_1 UINT32_C(1)

MATH_ENGINE_CALCULATOR_RESULT_FLAG_EXACT

Text가 선택 representation/scale에서 exact 수치를 나타냄을 표시하는 result bit다.

#define MATH_ENGINE_CALCULATOR_RESULT_FLAG_EXACT (UINT32_C(1) << 0u)

MATH_ENGINE_CALCULATOR_RESULT_FLAG_HAS_UNIT

Text가 numeric value 뒤에 canonical unit expression을 포함함을 표시하는 result bit다.

#define MATH_ENGINE_CALCULATOR_RESULT_FLAG_HAS_UNIT (UINT32_C(1) << 1u)

MATH_ENGINE_CALCULATOR_RESULT_VERSION_1

math_engine_calculator_result_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_CALCULATOR_RESULT_VERSION_1 UINT32_C(1)

MATH_ENGINE_CALCULATOR_TEXT_CAPACITY

Calculator result UTF-8 text buffer의 trailing NUL 포함 byte capacity다.

#define MATH_ENGINE_CALCULATOR_TEXT_CAPACITY UINT32_C(512)

MATH_ENGINE_CALCULATOR_VARIABLE_NAME_CAPACITY

Variable ASCII identifier buffer의 trailing NUL 포함 byte capacity다.

#define MATH_ENGINE_CALCULATOR_VARIABLE_NAME_CAPACITY UINT32_C(32)

MATH_ENGINE_CALCULATOR_VARIABLE_VALUE_CAPACITY

Variable expression/quantity UTF-8 buffer의 trailing NUL 포함 byte capacity다.

#define MATH_ENGINE_CALCULATOR_VARIABLE_VALUE_CAPACITY UINT32_C(128)

Function

math_engine_calculator_resolve_mode

선택 mode와 workload/오차 관측값을 현재 immutable capability로 해석한다.

  • 매개변수 selected_mode: 고정 mode 또는 FULL hybrid mode.
  • 매개변수 workload_class: math_engine_workload_class_t 값.
  • 매개변수 requested_precision_bits: 요청 significand precision bit 수. 0은 mode 기본값이다.
  • 매개변수 observed_error_bound: 이전 계산에서 관측한 finite nonnegative dimensionless 상한.
  • 매개변수 observed_residual: 이전 계산에서 관측한 finite nonnegative dimensionless residual.
  • 매개변수 target_error_bound: finite nonnegative 목표 상한. 0은 관측 기반 승격을 끈다.
  • 매개변수 out_resolution: size/version을 설정한 caller output.
  • 반환: 성공 시 OK. 미지원 mode/capability, 잘못된 workload·수치·ABI에서는 output을

보존한다. 같은 build capability와 입력은 같은 mode와 fingerprint를 만든다.

  • Math Engine ownership: out_resolution=caller
  • Math Engine nullable: out_resolution=false
  • Math Engine thread_safety: safe
MATH_ENGINE_API math_engine_status_t math_engine_calculator_resolve_mode(
    math_engine_mode_t selected_mode,
    uint32_t workload_class,
    uint32_t requested_precision_bits,
    double observed_error_bound,
    double observed_residual,
    double target_error_bound,
    math_engine_calculator_mode_resolution_t* out_resolution);

math_engine_calculator_evaluate_utf8

UTF-8 expression을 native parser/compiler/evaluator로 계산한다.

  • 매개변수 expression: NUL 종료가 필요 없는 non-empty UTF-8 byte range.
  • 매개변수 expression_size: expression 의 byte 수.
  • 매개변수 request: mode, angle 단위, decimal policy, 변수와 RNG policy를 담은 request.
  • 매개변수 out_result: size/version을 설정한 caller output.
  • 반환: 성공 시 OK와 locale-independent text를 반환한다. Parse/domain/pole/divide-by-zero,

budget/cancellation 또는 ABI 오류에서는 out_result 를 보존한다. Degree mode는 원형 삼각함수에만 적용되고 hyperbolic 함수에는 적용되지 않는다. Input range, request/variable storage와 output은 서로 overlap하지 않아야 하며 pointer를 호출 뒤 보관하지 않는다.

  • Math Engine ownership: expression=borrowed request=borrowed out_result=caller
  • Math Engine nullable: expression=false request=false out_result=false
  • Math Engine thread_safety: safe
MATH_ENGINE_API math_engine_status_t math_engine_calculator_evaluate_utf8(
    const char* expression,
    uint64_t expression_size,
    const math_engine_calculator_request_t* request,
    math_engine_calculator_result_t* out_result);

math_engine_calculator_convert_utf8

UTF-8 quantity를 native unit catalog의 target unit으로 변환한다.

  • 매개변수 quantity: 수치와 source unit을 포함한 non-empty UTF-8 byte range.
  • 매개변수 quantity_size: quantity 의 byte 수.
  • 매개변수 target_unit: 변환할 target unit expression의 non-empty UTF-8 byte range.
  • 매개변수 target_unit_size: target_unit 의 byte 수.
  • 매개변수 request: 결과 numeric kind, fixed scale, rounding과 RNG provenance policy.
  • 매개변수 out_result: size/version을 설정한 caller output.
  • 반환: 차원이 호환되고 수치가 표현 가능하면 OK. Parse, 차원, 범위, ABI 오류에서는

output을 보존한다. Fixed decimal mode는 request의 scale/rounding을 사용한다. 모든 input range와 output은 non-overlapping이고 pointer는 호출 후 보관되지 않는다.

  • Math Engine ownership: quantity=borrowed target_unit=borrowed request=borrowed out_result=caller
  • Math Engine nullable: quantity=false target_unit=false request=false out_result=false
  • Math Engine thread_safety: safe
MATH_ENGINE_API math_engine_status_t math_engine_calculator_convert_utf8(
    const char* quantity,
    uint64_t quantity_size,
    const char* target_unit,
    uint64_t target_unit_size,
    const math_engine_calculator_request_t* request,
    math_engine_calculator_result_t* out_result);

math_engine_calculator_simplify_utf8

Native bounded CAS로 UTF-8 expression을 단순화한다.

  • 매개변수 expression: NUL 종료가 필요 없는 non-empty UTF-8 expression.
  • 매개변수 expression_size: expression 의 byte 수.
  • 매개변수 request: PC_PRECISION 또는 FULL mode와 deterministic RNG provenance policy.
  • 매개변수 out_result: size/version을 설정한 caller output.
  • 반환: 지원되는 exact/unevaluated 변환이면 OK. GAME_FAST/FINANCE_FIXED는 UNSUPPORTED며,

parse·budget·cancellation·buffer/ABI 오류를 포함한 모든 실패에서 output을 보존한다. 내부 CAS ceiling은 고정되어 있고 input과 output은 overlap하지 않아야 한다.

  • Math Engine ownership: expression=borrowed request=borrowed out_result=caller
  • Math Engine nullable: expression=false request=false out_result=false
  • Math Engine thread_safety: safe
MATH_ENGINE_API math_engine_status_t math_engine_calculator_simplify_utf8(
    const char* expression,
    uint64_t expression_size,
    const math_engine_calculator_request_t* request,
    math_engine_calculator_result_t* out_result);