Math Engine Reference: Execution

문서 탐색

개요

Explicit mode와 FULL hybrid escalation의 deterministic trace ABI다.

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

공개 API

Header 사용 시작

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

#include <math_engine/math_engine_execution.h>

Type과 callback

`math_engine_workload_class_t`

대표 workload class다. 실제 수식은 canonical kernel 구현에 남는다.

typedef enum math_engine_workload_class {
    MATH_ENGINE_WORKLOAD_CLASS_INVALID = 0, /**< 초기화되지 않았거나 planner가 인식하지 못하는 workload sentinel이다. */
    MATH_ENGINE_WORKLOAD_CLASS_REALTIME = 1, /**< Bounded latency와 GAME_FAST-compatible error bound를 우선하는 workload다. */
    MATH_ENGINE_WORKLOAD_CLASS_SCIENTIFIC = 2, /**< Binary64 이상 precision과 refined error control을 우선하는 workload다. */
    MATH_ENGINE_WORKLOAD_CLASS_MONEY = 3, /**< Fixed decimal scale와 finance rounding을 강제하는 금액 workload다. */
    MATH_ENGINE_WORKLOAD_CLASS_AMBIGUOUS = 4 /**< Initial backend만으로 품질을 인증할 수 없으면 escalation을 허용하는 workload다. */
} math_engine_workload_class_t;

math_engine_workload_class_t.MATH_ENGINE_WORKLOAD_CLASS_INVALID
초기화되지 않았거나 planner가 인식하지 못하는 workload sentinel이다.
```
MATH_ENGINE_WORKLOAD_CLASS_INVALID = 0,
```
math_engine_workload_class_t.MATH_ENGINE_WORKLOAD_CLASS_REALTIME
Bounded latency와 GAME_FAST-compatible error bound를 우선하는 workload다.
```
MATH_ENGINE_WORKLOAD_CLASS_REALTIME = 1,
```
math_engine_workload_class_t.MATH_ENGINE_WORKLOAD_CLASS_SCIENTIFIC
Binary64 이상 precision과 refined error control을 우선하는 workload다.
```
MATH_ENGINE_WORKLOAD_CLASS_SCIENTIFIC = 2,
```
math_engine_workload_class_t.MATH_ENGINE_WORKLOAD_CLASS_MONEY
Fixed decimal scale와 finance rounding을 강제하는 금액 workload다.
```
MATH_ENGINE_WORKLOAD_CLASS_MONEY = 3,
```
math_engine_workload_class_t.MATH_ENGINE_WORKLOAD_CLASS_AMBIGUOUS
Initial backend만으로 품질을 인증할 수 없으면 escalation을 허용하는 workload다.
```
MATH_ENGINE_WORKLOAD_CLASS_AMBIGUOUS = 4,
```

`math_engine_kernel_id_t`

Planner가 선택하는 canonical kernel 식별자다.

typedef enum math_engine_kernel_id {
    MATH_ENGINE_KERNEL_ID_INVALID = 0, /**< 실행 가능한 canonical kernel이 선택되지 않았음을 나타내는 sentinel이다. */
    MATH_ENGINE_KERNEL_ID_CANONICAL_SCALAR = 1, /**< Public scalar reference semantics를 구현하는 canonical scalar kernel이다. */
    /** GAME_FAST runtime dispatch; the selected private scalar/SIMD kernel is queried separately. */
    MATH_ENGINE_KERNEL_ID_GAME_FAST_DISPATCH = 2
} math_engine_kernel_id_t;

math_engine_kernel_id_t.MATH_ENGINE_KERNEL_ID_INVALID
실행 가능한 canonical kernel이 선택되지 않았음을 나타내는 sentinel이다.
```
MATH_ENGINE_KERNEL_ID_INVALID = 0,
```
math_engine_kernel_id_t.MATH_ENGINE_KERNEL_ID_CANONICAL_SCALAR
Public scalar reference semantics를 구현하는 canonical scalar kernel이다.
```
MATH_ENGINE_KERNEL_ID_CANONICAL_SCALAR = 1,
```
math_engine_kernel_id_t.MATH_ENGINE_KERNEL_ID_GAME_FAST_DISPATCH
GAME_FAST runtime dispatch; the selected private scalar/SIMD kernel is queried separately.
```
/** GAME_FAST runtime dispatch; the selected private scalar/SIMD kernel is queried separately. */
    MATH_ENGINE_KERNEL_ID_GAME_FAST_DISPATCH = 2,
```

`math_engine_escalation_reason_t`

Backend 고정 또는 escalation의 이유다.

typedef enum math_engine_escalation_reason {
    MATH_ENGINE_ESCALATION_REASON_NONE = 0, /**< Initial backend가 그대로 final backend가 되어 escalation이 없었다. */
    MATH_ENGINE_ESCALATION_REASON_USER_PRECISION = 1, /**< Caller가 initial backend ceiling보다 높은 significand precision을 요청했다. */
    MATH_ENGINE_ESCALATION_REASON_ERROR_BOUND = 2, /**< Initial backend의 planned error가 요청 target bound를 만족하지 못했다. */
    MATH_ENGINE_ESCALATION_REASON_AMBIGUITY = 3, /**< Initial result의 불확실성을 해소하려고 더 강한 backend가 필요했다. */
    MATH_ENGINE_ESCALATION_REASON_FINANCE_FIXED_LOCK = 4, /**< Money workload가 decimal-fixed backend와 rounding을 고정했다. */
    MATH_ENGINE_ESCALATION_REASON_CAPABILITY_MISSING = 5, /**< 필요한 backend capability가 artifact에 없어 실행 계획을 만들 수 없었다. */
    MATH_ENGINE_ESCALATION_REASON_MODE_CONSTRAINT = 6 /**< 선택 mode 정책이 요청 workload·precision·heap 조건을 허용하지 않았다. */
} math_engine_escalation_reason_t;

math_engine_escalation_reason_t.MATH_ENGINE_ESCALATION_REASON_NONE
Initial backend가 그대로 final backend가 되어 escalation이 없었다.
```
MATH_ENGINE_ESCALATION_REASON_NONE = 0,
```
math_engine_escalation_reason_t.MATH_ENGINE_ESCALATION_REASON_USER_PRECISION
Caller가 initial backend ceiling보다 높은 significand precision을 요청했다.
```
MATH_ENGINE_ESCALATION_REASON_USER_PRECISION = 1,
```
math_engine_escalation_reason_t.MATH_ENGINE_ESCALATION_REASON_ERROR_BOUND
Initial backend의 planned error가 요청 target bound를 만족하지 못했다.
```
MATH_ENGINE_ESCALATION_REASON_ERROR_BOUND = 2,
```
math_engine_escalation_reason_t.MATH_ENGINE_ESCALATION_REASON_AMBIGUITY
Initial result의 불확실성을 해소하려고 더 강한 backend가 필요했다.
```
MATH_ENGINE_ESCALATION_REASON_AMBIGUITY = 3,
```
math_engine_escalation_reason_t.MATH_ENGINE_ESCALATION_REASON_FINANCE_FIXED_LOCK
Money workload가 decimal-fixed backend와 rounding을 고정했다.
```
MATH_ENGINE_ESCALATION_REASON_FINANCE_FIXED_LOCK = 4,
```
math_engine_escalation_reason_t.MATH_ENGINE_ESCALATION_REASON_CAPABILITY_MISSING
필요한 backend capability가 artifact에 없어 실행 계획을 만들 수 없었다.
```
MATH_ENGINE_ESCALATION_REASON_CAPABILITY_MISSING = 5,
```
math_engine_escalation_reason_t.MATH_ENGINE_ESCALATION_REASON_MODE_CONSTRAINT
선택 mode 정책이 요청 workload·precision·heap 조건을 허용하지 않았다.
```
MATH_ENGINE_ESCALATION_REASON_MODE_CONSTRAINT = 6,
```

`math_engine_execution_request_t`

Caller가 지정하는 execution planning request다.

typedef struct math_engine_execution_request {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_execution_request_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_EXECUTION_REQUEST_VERSION_1=인 request ABI version이다. */
    uint32_t mode; /**< 실행 정책을 선택하는 =math_engine_mode_t= 값이다. */
    uint32_t workload_class; /**< Backend 선택을 구체화하는 =math_engine_workload_class_t= 값이다. */
    uint32_t requested_precision_bits; /**< 요청 significand precision(bit)이다. 0이면 mode 기본 precision을 사용한다. */
    uint32_t flags; /**< Version 1 request flag bitset이다. 정의되지 않은 bit는 0이어야 한다. */
    double target_error_bound; /**< 무차원 finite nonnegative 절대 error ceiling이다. 0이면 별도 ceiling을 요구하지 않는다. */
} math_engine_execution_request_t;

math_engine_execution_request_t.struct_size
Caller가 sizeof(math_engine_execution_request_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_execution_request_t.struct_version
MATH_ENGINE_EXECUTION_REQUEST_VERSION_1 인 request ABI version이다.
```
uint32_t struct_version;
```
math_engine_execution_request_t.mode
실행 정책을 선택하는 math_engine_mode_t 값이다.
```
uint32_t mode;
```
math_engine_execution_request_t.workload_class
Backend 선택을 구체화하는 math_engine_workload_class_t 값이다.
```
uint32_t workload_class;
```
math_engine_execution_request_t.requested_precision_bits
요청 significand precision(bit)이다. 0이면 mode 기본 precision을 사용한다.
```
uint32_t requested_precision_bits;
```
math_engine_execution_request_t.flags
Version 1 request flag bitset이다. 정의되지 않은 bit는 0이어야 한다.
```
uint32_t flags;
```
math_engine_execution_request_t.target_error_bound
무차원 finite nonnegative 절대 error ceiling이다. 0이면 별도 ceiling을 요구하지 않는다.
```
double target_error_bound;
```

`math_engine_execution_trace_t`

Backend provenance와 budget을 기록하는 output trace다. execution_status가 UNSUPPORTED여도 planning 호출 자체는 OK이며 이 trace로 결손 capability를 설명한다.

typedef struct math_engine_execution_trace {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_execution_trace_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_EXECUTION_TRACE_VERSION_1=인 trace ABI version이다. */
    uint32_t mode; /**< Planner가 적용한 =math_engine_mode_t= 값이다. */
    uint32_t workload_class; /**< Planner가 분류한 =math_engine_workload_class_t= 값이다. */
    uint32_t kernel_id; /**< 선택한 =math_engine_kernel_id_t= canonical kernel 식별자다. */
    uint32_t initial_backend; /**< Escalation 전에 mode가 선택한 =math_engine_scalar_backend_t= 값이다. */
    uint32_t final_backend; /**< 모든 제약을 적용한 최종 =math_engine_scalar_backend_t= 값이다. */
    uint32_t escalation_reason; /**< Backend 변경 또는 고정 이유를 나타내는 =math_engine_escalation_reason_t= 값이다. */
    uint32_t initial_precision_bits; /**< Initial backend가 계획한 significand precision(bit)이다. */
    uint32_t final_precision_bits; /**< Final backend가 계획한 significand precision(bit)이다. */
    uint32_t requested_precision_bits; /**< 검증 뒤 반영된 caller 요청 precision(bit)이며 0은 mode 기본값이다. */
    int32_t execution_status; /**< 계획된 실행의 =math_engine_status_t=다. Planning API 자체 status와 구별한다. */
    double target_error_bound; /**< Request에서 검증된 무차원 target error ceiling이다. */
    double planned_error_bound; /**< Final backend가 보증할 수 있다고 계획한 무차원 error ceiling이다. */
    uint64_t max_iterations; /**< 선택 mode가 execution에 허용한 iteration budget이다. */
    uint64_t max_evaluations; /**< 선택 mode가 execution에 허용한 evaluation budget이다. */
    uint64_t required_capabilities; /**< 이 plan 실행에 필요한 capability bit의 합집합이다. */
    uint64_t available_capabilities; /**< 입력 capability snapshot에서 사용 가능했던 bit의 합집합이다. */
    uint32_t escalation_count; /**< Initial에서 final backend까지 수행할 deterministic escalation 단계 수다. */
    uint32_t flags; /**< =MATH_ENGINE_EXECUTION_TRACE_FLAG_*= bit의 조합이다. 정의되지 않은 bit는 0이다. */
} math_engine_execution_trace_t;

math_engine_execution_trace_t.struct_size
Caller가 sizeof(math_engine_execution_trace_t) 로 설정하는 byte 크기다.
```
uint32_t struct_size;
```
math_engine_execution_trace_t.struct_version
MATH_ENGINE_EXECUTION_TRACE_VERSION_1 인 trace ABI version이다.
```
uint32_t struct_version;
```
math_engine_execution_trace_t.mode
Planner가 적용한 math_engine_mode_t 값이다.
```
uint32_t mode;
```
math_engine_execution_trace_t.workload_class
Planner가 분류한 math_engine_workload_class_t 값이다.
```
uint32_t workload_class;
```
math_engine_execution_trace_t.kernel_id
선택한 math_engine_kernel_id_t canonical kernel 식별자다.
```
uint32_t kernel_id;
```
math_engine_execution_trace_t.initial_backend
Escalation 전에 mode가 선택한 math_engine_scalar_backend_t 값이다.
```
uint32_t initial_backend;
```
math_engine_execution_trace_t.final_backend
모든 제약을 적용한 최종 math_engine_scalar_backend_t 값이다.
```
uint32_t final_backend;
```
math_engine_execution_trace_t.escalation_reason
Backend 변경 또는 고정 이유를 나타내는 math_engine_escalation_reason_t 값이다.
```
uint32_t escalation_reason;
```
math_engine_execution_trace_t.initial_precision_bits
Initial backend가 계획한 significand precision(bit)이다.
```
uint32_t initial_precision_bits;
```
math_engine_execution_trace_t.final_precision_bits
Final backend가 계획한 significand precision(bit)이다.
```
uint32_t final_precision_bits;
```
math_engine_execution_trace_t.requested_precision_bits
검증 뒤 반영된 caller 요청 precision(bit)이며 0은 mode 기본값이다.
```
uint32_t requested_precision_bits;
```
math_engine_execution_trace_t.execution_status
계획된 실행의 math_engine_status_t 다. Planning API 자체 status와 구별한다.
```
int32_t execution_status;
```
math_engine_execution_trace_t.target_error_bound
Request에서 검증된 무차원 target error ceiling이다.
```
double target_error_bound;
```
math_engine_execution_trace_t.planned_error_bound
Final backend가 보증할 수 있다고 계획한 무차원 error ceiling이다.
```
double planned_error_bound;
```
math_engine_execution_trace_t.max_iterations
선택 mode가 execution에 허용한 iteration budget이다.
```
uint64_t max_iterations;
```
math_engine_execution_trace_t.max_evaluations
선택 mode가 execution에 허용한 evaluation budget이다.
```
uint64_t max_evaluations;
```
math_engine_execution_trace_t.required_capabilities
이 plan 실행에 필요한 capability bit의 합집합이다.
```
uint64_t required_capabilities;
```
math_engine_execution_trace_t.available_capabilities
입력 capability snapshot에서 사용 가능했던 bit의 합집합이다.
```
uint64_t available_capabilities;
```
math_engine_execution_trace_t.escalation_count
Initial에서 final backend까지 수행할 deterministic escalation 단계 수다.
```
uint32_t escalation_count;
```
math_engine_execution_trace_t.flags
MATH_ENGINE_EXECUTION_TRACE_FLAG_* bit의 조합이다. 정의되지 않은 bit는 0이다.
```
uint32_t flags;
```

Macro와 constant

`MATH_ENGINE_EXECUTION_REQUEST_VERSION_1`

math_engine_execution_request_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_EXECUTION_REQUEST_VERSION_1 1u

`MATH_ENGINE_EXECUTION_TRACE_FLAG_DETERMINISTIC`

Plan이 같은 ABI·request·capability snapshot에서 재현 가능함을 나타내는 trace bit다.

#define MATH_ENGINE_EXECUTION_TRACE_FLAG_DETERMINISTIC (UINT32_C(1) << 2u)

`MATH_ENGINE_EXECUTION_TRACE_FLAG_ESCALATED`

Initial backend와 final backend가 달라 실제 escalation이 계획됐음을 나타내는 trace bit다.

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

`MATH_ENGINE_EXECUTION_TRACE_FLAG_EXACT`

Final backend가 요청 representation에서 exact 결과를 제공함을 나타내는 trace bit다.

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

`MATH_ENGINE_EXECUTION_TRACE_VERSION_1`

math_engine_execution_trace_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_EXECUTION_TRACE_VERSION_1 1u

Function

`math_engine_execution_plan`

Mode/workload를 canonical kernel과 backend provenance로 계획한다.

매개변수 request: mode, workload, 요청 significand bit 수와 dimensionless 절대 오차 상한을

지정하는 immutable request. target_error_bound 0은 별도 상한 없음이다.

매개변수 capabilities: 실행 가능 backend와 ceiling을 고정한 immutable snapshot.
매개변수 out_trace: size/version을 설정한 caller output. 성공 시에만 한 번에 commit된다.
반환: 입력 ABI가 유효하면 OK. Capability 부족, precision ceiling 또는 mode 제약은

out_trace->execution_status 로 구분한다. 입력 검증 실패에서는 output을 보존한다. 계획은 locale·전역 mode와 무관하고 같은 입력에 deterministic하다.

Math Engine ownership: request=borrowed capabilities=borrowed out_trace=caller
Math Engine nullable: request=false capabilities=false out_trace=false
Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_execution_plan(
    const math_engine_execution_request_t* request,
    const math_engine_capability_descriptor_t* capabilities,
    math_engine_execution_trace_t* out_trace);

Math Engine Reference: Execution

문서 탐색

개요

관련 public header

공개 API

Header 사용 시작

Type과 callback

math_engine_workload_class_t

math_engine_kernel_id_t

math_engine_escalation_reason_t

math_engine_execution_request_t

math_engine_execution_trace_t

Macro와 constant

MATH_ENGINE_EXECUTION_REQUEST_VERSION_1

MATH_ENGINE_EXECUTION_TRACE_FLAG_DETERMINISTIC

MATH_ENGINE_EXECUTION_TRACE_FLAG_ESCALATED

MATH_ENGINE_EXECUTION_TRACE_FLAG_EXACT

MATH_ENGINE_EXECUTION_TRACE_VERSION_1