Math Engine Reference: Optimization

한 점에서 최소화할 목적 함수 값을 계산하는 callback이다.

• 매개변수 argument: 유한한 평가 위치.
• 매개변수 user_data: caller가 소유하는 opaque pointer.
• 매개변수 out_value: 목적 함수 값을 기록할 caller-provided storage.
• 반환: 성공이면 MATH_ENGINE_STATUS_OK, 실패이면 음수 상태 code.

Optimizer를 호출한 thread에서만 동기적으로 호출하며 저장하거나 다른 thread로 전달하지 않는다. Callback은 C++ exception을 ABI 경계 밖으로 전파하면 안 된다. 성공 시 finite 값을 기록해야 하며 실패 시 out_value 의 내용은 optimizer가 사용하지 않는다.

• Math Engine ownership: user_data=caller out_value=caller
• Math Engine nullable: user_data=true out_value=false
• Math Engine thread_safety: conditional
• Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

typedef math_engine_status_t (*math_engine_objective_f64_fn)(
    double argument,
    void* user_data,
    double* out_value);

유한 구간 최소화 결과와 실제 사용 예산을 보관하는 caller-owned POD다.

typedef struct math_engine_optimization_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_optimization_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t reserved; /**< 향후 ABI 확장용이다. Producer는 0을 기록하고 consumer는 무시한다. */
    uint64_t iteration_count; /**< Golden-section bracket을 줄인 iteration 수다. */
    uint64_t evaluation_count; /**< Objective callback을 동기 호출한 총횟수다. */
    double argument; /**< 최종 bracket에서 선택한 유한 minimizer argument다. */
    double value; /**< =argument=에서 평가한 finite objective value다. */
    double final_lower_bound; /**< 수렴한 closed minimizer bracket의 유한 하한이다. */
    double final_upper_bound; /**< 수렴한 closed minimizer bracket의 유한 상한이다. */
} math_engine_optimization_result_f64_t;

Box optimizer가 vector objective와 최대 constraint violation을 평가하는 callback이다.

• 매개변수 argument: dimension 개의 finite 좌표를 가진 borrowed 평가점.
• 매개변수 dimension: argument 의 element 수이며 solve option의 dimension과 같다.
• 매개변수 user_data: caller가 solve 동안 유효하게 유지하는 opaque pointer.
• 매개변수 out_value: 성공 시 finite objective 값을 기록할 caller-provided storage.
• 매개변수 out_max_constraint_violation: 성공 시 0 이상 finite 최대 제약 위반을 기록할 storage.
• 반환: 성공이면 MATH_ENGINE_STATUS_OK, 실패이면 solve를 중단할 음수 상태 code.

Solve를 호출한 thread에서 동기적으로 실행되고 어떤 pointer도 보관하지 않는다. Input과 output은 겹치지 않으며 callback은 C++ exception을 ABI 밖으로 전달하면 안 된다. 실패 시 두 output의 내용은 optimizer가 사용하지 않는다.

• Math Engine ownership: argument=borrowed user_data=caller out_value=caller out_max_constraint_violation=caller
• Math Engine nullable: argument=false user_data=true out_value=false out_max_constraint_violation=false
• Math Engine thread_safety: conditional
• Math Engine callback: invocation=synchronous thread=caller retention=none exception=forbidden

typedef math_engine_status_t (*math_engine_vector_objective_f64_fn)(
    const double* argument,
    uint32_t dimension,
    void* user_data,
    double* out_value,
    double* out_max_constraint_violation);

Deterministic projected coordinate search option이다.

typedef struct math_engine_box_optimization_options_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_box_optimization_options_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_BOX_OPTIMIZATION_OPTIONS_VERSION_1=인 option ABI version이다. */
    uint32_t dimension; /**< Argument, lower, upper와 output vector의 공통 positive element 수다. */
    uint32_t flags; /**< Version 1 box-option flag bitset이다. 정의되지 않은 bit는 0이어야 한다. */
    double initial_step_fraction; /**< 각 coordinate box width에 곱하는 finite (0,1] 최초 search step fraction이다. */
    double minimum_step_fraction; /**< 수렴을 선언하는 finite positive 최소 step fraction이며 initial 이하이다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Caller는 모두 0으로 설정해야 하며 nonzero option은 INVALID_ARGUMENT로 거부된다. */
} math_engine_box_optimization_options_f64_t;

Box optimization provenance, residual과 feasibility를 기록한다.

typedef struct math_engine_box_optimization_result_f64 {
    uint32_t struct_size; /**< Caller가 =sizeof(math_engine_box_optimization_result_f64_t)=로 설정하는 byte 크기다. */
    uint32_t struct_version; /**< =MATH_ENGINE_BOX_OPTIMIZATION_RESULT_VERSION_1=인 result ABI version이다. */
    uint32_t mode; /**< Search/quality policy를 선택한 =math_engine_mode_t= 값이다. */
    uint32_t quality; /**< Final solution의 algorithm-specific quality class다. */
    uint32_t flags; /**< =MATH_ENGINE_BOX_OPTIMIZATION_RESULT_FLAG_*= bit의 조합이다. */
    uint32_t dimension; /**< 최적화한 argument vector 원소 수다. */
    uint64_t iteration_count; /**< 전체 coordinate sweep/refinement iteration 수다. */
    uint64_t evaluation_count; /**< Vector objective callback을 동기 호출한 총횟수다. */
    uint64_t feasible_evaluation_count; /**< Constraint violation이 tolerance 안이었던 callback 평가 수다. */
    uint64_t workspace_used_bytes; /**< Search가 caller scratch에서 실제 사용한 byte 수다. */
    uint64_t operation_fingerprint; /**< Bounds, option, mode와 deterministic visit 순서를 결합한 fingerprint다. */
    double value; /**< Final argument에서 objective가 반환한 finite scalar value다. */
    double residual; /**< 마지막 accepted coordinate improvement 또는 convergence residual이다. */
    double max_constraint_violation; /**< Final argument에서 callback이 보고한 finite nonnegative 최대 제약 위반이다. */
    uint64_t reserved[2]; /**< 향후 ABI 확장용 두 slot이다. Caller는 호출 전에 모두 0으로 설정해야 하고 producer도 0을 기록한다. Nonzero storage는 INVALID_ARGUMENT로 거부된다. */
} math_engine_box_optimization_result_f64_t;

math_engine_box_optimization_options_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_BOX_OPTIMIZATION_OPTIONS_VERSION_1 UINT32_C(1)

같은 ABI·input·mode에서 coordinate 방문과 tie-break 순서가 재현됨을 나타낸다.

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

최종 argument의 maximum constraint violation이 context tolerance 안임을 나타낸다.

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

Initial coordinate search 뒤 더 작은 step으로 refinement를 수행했음을 나타낸다.

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

Caller의 initial argument를 검증해 첫 search point로 사용했음을 나타낸다.

#define MATH_ENGINE_BOX_OPTIMIZATION_RESULT_FLAG_WARM_STARTED \
    (UINT32_C(1) << 3u)

math_engine_box_optimization_result_f64_t 의 최초 안정 ABI version이다.

#define MATH_ENGINE_BOX_OPTIMIZATION_RESULT_VERSION_1 UINT32_C(1)

닫힌 구간에서 목적 함수의 국소 최솟값을 황금분할 탐색으로 구한다.

• 매개변수 objective: 목적 함수 callback. NULL이면 오류다.
• 매개변수 user_data: callback에 그대로 전달하는 caller-owned pointer. NULL이어도 된다.
• 매개변수 lower_bound: 닫힌 탐색 구간의 유한한 하한.
• 매개변수 upper_bound: 닫힌 탐색 구간의 유한한 상한. 하한보다 커야 한다.
• 매개변수 context: tolerance, iteration/evaluation budget과 cancellation을 제공하는 borrowed context.
• 매개변수 out_result: 성공 시 결과를 받는 caller-owned storage. NULL이면 오류다.
• 반환: 수렴하면 MATH_ENGINE_STATUS_OK, 예산 소진이나 취소를 포함한 실패이면 음수 상태 code.

구간 폭이 absolute + relative * max(abs(lower), abs(upper), 1) 이하이면 수렴으로 판정한다. 목적 함수 값은 finite여야 한다. 실패하면 out_result 를 변경하지 않는다. 목적 함수가 단봉(unimodal)이라는 전제에서 구간 안의 국소 최솟값을 찾는다.

• Math Engine ownership: objective=borrowed user_data=caller context=borrowed out_result=caller
• Math Engine nullable: objective=false user_data=true context=false out_result=false
• Math Engine thread_safety: conditional

MATH_ENGINE_API math_engine_status_t math_engine_minimize_bounded_f64(
    math_engine_objective_f64_fn objective,
    void* user_data,
    double lower_bound,
    double upper_bound,
    const math_engine_context_t* context,
    math_engine_optimization_result_f64_t* out_result);

Box optimization option을 안정된 기본값으로 초기화한다.

• 매개변수 dimension: 최적화 vector 차원. 1 이상이어야 한다.
• 매개변수 out_options: 성공 시 size/version과 기본값을 받는 caller-owned storage.
• 반환: 유효한 차원이면 OK, 잘못된 인자면 해당 음수 상태 code이며 실패하면 output을 보존한다.
• Math Engine ownership: out_options=caller
• Math Engine nullable: out_options=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_box_optimization_options_f64_init(
    uint32_t dimension,
    math_engine_box_optimization_options_f64_t* out_options);

Box optimization result의 size/version 계약을 초기화한다.

• 매개변수 out_result: 초기화할 caller-owned result storage.
• 반환: 유효한 storage면 OK, null이면 INVALID_ARGUMENT이며 실패하면 output을 보존한다.
• Math Engine ownership: out_result=caller
• Math Engine nullable: out_result=false
• Math Engine thread_safety: safe

MATH_ENGINE_API math_engine_status_t math_engine_box_optimization_result_f64_init(
    math_engine_box_optimization_result_f64_t* out_result);

지정 dimension에 필요한 caller scratch byte 수를 반환한다.

• 매개변수 dimension: 최적화 vector 차원. 1 이상이어야 한다.
• 매개변수 out_size: 성공 시 필요한 scratch 크기를 byte 단위로 받는 caller-owned storage.
• 반환: 크기를 계산하면 OK, 범위를 벗어나거나 overflow하면 해당 음수 상태 code이며 실패하면 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_minimize_box_workspace_size_f64(
    uint32_t dimension,
    uint64_t* out_size);

닫힌 component-wise bound 안에서 projected coordinate search를 수행한다.

• 매개변수 objective: 같은 thread에서 동기 호출하고 저장하지 않는 borrowed callback.
• 매개변수 user_data: callback lifetime 동안 caller가 소유하는 nullable pointer.
• 매개변수 options: dimension과 refinement fraction을 지정하는 borrowed option.
• 매개변수 lower_bounds: dimension개 유한 lower bound.
• 매개변수 upper_bounds: dimension개 유한 upper bound.
• 매개변수 warm_start: nullable dimension개 초기값. Bound로 projection한다.
• 매개변수 context: mode, tolerance, iteration/evaluation budget과 cancellation.
• 매개변수 workspace: input/output과 겹치지 않는 alignof(double) 정렬 scratch.
• 매개변수 out_argument: 성공 시 dimension개 solution을 받는 caller storage.
• 매개변수 out_result: 성공 provenance를 받는 size/version 초기화 storage.
• 반환: 수렴한 feasible solution만 OK다. Infeasible은 DEGENERATE, 예산 소진은 BUDGET_EXHAUSTED이며 모든 실패는 두 output을 보존한다.
• Math Engine ownership: objective=borrowed user_data=caller options=borrowed lower_bounds=borrowed upper_bounds=borrowed warm_start=borrowed context=borrowed workspace=caller out_argument=caller out_result=caller
• Math Engine nullable: objective=false user_data=true options=false lower_bounds=false upper_bounds=false warm_start=true context=false workspace.data=false out_argument=false out_result=false
• Math Engine thread_safety: separate_workspace

MATH_ENGINE_API math_engine_status_t math_engine_minimize_box_f64(
    math_engine_vector_objective_f64_fn objective,
    void* user_data,
    const math_engine_box_optimization_options_f64_t* options,
    const double* lower_bounds,
    const double* upper_bounds,
    const double* warm_start,
    const math_engine_context_t* context,
    math_engine_mutable_byte_span_t workspace,
    double* out_argument,
    math_engine_box_optimization_result_f64_t* out_result);