Math Engine Reference: Linalg

Caller workspace 크기 계산과 result provenance에 사용하는 연산 ID다.

typedef enum math_engine_linalg_operation {
    MATH_ENGINE_LINALG_OPERATION_INVALID = 0, /**< Result가 초기화 상태이거나 operation provenance가 없음을 나타낸다. */
    MATH_ENGINE_LINALG_OPERATION_MATRIX_MULTIPLY = 1, /**< Dynamic row-major matrix product =lhs * rhs=를 계산했다. */
    MATH_ENGINE_LINALG_OPERATION_MATRIX_SOLVE = 2, /**< Square coefficient matrix와 right-hand side의 linear system을 풀었다. */
    MATH_ENGINE_LINALG_OPERATION_MAT4_MULTIPLY = 3 /**< Fixed-size row-major 4x4 matrix product를 계산했다. */
} math_engine_linalg_operation_t;

실제 실행한 private implementation ID다.

typedef enum math_engine_linalg_implementation {
    MATH_ENGINE_LINALG_IMPLEMENTATION_INVALID = 0, /**< 실행 implementation이 선택되지 않았음을 나타내는 sentinel이다. */
    MATH_ENGINE_LINALG_IMPLEMENTATION_PORTABLE_SCALAR = 1, /**< 모든 지원 platform에서 같은 loop 순서를 쓰는 portable scalar kernel이다. */
    MATH_ENGINE_LINALG_IMPLEMENTATION_SIMD128 = 2, /**< Capability와 mode가 허용한 128-bit SIMD vectorized kernel이다. */
    MATH_ENGINE_LINALG_IMPLEMENTATION_COMPENSATED_SCALAR = 3 /**< PC_PRECISION/FULL에서 합산 오차를 줄이는 compensated scalar kernel이다. */
} math_engine_linalg_implementation_t;

Row-major read-only dynamic matrix view다. row_stride 단위는 element다.

typedef struct math_engine_matrix_const_view_f64 {
    const double* values; /**< Caller-owned row-major matrix 원소를 빌려 읽는 pointer다. Non-empty view에서 non-null이고 호출 뒤 보관하지 않는다. */
    uint32_t rows; /**< Matrix row 수다. Operation별로 요구하는 positive dimension을 만족해야 한다. */
    uint32_t columns; /**< Matrix column 수다. Operation별 shape compatibility를 만족해야 한다. */
    uint32_t row_stride; /**< 인접 row 시작 사이의 =double= 원소 수다. =columns= 이상이어야 한다. */
    uint32_t flags; /**< Version 1 const-view flag bitset이다. 정의되지 않은 bit는 0이어야 한다. */
} math_engine_matrix_const_view_f64_t;

Row-major writable dynamic matrix view다. row_stride 단위는 element다.

typedef struct math_engine_matrix_view_f64 {
    double* values; /**< Caller-owned writable row-major matrix 원소 pointer다. Non-empty view에서 non-null이고 호출 뒤 보관하지 않는다. */
    uint32_t rows; /**< Output matrix row 수다. Operation이 요구하는 result shape와 같아야 한다. */
    uint32_t columns; /**< Output matrix column 수다. Operation이 요구하는 result shape와 같아야 한다. */
    uint32_t row_stride; /**< 인접 writable row 시작 사이의 =double= 원소 수다. =columns= 이상이어야 한다. */
    uint32_t flags; /**< Version 1 mutable-view flag bitset이다. 정의되지 않은 bit는 0이어야 한다. */
} math_engine_matrix_view_f64_t;

Mode, implementation, rank, condition과 residual을 기록하는 result다.

typedef struct math_engine_linalg_result {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_linalg_result_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_LINALG_RESULT_VERSION_1=인 result ABI version이다. */
    uint32_t operation; /**< 실행한 =math_engine_linalg_operation_t= 값이다. */
    uint32_t implementation; /**< 실제 선택한 =math_engine_linalg_implementation_t= 값이다. */
    uint32_t mode; /**< Implementation/quality를 선택한 =math_engine_mode_t= 값이다. */
    uint32_t rows; /**< Result operation의 output row 수다. */
    uint32_t columns; /**< Result operation의 output column 또는 right-hand-side 수다. */
    uint32_t inner_dimension; /**< Matrix product의 contracted dimension 또는 solve coefficient dimension이다. */
    uint32_t rank; /**< Pivot tolerance로 판정한 coefficient/output matrix의 numerical rank다. */
    uint32_t flags; /**< =MATH_ENGINE_LINALG_RESULT_FLAG_*= bit의 조합이다. */
    uint64_t workspace_used_bytes; /**< Operation이 caller scratch에서 실제 사용한 byte 수다. */
    uint64_t operation_fingerprint; /**< Shape, mode, implementation과 canonical evaluation order의 deterministic fingerprint다. */
    double condition_estimate; /**< 선택 norm에서 추정한 nonnegative condition number다. 제공하지 않는 operation은 0이다. */
    double residual_norm; /**< Solve/refinement 결과의 nonnegative residual norm이다. 제공하지 않는 operation은 0이다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Producer는 모두 0을 기록하고 consumer는 무시한다. */
} math_engine_linalg_result_t;

선택 implementation이 같은 ABI·입력·mode에서 operation order를 재현함을 나타낸다.

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

Condition estimate가 context tolerance 기준으로 수치적으로 불안정한 범위임을 나타낸다.

#define MATH_ENGINE_LINALG_RESULT_FLAG_ILL_CONDITIONED (UINT32_C(1) << 3u)

Operation이 output storage와 명시된 input storage의 exact alias를 지원했음을 나타낸다.

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

Initial solution/product 뒤 residual-based refinement pass를 하나 이상 수행했음을 나타낸다.

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

math_engine_linalg_result_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_LINALG_RESULT_VERSION_1 UINT32_C(1)

두 2차원 f64 vector의 dot product를 계산한다.

• 매개변수 lhs: 왼쪽 borrowed vector.
• 매개변수 rhs: 오른쪽 borrowed vector.
• 매개변수 out_dot: caller-owned scalar 결과.
• 반환: 성공하면 OK, null은 INVALID_ARGUMENT, non-finite 입력·결과는 NON_FINITE.

@note 실패하면 out_dot 을 변경하지 않는다.

• Math Engine ownership: lhs=borrowed rhs=borrowed out_dot=caller
• Math Engine nullable: lhs=false rhs=false out_dot=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_vec2_dot_f64(
    const math_engine_vec2_f64_t* lhs,
    const math_engine_vec2_f64_t* rhs,
    double* out_dot);

두 4차원 f64 vector의 dot product를 계산한다.

• 매개변수 lhs: 왼쪽 borrowed vector.
• 매개변수 rhs: 오른쪽 borrowed vector.
• 매개변수 out_dot: caller-owned scalar 결과.
• 반환: 성공하면 OK, null은 INVALID_ARGUMENT, non-finite 입력·결과는 NON_FINITE.

@note 실패하면 out_dot 을 변경하지 않는다.

• Math Engine ownership: lhs=borrowed rhs=borrowed out_dot=caller
• Math Engine nullable: lhs=false rhs=false out_dot=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_vec4_dot_f64(
    const math_engine_vec4_f64_t* lhs,
    const math_engine_vec4_f64_t* rhs,
    double* out_dot);

Row-major 2x2 product를 계산하며 output alias를 허용한다.

• 매개변수 lhs: 왼쪽 borrowed matrix.
• 매개변수 rhs: 오른쪽 borrowed matrix.
• 매개변수 out_product: caller-owned 결과.
• 반환: 성공하면 OK, non-finite 입력·결과는 NON_FINITE.

@note 성공 시에만 out_product 전체를 commit한다.

• Math Engine ownership: lhs=borrowed rhs=borrowed out_product=caller
• Math Engine nullable: lhs=false rhs=false out_product=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_mat2_multiply_f64(
    const math_engine_mat2_f64_t* lhs,
    const math_engine_mat2_f64_t* rhs,
    math_engine_mat2_f64_t* out_product);

두 3차원 벡터의 dot product를 계산한다.

• 매개변수 lhs: 첫 번째 borrowed vector.
• 매개변수 rhs: 두 번째 borrowed vector.
• 매개변수 out_dot: 성공 시 scalar 결과를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code. 입력이나 결과가 non-finite이면 실패한다.
• Math Engine ownership: lhs=borrowed rhs=borrowed out_dot=caller
• Math Engine nullable: lhs=false rhs=false out_dot=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_vec3_dot_f64(
    const math_engine_vec3_f64_t* lhs,
    const math_engine_vec3_f64_t* rhs,
    double* out_dot);

두 3차원 벡터의 오른손 좌표계 cross product를 계산한다.

• 매개변수 lhs: 첫 번째 borrowed vector.
• 매개변수 rhs: 두 번째 borrowed vector.
• 매개변수 out_cross: 성공 시 vector 결과를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code. 실패하면 output을 변경하지 않는다.
• Math Engine ownership: lhs=borrowed rhs=borrowed out_cross=caller
• Math Engine nullable: lhs=false rhs=false out_cross=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_vec3_cross_f64(
    const math_engine_vec3_f64_t* lhs,
    const math_engine_vec3_f64_t* rhs,
    math_engine_vec3_f64_t* out_cross);

3차원 벡터의 Euclidean norm을 overflow-resistant 방식으로 계산한다.

• 매개변수 vector: borrowed vector.
• 매개변수 out_norm: 성공 시 0 이상인 norm을 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code. 실패하면 output을 변경하지 않는다.
• Math Engine ownership: vector=borrowed out_norm=caller
• Math Engine nullable: vector=false out_norm=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_vec3_norm_f64(
    const math_engine_vec3_f64_t* vector,
    double* out_norm);

3차원 벡터를 단위 길이로 정규화한다.

• 매개변수 vector: borrowed vector.
• 매개변수 context: zero-length 퇴화 판정 tolerance를 제공하는 borrowed context.
• 매개변수 out_normalized: 성공 시 단위 vector를 받는 caller-owned storage.
• 반환: 성공, 퇴화 또는 다른 음수 상태 code. 실패하면 output을 변경하지 않는다.
• Math Engine ownership: vector=borrowed context=borrowed out_normalized=caller
• Math Engine nullable: vector=false context=false out_normalized=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_vec3_normalize_f64(
    const math_engine_vec3_f64_t* vector,
    const math_engine_context_t* context,
    math_engine_vec3_f64_t* out_normalized);

Quaternion을 단위 길이로 정규화한다.

• 매개변수 quaternion: scalar-first 형식의 borrowed quaternion.
• 매개변수 context: zero-length 퇴화 판정 tolerance를 제공하는 borrowed context.
• 매개변수 out_normalized: 성공 시 단위 quaternion을 받는 caller-owned storage.
• 반환: 성공, 퇴화 또는 다른 음수 상태 code. 실패하면 output을 변경하지 않는다.
• Math Engine ownership: quaternion=borrowed context=borrowed out_normalized=caller
• Math Engine nullable: quaternion=false context=false out_normalized=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_quat_normalize_f64(
    const math_engine_quat_f64_t* quaternion,
    const math_engine_context_t* context,
    math_engine_quat_f64_t* out_normalized);

두 quaternion orientation 사이의 shortest geodesic angle을 radian으로 계산한다.

• 매개변수 lhs: 첫 번째 scalar-first quaternion을 가리키는 borrowed pointer.
• 매개변수 rhs: 두 번째 scalar-first quaternion을 가리키는 borrowed pointer.
• 매개변수 context: zero-length 판정 tolerance를 제공하는 borrowed context.
• 매개변수 out_angle: 성공 시 radian 단위 angle을 받는 caller-owned storage.
• 반환: 성공하면 [0, pi] angle. Zero/non-finite quaternion은 오류이며 output을 보존한다.

@note 두 입력을 정규화하고 2*atan2(length(vector), abs(scalar))=를 사용하므로 =q 와 =-q=는 같은 orientation이고 acos domain drift가 없다.

• Math Engine ownership: lhs=borrowed rhs=borrowed context=borrowed out_angle=caller
• Math Engine nullable: lhs=false rhs=false context=false out_angle=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_quat_geodesic_angle_f64(
    const math_engine_quat_f64_t* lhs,
    const math_engine_quat_f64_t* rhs,
    const math_engine_context_t* context,
    double* out_angle);

두 scalar-first quaternion의 Hamilton product lhs * rhs 를 계산한다.

• 매개변수 lhs: 왼쪽 borrowed quaternion.
• 매개변수 rhs: 오른쪽 borrowed quaternion.
• 매개변수 out_product: 성공 시 product를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code. 결과가 non-finite이면 실패한다.
• Math Engine ownership: lhs=borrowed rhs=borrowed out_product=caller
• Math Engine nullable: lhs=false rhs=false out_product=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_quat_multiply_f64(
    const math_engine_quat_f64_t* lhs,
    const math_engine_quat_f64_t* rhs,
    math_engine_quat_f64_t* out_product);

Unit quaternion으로 3차원 vector를 회전한다.

• 매개변수 rotation: scalar-first unit quaternion.
• 매개변수 vector: 회전할 borrowed vector.
• 매개변수 context: unit-length 검증 tolerance를 제공하는 borrowed context.
• 매개변수 out_rotated: 성공 시 회전된 vector를 받는 caller-owned storage.
• 반환: 성공, unit 조건 위반 또는 다른 음수 상태 code. 실패하면 output을 보존한다.
• Math Engine ownership: rotation=borrowed vector=borrowed context=borrowed out_rotated=caller
• Math Engine nullable: rotation=false vector=false context=false out_rotated=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_quat_rotate_vec3_f64(
    const math_engine_quat_f64_t* rotation,
    const math_engine_vec3_f64_t* vector,
    const math_engine_context_t* context,
    math_engine_vec3_f64_t* out_rotated);

Row-major 3x3 matrix product lhs * rhs 를 계산한다.

• 매개변수 lhs: 왼쪽 borrowed matrix.
• 매개변수 rhs: 오른쪽 borrowed matrix.
• 매개변수 out_product: 성공 시 product를 받는 caller-owned storage.
• 반환: 성공 또는 음수 상태 code. 실패하면 output을 변경하지 않는다.
• Math Engine ownership: lhs=borrowed rhs=borrowed out_product=caller
• Math Engine nullable: lhs=false rhs=false out_product=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_mat3_multiply_f64(
    const math_engine_mat3_f64_t* lhs,
    const math_engine_mat3_f64_t* rhs,
    math_engine_mat3_f64_t* out_product);

Row-major 3x3 matrix의 inverse를 scale-normalized cofactor 방식으로 계산한다.

• 매개변수 matrix: 역행렬을 구할 borrowed matrix.
• 매개변수 context: determinant 퇴화 판정 tolerance를 제공하는 borrowed context.
• 매개변수 out_inverse: 성공 시 inverse를 받는 caller-owned storage.
• 반환: 성공, singular 퇴화 또는 다른 음수 상태 code. 실패하면 output을 보존한다.
• Math Engine ownership: matrix=borrowed context=borrowed out_inverse=caller
• Math Engine nullable: matrix=false context=false out_inverse=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_mat3_inverse_f64(
    const math_engine_mat3_f64_t* matrix,
    const math_engine_context_t* context,
    math_engine_mat3_f64_t* out_inverse);

Mode별 implementation으로 row-major 4x4 product를 계산한다.

• 매개변수 lhs: 왼쪽 borrowed matrix.
• 매개변수 rhs: 오른쪽 borrowed matrix.
• 매개변수 context: Game/PC/FULL implementation 선택과 tolerance를 제공한다.
• 매개변수 out_product: caller-owned 결과. lhs 또는 rhs와 같아도 된다.
• 매개변수 out_result: caller가 size/version을 초기화한 provenance.
• 반환: 성공하면 OK, Finance mode는 UNSUPPORTED, non-finite는 NON_FINITE.

@note 성공 시에만 두 output을 함께 commit한다.

• Math Engine ownership: lhs=borrowed rhs=borrowed context=borrowed out_product=caller out_result=caller
• Math Engine nullable: lhs=false rhs=false context=false out_product=false out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_mat4_multiply_context_f64(
    const math_engine_mat4_f64_t* lhs,
    const math_engine_mat4_f64_t* rhs,
    const math_engine_context_t* context,
    math_engine_mat4_f64_t* out_product,
    math_engine_linalg_result_t* out_result);

Dynamic matrix view의 pointer, shape, stride와 flag를 검증한다.

• 매개변수 matrix: 검사할 borrowed view.
• 반환: 유효하면 OK, null·0 dimension·작은 stride·unknown flag는 INVALID_ARGUMENT, element가 non-finite이면 NON_FINITE.
• Math Engine ownership: matrix=borrowed
• Math Engine nullable: matrix=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_matrix_view_validate_f64(
    const math_engine_matrix_const_view_f64_t* matrix);

Dynamic matrix operation에 필요한 scratch workspace 크기를 계산한다.

• 매개변수 operation: multiply 또는 solve.
• 매개변수 rows: 왼쪽 matrix row 또는 solve 차수.
• 매개변수 columns: multiply 결과 column 또는 solve RHS column 수.
• 매개변수 inner_dimension: multiply inner dimension. solve에서는 matrix 차수와 같아야 한다.
• 매개변수 out_size: caller-owned 필요 크기. 단위는 byte.
• 반환: 성공하면 OK, shape·operation이 잘못되면 INVALID_ARGUMENT, 크기 산술은 OVERFLOW.

@note 실패하면 out_size 를 변경하지 않는다.

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

MATH_ENGINE_API math_engine_status_t math_engine_matrix_workspace_size_f64(
    math_engine_linalg_operation_t operation,
    uint32_t rows,
    uint32_t columns,
    uint32_t inner_dimension,
    uint64_t* out_size);

Caller workspace를 사용해 row-major dynamic matrix product를 계산한다.

• 매개변수 lhs: shape MxK인 borrowed view.
• 매개변수 rhs: shape KxN인 borrowed view.
• 매개변수 context: mode, tolerance와 결정성 정책.
• 매개변수 workspace: input/output과 겹치지 않는 caller-owned scratch byte span.
• 매개변수 out_product: shape MxN인 writable view. lhs 또는 rhs storage와 겹쳐도 된다.
• 매개변수 out_result: caller가 size/version을 초기화한 provenance.
• 반환: 성공하면 OK, 작은 scratch는 INSUFFICIENT_WORKSPACE, Finance mode는 UNSUPPORTED.

@note 모든 검증과 계산이 성공한 뒤에만 output matrix와 result를 commit한다.

• Math Engine ownership: lhs=borrowed rhs=borrowed context=borrowed workspace=caller out_product=caller out_result=caller
• Math Engine nullable: lhs=false rhs=false context=false workspace.data=false out_product=false out_result=false
• Math Engine thread_safety: separate_workspace

MATH_ENGINE_API math_engine_status_t math_engine_matrix_multiply_f64(
    const math_engine_matrix_const_view_f64_t* lhs,
    const math_engine_matrix_const_view_f64_t* rhs,
    const math_engine_context_t* context,
    math_engine_mutable_byte_span_t workspace,
    const math_engine_matrix_view_f64_t* out_product,
    math_engine_linalg_result_t* out_result);

Partial-pivot LU로 =matrix * X = rhs=를 풀고 residual을 검증한다.

• 매개변수 matrix: shape NxN인 borrowed coefficient matrix.
• 매개변수 rhs: shape NxM인 borrowed right-hand-side matrix.
• 매개변수 context: singular threshold, mode와 결정성 정책.
• 매개변수 workspace: input/output과 겹치지 않는 caller-owned scratch byte span.
• 매개변수 out_solution: shape NxM인 writable 결과. input storage와 겹쳐도 된다.
• 매개변수 out_result: rank, condition estimate, residual과 backend provenance.
• 반환: 성공하면 OK, singular은 DEGENERATE, residual 보증 실패는 UNCERTAIN, 작은 scratch는 INSUFFICIENT_WORKSPACE.

@note 실패하면 solution과 result를 변경하지 않는다.

• Math Engine ownership: matrix=borrowed rhs=borrowed context=borrowed workspace=caller out_solution=caller out_result=caller
• Math Engine nullable: matrix=false rhs=false context=false workspace.data=false out_solution=false out_result=false
• Math Engine thread_safety: separate_workspace

MATH_ENGINE_API math_engine_status_t math_engine_matrix_solve_f64(
    const math_engine_matrix_const_view_f64_t* matrix,
    const math_engine_matrix_const_view_f64_t* rhs,
    const math_engine_context_t* context,
    math_engine_mutable_byte_span_t workspace,
    const math_engine_matrix_view_f64_t* out_solution,
    math_engine_linalg_result_t* out_result);