3 Reference

9.2

Racket

3 Reference🔗ℹ

3.1 High-level API🔗ℹ

package: scs

The scs module re-exports the matrix builders under the scs: prefix together with the cone, settings, and solve API.

3.1.1 Matrices and vectors🔗ℹ

procedure
(scs:matrix nrow ncol val ...) → any/c
  nrow : exact-nonnegative-integer?
  ncol : exact-nonnegative-integer?
  val : real?

Builds an nrow×ncol CSC matrix from a dense, row-major sequence of vals (there must be (* nrow ncol) of them). Exact zeros are dropped from the sparse representation.

procedure
(scs:sparse-matrix nrow ncol triple ...) → any/c
  nrow : exact-nonnegative-integer?
  ncol : exact-nonnegative-integer?
   triple :
(list/c exact-nonnegative-integer?
        exact-nonnegative-integer?
        real?)

Builds an nrow×ncol CSC matrix from explicit (list row col value) triples. For a quadratic objective P, supply only the upper-triangular entries.

procedure
(scs:matrix-ref m i j) → real?
  m : any/c
  i : exact-nonnegative-integer?
  j : exact-nonnegative-integer?

Returns entry (i ,j), or 0.0 if it is absent from the sparse representation.

procedure
(scs:matrix-nnz m) → exact-nonnegative-integer?
  m : any/c
procedure
(scs:matrix-p->vector m) → (vectorof exact-integer?)
  m : any/c
procedure
(scs:matrix-x->vector m) → (vectorof real?)
  m : any/c
procedure
(scs:matrix-i->vector m) → (vectorof exact-integer?)
  m : any/c

Inspect a CSC matrix: its non-zero count and its column-pointer, value, and row-index arrays.

procedure
(scs:vector->float-ptr v) → cpointer?
  v : (or/c (vectorof real?) (listof real?))
procedure
(scs:float-ptr->vector ptr len) → (vectorof real?)
  ptr : cpointer?
  len : exact-nonnegative-integer?

Low-level helpers to copy a Racket sequence into a freshly allocated scs_float array and to read one back. Used when driving the scs/foreign layer directly.

3.1.2 Cones🔗ℹ

procedure
(make-cone [ #:zero z
#:positive l
#:box-lower box-lower
#:box-upper box-upper
#:soc soc
#:psd psd
#:complex-psd complex-psd
#:exp-primal exp-primal
#:exp-dual exp-dual
#:power power]) → scs-cone?
  z : exact-nonnegative-integer? = 0
  l : exact-nonnegative-integer? = 0
  box-lower : (listof real?) = '()
  box-upper : (listof real?) = '()
  soc : (listof exact-nonnegative-integer?) = '()
  psd : (listof exact-nonnegative-integer?) = '()
  complex-psd : (listof exact-nonnegative-integer?) = '()
  exp-primal : exact-nonnegative-integer? = 0
  exp-dual : exact-nonnegative-integer? = 0
  power : (listof real?) = '()

Assembles a cone specification. The keywords correspond to the primitive cones in the order the rows of A must follow; see Cones. box-lower and box-upper must have equal length.

3.1.3 Settings🔗ℹ

procedure
(make-settings [ #:verbose? verbose?
#:normalize? normalize?
#:max-iters max-iters
#:eps-abs eps-abs
#:eps-rel eps-rel
#:eps-infeas eps-infeas
#:time-limit-secs time-limit-secs
#:warm-start? warm-start?])
→ scs-settings?
  verbose? : boolean? = #f
  normalize? : boolean? = #t
  max-iters : (or/c #f exact-positive-integer?) = #f
  eps-abs : (or/c #f real?) = #f
  eps-rel : (or/c #f real?) = #f
  eps-infeas : (or/c #f real?) = #f
  time-limit-secs : (or/c #f real?) = #f
  warm-start? : boolean? = #f

Returns a settings value initialized to SCS’s defaults, with the supplied keywords overridden. A #f override leaves the SCS default in place. See the settings reference.

3.1.4 Solving🔗ℹ

procedure
(solve #:A A
#:b b
#:c c
#:cone cone
[ #:P P
#:settings settings
#:indirect? indirect?
#:warm-start warm]) → scs-result?
  A : any/c
  b : (or/c (vectorof real?) (listof real?))
  c : (or/c (vectorof real?) (listof real?))
  cone : scs-cone?
  P : (or/c any/c #f) = #f
  settings : (or/c scs-settings? #f) = #f
  indirect? : boolean? = #f
  warm : exact-integer? = 0

Solves the cone program described by A, b, c, the optional quadratic objective P, and cone. With #:indirect? #t the indirect (conjugate-gradient) linear-system solver is used. The workspace is reclaimed by the garbage collector.

struct
(struct scs-result ( exit-flag
status
status-val
x
y
s
pobj
dobj
gap
iter
solve-time
setup-time)
    #:transparent)
  exit-flag : exact-integer?
  status : string?
  status-val : exact-integer?
  x : (vectorof real?)
  y : (vectorof real?)
  s : (vectorof real?)
  pobj : real?
  dobj : real?
  gap : real?
  iter : exact-integer?
  solve-time : real?
  setup-time : real?

The result of a solve. x, y, and s are the primal, dual, and slack vectors; status is the status string and status-val/exit-flag the integer exit code (see the exit-flag reference).

procedure
(solved? r) → boolean?
r : scs-result?

Returns #t when r solved to tolerance (exit flag 1).

procedure
(scs-version) → string?

The version string of the underlying SCS C library.

3.2 Contracted FFI layer🔗ℹ

(require scs/foreign)

package: scs

scs/foreign exposes the SCS cstructs and a contracted view of the C entry points, for callers building problems by hand or driving warm-started re-solves. The cstructs (make-scs-matrix, make-scs-data, make-scs-cone, make-scs-solution, new-scs-settings, new-scs-info) and their accessors are re-exported from the raw layer; make-cone and make-settings from scs build the cone and settings structs ergonomically.

3.2.1 Cstructs🔗ℹ

The cstructs mirror the SCS C API (scs.h, SCS 3.2.11) one-to-one. Each provides a positional constructor (make-_), a predicate, and field accessors/mutators; the two configuration structs additionally provide a keyword constructor (new-_) that defaults every field to a type-appropriate zero. Most callers should prefer make-cone, make-settings, and solve from scs and reach for these only when driving the C API directly. Pointer fields store raw addresses, so a value placed in one must be kept alive with retain! for as long as the owning struct is live.

procedure
(make-scs-matrix x i p m n) → scs-matrix?
  x : (or/c cpointer? #f)
  i : (or/c cpointer? #f)
  p : (or/c cpointer? #f)
  m : exact-integer?
  n : exact-integer?
procedure
(scs-matrix? v) → boolean?
  v : any/c

An ScsMatrix: an m×n sparse matrix in CSC form with value array x, row-index array i, and column-pointer array p.

procedure
(make-scs-data m n A P b c) → scs-data?
  m : exact-integer?
  n : exact-integer?
  A : scs-matrix?
  P : (or/c scs-matrix? cpointer? #f)
  b : (or/c cpointer? #f)
  c : (or/c cpointer? #f)
procedure
(scs-data? v) → boolean?
  v : any/c

An ScsData: the constraint matrix A (m×n), the optional quadratic-objective matrix P (n×n, upper triangle, or #f), and the dense right-hand sides b and c.

procedure
(make-scs-cone z
l
bu
bl
bsize
q
qsize
s
ssize
cs
cssize
ep
ed
p
psize) → scs-cone?
  z : exact-integer?
  l : exact-integer?
  bu : (or/c cpointer? #f)
  bl : (or/c cpointer? #f)
  bsize : exact-integer?
  q : (or/c cpointer? #f)
  qsize : exact-integer?
  s : (or/c cpointer? #f)
  ssize : exact-integer?
  cs : (or/c cpointer? #f)
  cssize : exact-integer?
  ep : exact-integer?
  ed : exact-integer?
  p : (or/c cpointer? #f)
  psize : exact-integer?
procedure
(scs-cone? v) → boolean?
  v : any/c

An ScsCone, the low-level form of make-cone: the zero cone z, positive cone l, box cone (bu/bl, length bsize), second-order cones q (count qsize), PSD cones s (count ssize), complex-PSD cones cs (count cssize), exponential cones ep/ed, and power cones p (count psize). See Cones for the required row ordering.

procedure
(make-scs-solution x y s) → scs-solution?
  x : (or/c cpointer? #f)
  y : (or/c cpointer? #f)
  s : (or/c cpointer? #f)
procedure
(scs-solution? v) → boolean?
  v : any/c

An ScsSolution: the dense primal (x), dual (y), and slack (s) arrays that scs-solve fills in.

procedure
(new-scs-settings
[ #:normalize normalize
#:scale scale
#:adaptive_scale adaptive_scale
#:rho_x rho_x
#:max_iters max_iters
#:eps_abs eps_abs
#:eps_rel eps_rel
#:eps_infeas eps_infeas
#:alpha alpha
#:time_limit_secs time_limit_secs
#:verbose verbose
#:warm_start warm_start
#:acceleration_lookback acceleration_lookback
#:acceleration_interval acceleration_interval
#:write_data_filename write_data_filename
#:log_csv_filename log_csv_filename])
→ scs-settings?
  normalize : exact-integer? = 0
  scale : real? = 0.0
  adaptive_scale : exact-integer? = 0
  rho_x : real? = 0.0
  max_iters : exact-integer? = 0
  eps_abs : real? = 0.0
  eps_rel : real? = 0.0
  eps_infeas : real? = 0.0
  alpha : real? = 0.0
  time_limit_secs : real? = 0.0
  verbose : exact-integer? = 0
  warm_start : exact-integer? = 0
  acceleration_lookback : exact-integer? = 0
  acceleration_interval : exact-integer? = 0
  write_data_filename : (or/c string? #f) = #f
  log_csv_filename : (or/c string? #f) = #f
procedure
(scs-settings? v) → boolean?
  v : any/c

An ScsSettings, the low-level form of make-settings. Each keyword mirrors the correspondingly named scs.h field and defaults to a type-appropriate zero; pass the result through scs-set-default-settings to install SCS’s real defaults before overriding individual fields. See the settings reference.

procedure
(new-scs-info) → scs-info?
procedure
(scs-info? v) → boolean?
v : any/c

An ScsInfo result record, normally constructed with no arguments to receive the outcome of scs-solve. Every scs.h field (e.g. iter, status, status_val, pobj, dobj, gap, solve_time, setup_time) is also available as an optional keyword defaulting to a type-appropriate zero, and as a field accessor.

3.2.2 C entry points🔗ℹ

procedure
(scs-init d k stgs) → cpointer?
  d : scs-data?
  k : scs-cone?
  stgs : scs-settings?
procedure
(scs-solve work sol info warm) → exact-integer?
  work : cpointer?
  sol : scs-solution?
  info : scs-info?
  warm : exact-integer?
procedure
(scs-update work b c) → exact-integer?
  work : cpointer?
  b : cpointer?
  c : cpointer?

Initialize a workspace, solve into sol/info (pass 1 for warm to warm start), and update the workspace’s b/c for a re-solve. The /indirect variants (scs-init/indirect, scs-solve/indirect, scs-update/indirect) use libscsindir. The workspace is GC-reclaimed via a finalizer.

procedure
(scs-init/indirect d k stgs) → cpointer?
  d : scs-data?
  k : scs-cone?
  stgs : scs-settings?
procedure
(scs-solve/indirect work sol info warm) → exact-integer?
  work : cpointer?
  sol : scs-solution?
  info : scs-info?
  warm : exact-integer?
procedure
(scs-update/indirect work b c) → exact-integer?
  work : cpointer?
  b : cpointer?
  c : cpointer?

The indirect/conjugate-gradient counterparts of scs-init, scs-solve, and scs-update, bound against libscsindir.

procedure
(scs-set-default-settings stgs) → void?
stgs : scs-settings?

Populates stgs with the SCS defaults in place.

procedure
(retain! owner thing ...) → any/c
owner : any/c
thing : any/c

Records things in a weak table keyed by owner and returns owner, keeping FFI backing buffers alive as long as the struct that points at them. Use it whenever you store a freshly allocated buffer into a cstruct pointer field.

3.2.3 Deterministic release🔗ℹ

(require (submod scs/foreign unsafe))

(require (submod scs/foreign unsafe)) additionally provides scs-finish and scs-finish/indirect for callers that need to release a workspace eagerly rather than waiting for the collector.

procedure
(scs-finish work) → void?
work : cpointer?
procedure
(scs-finish/indirect work) → void?
work : cpointer?

Free the SCS workspace work returned by scs-init (resp. scs-init/indirect). A workspace is also finalized automatically when it becomes unreachable, so calling these is only necessary to release the native memory at a deterministic point.

3.3 Raw FFI layer🔗ℹ

(require scs/foreign/raw)

package: scs

scs/foreign/raw is the direct, uncontracted binding to the SCS C API. It provides the define-scs / define-scs-indirect FFI definers, the _scs-int and _scs-float C type aliases, the cstructs, retain!, and the solver functions without contracts. Prefer scs or scs/foreign unless you are extending the bindings.

syntax
(define-scs id type-expr option ...)
syntax
(define-scs-indirect id type-expr option ...)

Bind id to the SCS C function of the same name (hyphens mapped to underscores) with the _fun type type-expr, against libscsdir and libscsindir respectively. These are define-ffi-definer instances, so each option is a definer keyword clause such as #:wrap or #:c-id.

value
_scs-int : ctype?
value
_scs-float : ctype?

The C type aliases for SCS’s scs_int and scs_float. In the nixpkgs build these are _int (32-bit) and _double; aliasing them keeps a future DLONG/SFLOAT build a one-line change.