space-data-module-sdk 0.8.17 → 0.8.18

package/include/orbpro/orbpro_solver_abi.h

@@ -0,0 +1,183 @@
+/* ===========================================================================
+ * SCHEMA-DERIVED ABI CONTRACT.
+ *
+ * Source of truth : schemas/orbpro/Solver.fbs
+ * Contract        : pull/supply maneuver-family solver ABI
+ *
+ * A solver has no propagator import. plugin_solver_next yields a candidate;
+ * the host evaluates it through the selected propagator/objective ports and
+ * returns the answer through plugin_solver_supply.
+ * ===========================================================================
+ */
+
+#ifndef ORBPRO_SOLVER_ABI_H
+#define ORBPRO_SOLVER_ABI_H
+
+#include <stddef.h>
+#include <stdint.h>
+
+#if defined(__cplusplus)
+#define ORBPRO_SOLVER_STATIC_ASSERT(cond, msg) static_assert(cond, msg)
+#else
+#define ORBPRO_SOLVER_STATIC_ASSERT(cond, msg) _Static_assert(cond, msg)
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#define ORBPRO_SOLVER_MAX_DIMENSION 16u
+#define ORBPRO_SOLVER_MAX_JACOBIAN_VALUES 256u
+
+typedef enum {
+  ORBPRO_SOLVER_NEWTON_RAPHSON = 0,
+  ORBPRO_SOLVER_BROYDEN = 1,
+  ORBPRO_SOLVER_MODIFIED_BROYDEN = 2,
+  ORBPRO_SOLVER_SQP = 3,
+} OrbProSolverAlgorithm;
+
+typedef enum {
+  ORBPRO_SOLVER_DIFFERENCE_FORWARD = 0,
+  ORBPRO_SOLVER_DIFFERENCE_CENTRAL = 1,
+  ORBPRO_SOLVER_DIFFERENCE_ANALYTIC_STM = 2,
+} OrbProSolverDifferenceMode;
+
+typedef enum {
+  ORBPRO_SOLVER_STATUS_IDLE = 0,
+  ORBPRO_SOLVER_STATUS_NEEDS_EVALUATION = 1,
+  ORBPRO_SOLVER_STATUS_CONVERGED = 2,
+  ORBPRO_SOLVER_STATUS_INVALID_PROBLEM = 3,
+  ORBPRO_SOLVER_STATUS_EVALUATION_FAILED = 4,
+  ORBPRO_SOLVER_STATUS_SINGULAR_JACOBIAN = 5,
+  ORBPRO_SOLVER_STATUS_BUDGET_EXCEEDED = 6,
+  ORBPRO_SOLVER_STATUS_STALLED = 7,
+  ORBPRO_SOLVER_STATUS_INFEASIBLE = 8,
+} OrbProSolverStatus;
+
+typedef enum {
+  ORBPRO_SOLVER_EVALUATE_VALUES = 0,
+  ORBPRO_SOLVER_EVALUATE_VALUES_AND_JACOBIAN = 1,
+} OrbProSolverEvaluationKind;
+
+typedef struct {
+  uint8_t algorithm;
+  uint8_t difference_mode;
+  uint16_t _reserved0;
+  uint32_t maximum_iterations;
+  uint32_t maximum_evaluations;
+  uint32_t variable_count;
+  uint32_t goal_count;
+  uint32_t equality_constraint_count;
+  uint32_t inequality_constraint_count;
+  double residual_tolerance;
+  double step_tolerance;
+  double constraint_tolerance;
+  double kkt_tolerance;
+} OrbProSolverSettings;
+
+ORBPRO_SOLVER_STATIC_ASSERT(sizeof(OrbProSolverSettings) == 64,
+                            "OrbProSolverSettings must be 64 bytes");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverSettings, variable_count) == 12,
+                            "OrbProSolverSettings.variable_count offset");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverSettings, equality_constraint_count) == 20,
+                            "OrbProSolverSettings.equality_constraint_count offset");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverSettings, residual_tolerance) == 32,
+                            "OrbProSolverSettings.residual_tolerance offset");
+
+typedef struct {
+  uint64_t request_id;
+  uint8_t kind;
+  uint8_t _reserved0[3];
+  uint32_t variable_count;
+  double variables[ORBPRO_SOLVER_MAX_DIMENSION];
+} OrbProSolverEvaluationRequest;
+
+ORBPRO_SOLVER_STATIC_ASSERT(sizeof(OrbProSolverEvaluationRequest) == 144,
+                            "OrbProSolverEvaluationRequest must be 144 bytes");
+
+typedef struct {
+  uint64_t request_id;
+  uint8_t valid;
+  uint8_t _reserved0[3];
+  uint32_t goal_count;
+  uint32_t constraint_count;
+  uint32_t jacobian_rows;
+  uint32_t jacobian_columns;
+  double goals[ORBPRO_SOLVER_MAX_DIMENSION];
+  double objective;
+  double constraints[ORBPRO_SOLVER_MAX_DIMENSION];
+  double jacobian[ORBPRO_SOLVER_MAX_JACOBIAN_VALUES];
+} OrbProSolverEvaluation;
+
+ORBPRO_SOLVER_STATIC_ASSERT(sizeof(OrbProSolverEvaluation) == 2344,
+                            "OrbProSolverEvaluation must be 2344 bytes");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverEvaluation, goals) == 32,
+                            "OrbProSolverEvaluation.goals offset");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverEvaluation, objective) == 160,
+                            "OrbProSolverEvaluation.objective offset");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverEvaluation, constraints) == 168,
+                            "OrbProSolverEvaluation.constraints offset");
+
+typedef struct {
+  uint32_t iteration;
+  uint32_t evaluation_count;
+  uint32_t variable_count;
+  uint32_t goal_count;
+  double variables[ORBPRO_SOLVER_MAX_DIMENSION];
+  double values[ORBPRO_SOLVER_MAX_DIMENSION];
+  double residual_norm;
+  double step_norm;
+  double jacobian_condition;
+  double maximum_constraint_violation;
+  double kkt_residual;
+  uint8_t accepted;
+  uint8_t _reserved0[7];
+} OrbProSolverIteration;
+
+ORBPRO_SOLVER_STATIC_ASSERT(sizeof(OrbProSolverIteration) == 320,
+                            "OrbProSolverIteration must be 320 bytes");
+
+typedef struct {
+  uint8_t status;
+  uint8_t _reserved0[3];
+  uint32_t iteration_count;
+  uint32_t evaluation_count;
+  uint32_t variable_count;
+  uint32_t value_count;
+  double variables[ORBPRO_SOLVER_MAX_DIMENSION];
+  double values[ORBPRO_SOLVER_MAX_DIMENSION];
+  double objective;
+  double residual_norm;
+  double maximum_constraint_violation;
+  double kkt_residual;
+} OrbProSolverResult;
+
+ORBPRO_SOLVER_STATIC_ASSERT(sizeof(OrbProSolverResult) == 312,
+                            "OrbProSolverResult must be 312 bytes");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverResult, variables) == 24,
+                            "OrbProSolverResult.variables offset");
+ORBPRO_SOLVER_STATIC_ASSERT(offsetof(OrbProSolverResult, objective) == 280,
+                            "OrbProSolverResult.objective offset");
+
+static inline void orbpro_solver_zero(void* value, size_t size) {
+  size_t index;
+  for (index = 0; index < size; ++index) ((uint8_t*)value)[index] = 0;
+}
+
+int32_t plugin_solver_configure(const OrbProSolverSettings* settings,
+                                const double* initial_variables,
+                                const double* lower_bounds,
+                                const double* upper_bounds,
+                                const double* desired_values,
+                                const double* perturbations);
+int32_t plugin_solver_begin(void);
+int32_t plugin_solver_next(OrbProSolverEvaluationRequest* request);
+int32_t plugin_solver_supply(const OrbProSolverEvaluation* evaluation);
+int32_t plugin_solver_result(OrbProSolverResult* result);
+int32_t plugin_solver_iteration(uint32_t index, OrbProSolverIteration* result);
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* ORBPRO_SOLVER_ABI_H */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "space-data-module-sdk",
-  "version": "0.8.17",
+  "version": "0.8.18",
   "license": "Apache-2.0",
   "description": "Module SDK for building, validating, signing, and deploying WebAssembly modules on the Space Data Network.",
   "type": "module",
@@ -125,7 +125,7 @@
     "flatsql": "^2.0.0",
     "hd-wallet-wasm": "2.0.28",
     "sdn-emception": "1.0.0",
-    "spacedatastandards.org": "1.203.0"
+    "spacedatastandards.org": "1.206.0"
   },
   "devDependencies": {
     "esbuild": "^0.28.0",

package/schemas/orbpro/Solver.fbs

@@ -0,0 +1,115 @@
+include "Propagator.fbs";
+
+namespace orbpro.solver;
+
+// Pull/supply solver protocol. The solver never imports a propagator or an
+// objective function: it asks the host for one evaluation at a candidate
+// control vector, and the host routes that request to the selected ports.
+
+enum SolverAlgorithm : ubyte (abi, abi_c_name: "OrbProSolverAlgorithm", abi_c_prefix: "ORBPRO_SOLVER_") {
+  NEWTON_RAPHSON = 0,
+  BROYDEN = 1,
+  MODIFIED_BROYDEN = 2,
+  SQP = 3
+}
+
+enum DifferenceMode : ubyte (abi, abi_c_name: "OrbProSolverDifferenceMode", abi_c_prefix: "ORBPRO_SOLVER_DIFFERENCE_") {
+  FORWARD = 0,
+  CENTRAL = 1,
+  ANALYTIC_STM = 2
+}
+
+enum SolverStatus : ubyte (abi, abi_c_name: "OrbProSolverStatus", abi_c_prefix: "ORBPRO_SOLVER_STATUS_") {
+  IDLE = 0,
+  NEEDS_EVALUATION = 1,
+  CONVERGED = 2,
+  INVALID_PROBLEM = 3,
+  EVALUATION_FAILED = 4,
+  SINGULAR_JACOBIAN = 5,
+  BUDGET_EXCEEDED = 6,
+  STALLED = 7,
+  INFEASIBLE = 8
+}
+
+enum EvaluationKind : ubyte (abi, abi_c_name: "OrbProSolverEvaluationKind", abi_c_prefix: "ORBPRO_SOLVER_EVALUATE_") {
+  VALUES = 0,
+  VALUES_AND_JACOBIAN = 1
+}
+
+/// Fixed ABI limit. A larger search problem travels as $SLP through the
+/// command surface; the direct pull/supply surface intentionally stays small.
+struct SolverSettings (abi, abi_c_name: "OrbProSolverSettings", abi_c_helper_prefix: "orbpro_solver_settings_") {
+  algorithm: SolverAlgorithm;
+  difference_mode: DifferenceMode;
+  _reserved0: ushort;
+  maximum_iterations: uint;
+  maximum_evaluations: uint;
+  variable_count: uint;
+  goal_count: uint;
+  equality_constraint_count: uint;
+  inequality_constraint_count: uint;
+  residual_tolerance: double;
+  step_tolerance: double;
+  constraint_tolerance: double;
+  kkt_tolerance: double;
+}
+
+/// Candidate that must be evaluated by the consumer-selected propagator and
+/// objective ports.
+struct SolverEvaluationRequest (abi, abi_c_name: "OrbProSolverEvaluationRequest", abi_c_helper_prefix: "orbpro_solver_request_") {
+  request_id: ulong;
+  kind: EvaluationKind;
+  _reserved0: [ubyte:3];
+  variable_count: uint;
+  variables: [double:16];
+}
+
+/// Values supplied after one request. Goals are the achieved values for a
+/// target problem. For an optimization problem, objective and constraints are
+/// also populated. The Jacobian is row-major with at most 16 by 16 entries.
+struct SolverEvaluation (abi, abi_c_name: "OrbProSolverEvaluation", abi_c_helper_prefix: "orbpro_solver_evaluation_") {
+  request_id: ulong;
+  valid: ubyte;
+  _reserved0: [ubyte:3];
+  goal_count: uint;
+  constraint_count: uint;
+  jacobian_rows: uint;
+  jacobian_columns: uint;
+  goals: [double:16];
+  objective: double;
+  constraints: [double:16];
+  jacobian: [double:256];
+}
+
+struct SolverIteration (abi, abi_c_name: "OrbProSolverIteration", abi_c_helper_prefix: "orbpro_solver_iteration_") {
+  iteration: uint;
+  evaluation_count: uint;
+  variable_count: uint;
+  goal_count: uint;
+  variables: [double:16];
+  values: [double:16];
+  residual_norm: double;
+  step_norm: double;
+  jacobian_condition: double;
+  maximum_constraint_violation: double;
+  kkt_residual: double;
+  accepted: ubyte;
+  _reserved0: [ubyte:7];
+}
+
+struct SolverResult (abi, abi_c_name: "OrbProSolverResult", abi_c_helper_prefix: "orbpro_solver_result_") {
+  status: SolverStatus;
+  _reserved0: [ubyte:3];
+  iteration_count: uint;
+  evaluation_count: uint;
+  variable_count: uint;
+  value_count: uint;
+  variables: [double:16];
+  values: [double:16];
+  objective: double;
+  residual_norm: double;
+  maximum_constraint_violation: double;
+  kkt_residual: double;
+}
+
+root_type SolverResult;