Math Engine Reference: Calculator
문서 탐색
개요
@file math_engine_calculator.h Python/CLI/GUI가 canonical expression·quantity·CAS를 사용하는 얇은 desktop facade.
- 실행 원본:
include/math_engine/math_engine_calculator.h - 분류: 식·CAS·계산기·plot
관련 public header
공개 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을 제외한
nameUTF-8 byte 수다. 1 이상이고 capacity보다 작아야 한다.uint32_t name_size;
math_engine_calculator_variable_t.value_size
Trailing NUL을 제외한
valueUTF-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을 제외한
textUTF-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);