Math Engine Reference: Mode

문서 탐색

개요

Desktop runtime mode의 backend·quality·rounding·budget 계약을 선언한다.

Policy 조회는 구현 가능 여부와 분리된다. 모든 desktop mode의 canonical 요구 정책은 조회할 수 있지만 compiled backend가 없으면 context 초기화나 실행 계획은 MATH_ENGINE_STATUS_UNSUPPORTED 로 fail-closed한다.

실행 원본: include/math_engine/math_engine_mode.h
분류: 진입점·ABI·공통 계약

공개 API

Header 사용 시작

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

#include <math_engine/math_engine_mode.h>

Type과 callback

`math_engine_mode_t`

같은 desktop shared/static SDK가 선택하는 runtime mode다.

typedef enum math_engine_mode {
    MATH_ENGINE_MODE_INVALID = 0, /**< 초기화되지 않았거나 알려지지 않은 mode sentinel이다. 실행 요청에는 사용할 수 없다. */
    MATH_ENGINE_MODE_GAME_FAST = 1, /**< 낮은 latency와 bounded error를 우선하는 binary32 중심 realtime mode다. */
    MATH_ENGINE_MODE_PC_PRECISION = 2, /**< Desktop binary64와 refined algorithm을 기본으로 하는 정밀 계산 mode다. */
    MATH_ENGINE_MODE_FINANCE_FIXED = 3, /**< 명시 scale과 decimal half-even rounding을 사용하는 금액 계산 mode다. */
    /** 모든 desktop backend와 workload 조정자를 포함하는 full product mode. */
    MATH_ENGINE_MODE_FULL = 4,
    /** @deprecated Source compatibility alias. Use MATH_ENGINE_MODE_FULL. */
    MATH_ENGINE_MODE_UNLIMITED = MATH_ENGINE_MODE_FULL
} math_engine_mode_t;

math_engine_mode_t.MATH_ENGINE_MODE_INVALID
초기화되지 않았거나 알려지지 않은 mode sentinel이다. 실행 요청에는 사용할 수 없다.
```
MATH_ENGINE_MODE_INVALID = 0,
```
math_engine_mode_t.MATH_ENGINE_MODE_GAME_FAST
낮은 latency와 bounded error를 우선하는 binary32 중심 realtime mode다.
```
MATH_ENGINE_MODE_GAME_FAST = 1,
```
math_engine_mode_t.MATH_ENGINE_MODE_PC_PRECISION
Desktop binary64와 refined algorithm을 기본으로 하는 정밀 계산 mode다.
```
MATH_ENGINE_MODE_PC_PRECISION = 2,
```
math_engine_mode_t.MATH_ENGINE_MODE_FINANCE_FIXED
명시 scale과 decimal half-even rounding을 사용하는 금액 계산 mode다.
```
MATH_ENGINE_MODE_FINANCE_FIXED = 3,
```

math_engine_mode_t.MATH_ENGINE_MODE_FULL

모든 desktop backend와 workload 조정자를 포함하는 full product mode.

/** 모든 desktop backend와 workload 조정자를 포함하는 full product mode. */
    MATH_ENGINE_MODE_FULL = 4,

math_engine_mode_t.MATH_ENGINE_MODE_UNLIMITED

@deprecated Source compatibility alias. Use MATH_ENGINE_MODE_FULL.

/** @deprecated Source compatibility alias. Use MATH_ENGINE_MODE_FULL. */
    MATH_ENGINE_MODE_UNLIMITED = MATH_ENGINE_MODE_FULL,

`math_engine_scalar_backend_t`

Mode가 기본으로 선택하는 scalar/backend family다.

typedef enum math_engine_scalar_backend {
    MATH_ENGINE_SCALAR_BACKEND_INVALID = 0, /**< 초기화되지 않았거나 사용할 수 없는 backend sentinel이다. */
    MATH_ENGINE_SCALAR_BACKEND_BINARY32 = 1, /**< IEEE-754 binary32 scalar backend다. */
    MATH_ENGINE_SCALAR_BACKEND_BINARY64 = 2, /**< IEEE-754 binary64 scalar backend다. */
    MATH_ENGINE_SCALAR_BACKEND_DECIMAL_FIXED = 3, /**< 명시적 decimal scale을 가진 fixed-point backend다. */
    MATH_ENGINE_SCALAR_BACKEND_ARBITRARY_PRECISION = 4, /**< 요청 bit 수에 맞춰 확장하는 arbitrary-precision backend다. */
    MATH_ENGINE_SCALAR_BACKEND_HYBRID = 5 /**< Workload와 error bound에 따라 여러 backend 사이를 단계적으로 선택하는 조정 backend다. */
} math_engine_scalar_backend_t;

math_engine_scalar_backend_t.MATH_ENGINE_SCALAR_BACKEND_INVALID
초기화되지 않았거나 사용할 수 없는 backend sentinel이다.
```
MATH_ENGINE_SCALAR_BACKEND_INVALID = 0,
```
math_engine_scalar_backend_t.MATH_ENGINE_SCALAR_BACKEND_BINARY32
IEEE-754 binary32 scalar backend다.
```
MATH_ENGINE_SCALAR_BACKEND_BINARY32 = 1,
```
math_engine_scalar_backend_t.MATH_ENGINE_SCALAR_BACKEND_BINARY64
IEEE-754 binary64 scalar backend다.
```
MATH_ENGINE_SCALAR_BACKEND_BINARY64 = 2,
```
math_engine_scalar_backend_t.MATH_ENGINE_SCALAR_BACKEND_DECIMAL_FIXED
명시적 decimal scale을 가진 fixed-point backend다.
```
MATH_ENGINE_SCALAR_BACKEND_DECIMAL_FIXED = 3,
```
math_engine_scalar_backend_t.MATH_ENGINE_SCALAR_BACKEND_ARBITRARY_PRECISION
요청 bit 수에 맞춰 확장하는 arbitrary-precision backend다.
```
MATH_ENGINE_SCALAR_BACKEND_ARBITRARY_PRECISION = 4,
```
math_engine_scalar_backend_t.MATH_ENGINE_SCALAR_BACKEND_HYBRID
Workload와 error bound에 따라 여러 backend 사이를 단계적으로 선택하는 조정 backend다.
```
MATH_ENGINE_SCALAR_BACKEND_HYBRID = 5,
```

`math_engine_algorithm_quality_t`

Algorithm의 결과 품질 class다.

typedef enum math_engine_algorithm_quality {
    MATH_ENGINE_ALGORITHM_QUALITY_INVALID = 0, /**< 초기화되지 않았거나 알려지지 않은 quality sentinel이다. */
    MATH_ENGINE_ALGORITHM_QUALITY_FAST_BOUNDED = 1, /**< 명시된 오차 상한 안에서 latency를 우선하는 quality다. */
    MATH_ENGINE_ALGORITHM_QUALITY_REFINED = 2, /**< 추가 iteration/evaluation으로 binary 결과를 정제하는 quality다. */
    MATH_ENGINE_ALGORITHM_QUALITY_EXACT_DECIMAL = 3, /**< 선택 scale과 rounding 규칙 아래 정확한 decimal 정수 산술 quality다. */
    MATH_ENGINE_ALGORITHM_QUALITY_HYBRID_ESCALATING = 4 /**< 증거가 부족할 때 더 강한 backend로 deterministic하게 승격하는 quality다. */
} math_engine_algorithm_quality_t;

math_engine_algorithm_quality_t.MATH_ENGINE_ALGORITHM_QUALITY_INVALID
초기화되지 않았거나 알려지지 않은 quality sentinel이다.
```
MATH_ENGINE_ALGORITHM_QUALITY_INVALID = 0,
```
math_engine_algorithm_quality_t.MATH_ENGINE_ALGORITHM_QUALITY_FAST_BOUNDED
명시된 오차 상한 안에서 latency를 우선하는 quality다.
```
MATH_ENGINE_ALGORITHM_QUALITY_FAST_BOUNDED = 1,
```
math_engine_algorithm_quality_t.MATH_ENGINE_ALGORITHM_QUALITY_REFINED
추가 iteration/evaluation으로 binary 결과를 정제하는 quality다.
```
MATH_ENGINE_ALGORITHM_QUALITY_REFINED = 2,
```
math_engine_algorithm_quality_t.MATH_ENGINE_ALGORITHM_QUALITY_EXACT_DECIMAL
선택 scale과 rounding 규칙 아래 정확한 decimal 정수 산술 quality다.
```
MATH_ENGINE_ALGORITHM_QUALITY_EXACT_DECIMAL = 3,
```
math_engine_algorithm_quality_t.MATH_ENGINE_ALGORITHM_QUALITY_HYBRID_ESCALATING
증거가 부족할 때 더 강한 backend로 deterministic하게 승격하는 quality다.
```
MATH_ENGINE_ALGORITHM_QUALITY_HYBRID_ESCALATING = 4,
```

`math_engine_rounding_policy_t`

Mode 기본 rounding 정책이다. 개별 decimal operation은 scale과 tie rule을 재확인한다.

typedef enum math_engine_rounding_policy {
    MATH_ENGINE_ROUNDING_POLICY_INVALID = 0, /**< 초기화되지 않았거나 알려지지 않은 rounding policy sentinel이다. */
    MATH_ENGINE_ROUNDING_POLICY_NEAREST_EVEN = 1, /**< Binary 연산의 round-to-nearest, ties-to-even 정책이다. */
    MATH_ENGINE_ROUNDING_POLICY_DECIMAL_HALF_EVEN = 2, /**< Decimal scale 경계에서 가장 가까운 값, 정확한 tie는 짝수로 반올림한다. */
    MATH_ENGINE_ROUNDING_POLICY_MODE_DEPENDENT = 3 /**< FULL planner가 선택한 최종 backend의 canonical rounding 정책을 따른다. */
} math_engine_rounding_policy_t;

math_engine_rounding_policy_t.MATH_ENGINE_ROUNDING_POLICY_INVALID
초기화되지 않았거나 알려지지 않은 rounding policy sentinel이다.
```
MATH_ENGINE_ROUNDING_POLICY_INVALID = 0,
```
math_engine_rounding_policy_t.MATH_ENGINE_ROUNDING_POLICY_NEAREST_EVEN
Binary 연산의 round-to-nearest, ties-to-even 정책이다.
```
MATH_ENGINE_ROUNDING_POLICY_NEAREST_EVEN = 1,
```
math_engine_rounding_policy_t.MATH_ENGINE_ROUNDING_POLICY_DECIMAL_HALF_EVEN
Decimal scale 경계에서 가장 가까운 값, 정확한 tie는 짝수로 반올림한다.
```
MATH_ENGINE_ROUNDING_POLICY_DECIMAL_HALF_EVEN = 2,
```
math_engine_rounding_policy_t.MATH_ENGINE_ROUNDING_POLICY_MODE_DEPENDENT
FULL planner가 선택한 최종 backend의 canonical rounding 정책을 따른다.
```
MATH_ENGINE_ROUNDING_POLICY_MODE_DEPENDENT = 3,
```

`math_engine_mode_policy_t`

모든 build가 공유하는 mode policy descriptor version 1이다.

typedef struct math_engine_mode_policy {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_mode_policy_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_ABI_VERSION=과 함께 검증되는 mode-policy ABI version이다. */
    uint32_t mode; /**< 이 descriptor가 설명하는 =math_engine_mode_t= 값이다. */
    uint32_t default_scalar_backend; /**< Mode가 workload override 없이 선택하는 =math_engine_scalar_backend_t= 값이다. */
    uint32_t algorithm_quality; /**< Mode의 기본 =math_engine_algorithm_quality_t= 보증 수준이다. */
    uint32_t rounding_policy; /**< Mode의 기본 =math_engine_rounding_policy_t= 값이다. */
    uint32_t deterministic; /**< 1이면 같은 ABI·입력·capability에서 실행 계획과 결과 재현성을 요구한다. */
    uint32_t heap_allowed; /**< 1이면 mode 구현이 heap allocation을 사용할 수 있고 0이면 caller workspace만 사용한다. */
    double absolute_tolerance; /**< Mode 기본 절대 tolerance다. 단위는 소비 operation의 결과 단위를 따른다. */
    double relative_tolerance; /**< Mode 기본 무차원 상대 tolerance다. */
    uint64_t max_iterations; /**< Mode 기본 iterative-kernel iteration ceiling이다. */
    uint64_t max_evaluations; /**< Mode 기본 function/kernel evaluation ceiling이다. */
    uint64_t required_capabilities; /**< Mode 실행에 필요한 =MATH_ENGINE_CAPABILITY_*= bit의 합집합이다. */
    uint32_t flags; /**< Version 1 mode-policy flag bitset이다. 정의되지 않은 bit는 0이어야 한다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
} math_engine_mode_policy_t;

math_engine_mode_policy_t.struct_size
Caller가 sizeof(math_engine_mode_policy_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_mode_policy_t.struct_version
MATH_ENGINE_ABI_VERSION 과 함께 검증되는 mode-policy ABI version이다.
```
uint32_t struct_version;
```
math_engine_mode_policy_t.mode
이 descriptor가 설명하는 math_engine_mode_t 값이다.
```
uint32_t mode;
```
math_engine_mode_policy_t.default_scalar_backend
Mode가 workload override 없이 선택하는 math_engine_scalar_backend_t 값이다.
```
uint32_t default_scalar_backend;
```
math_engine_mode_policy_t.algorithm_quality
Mode의 기본 math_engine_algorithm_quality_t 보증 수준이다.
```
uint32_t algorithm_quality;
```
math_engine_mode_policy_t.rounding_policy
Mode의 기본 math_engine_rounding_policy_t 값이다.
```
uint32_t rounding_policy;
```
math_engine_mode_policy_t.deterministic
1이면 같은 ABI·입력·capability에서 실행 계획과 결과 재현성을 요구한다.
```
uint32_t deterministic;
```
math_engine_mode_policy_t.heap_allowed
1이면 mode 구현이 heap allocation을 사용할 수 있고 0이면 caller workspace만 사용한다.
```
uint32_t heap_allowed;
```
math_engine_mode_policy_t.absolute_tolerance
Mode 기본 절대 tolerance다. 단위는 소비 operation의 결과 단위를 따른다.
```
double absolute_tolerance;
```
math_engine_mode_policy_t.relative_tolerance
Mode 기본 무차원 상대 tolerance다.
```
double relative_tolerance;
```
math_engine_mode_policy_t.max_iterations
Mode 기본 iterative-kernel iteration ceiling이다.
```
uint64_t max_iterations;
```
math_engine_mode_policy_t.max_evaluations
Mode 기본 function/kernel evaluation ceiling이다.
```
uint64_t max_evaluations;
```
math_engine_mode_policy_t.required_capabilities
Mode 실행에 필요한 MATH_ENGINE_CAPABILITY_* bit의 합집합이다.
```
uint64_t required_capabilities;
```
math_engine_mode_policy_t.flags
Version 1 mode-policy flag bitset이다. 정의되지 않은 bit는 0이어야 한다.
```
uint32_t flags;
```
math_engine_mode_policy_t.reserved
향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다.
```
uint32_t reserved;
```

Macro와 constant

`MATH_ENGINE_CAPABILITY_ARBITRARY_PRECISION`

Artifact가 arbitrary-precision backend를 실행할 수 있음을 나타내는 capability bit다.

#define MATH_ENGINE_CAPABILITY_ARBITRARY_PRECISION (UINT64_C(1) << 3u)

`MATH_ENGINE_CAPABILITY_BINARY32`

Artifact가 binary32 scalar backend를 실행할 수 있음을 나타내는 capability bit다.

#define MATH_ENGINE_CAPABILITY_BINARY32 (UINT64_C(1) << 0u)

`MATH_ENGINE_CAPABILITY_BINARY64`

Artifact가 binary64 scalar backend를 실행할 수 있음을 나타내는 capability bit다.

#define MATH_ENGINE_CAPABILITY_BINARY64 (UINT64_C(1) << 1u)

`MATH_ENGINE_CAPABILITY_DECIMAL_FIXED`

Artifact가 fixed-scale decimal backend를 실행할 수 있음을 나타내는 capability bit다.

#define MATH_ENGINE_CAPABILITY_DECIMAL_FIXED (UINT64_C(1) << 2u)

Function

`math_engine_mode_policy_get`

Mode의 canonical policy를 조회한다.

매개변수 mode: 네 desktop mode 중 하나.
매개변수 out_policy: caller가 size/version을 초기화한 output.
반환: 알려진 mode면 OK. 현재 build 지원 여부와 무관하며 실패 시 output을 보존한다.
Math Engine ownership: out_policy=caller
Math Engine nullable: out_policy=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_mode_policy_get(
    math_engine_mode_t mode,
    math_engine_mode_policy_t* out_policy);

Math Engine Reference: Mode

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_mode_t

math_engine_scalar_backend_t

math_engine_algorithm_quality_t

math_engine_rounding_policy_t

math_engine_mode_policy_t