cadical 0.9.0

data/ext/cadical/cadical_ext.c

@@ -0,0 +1,778 @@
+/* Ruby C extension wrapping the CaDiCaL SAT solver's C API.
+ *
+ * Decide whether a set of boolean clauses can all be true at once, and if so produce a
+ * satisfying assignment. */
+
+#include <ruby.h>
+#include <ruby/thread.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <string.h>
+
+#include "ccadical.h"
+
+/*
+ * Document-class: CaDiCaL
+ *
+ * A Ruby binding for the {CaDiCaL}[https://github.com/arminbiere/cadical] SAT solver.
+ *
+ * Decide whether a set of boolean clauses can all be true at once, and if so produce a
+ * satisfying assignment.
+ *
+ * This is a thin, general-purpose binding over CaDiCaL's C API (ccadical_*).
+ *
+ * Typical use:
+ *
+ *   s = CaDiCaL.new
+ *   x = s.new_var
+ *   y = s.new_var
+ *   s.add(x, y)    # (x \/ y)
+ *   s.add(-x, y)   # (!x \/ y)
+ *   s.solve        # => :sat
+ *   s.true?(y)     # => true
+ *
+ * - Make variables with #new_var (each is just an Integer).
+ * - A literal is a variable or its negation: +v+ means "variable +v+ is true", +-v+ means false.
+ * - A clause is a list of literals; add it as a constraint with #add.
+ * - #solve reports whether the clauses can all be satisfied: +:sat+ if so, +:unsat+ if not.
+ * - After +:sat+, read a variable's assigned truth value with #true?.
+ */
+
+static ID id_sat, id_unsat, id_unknown, id_call;
+
+/* ccadical_solve returns the IPASIR status codes: 10 = SATISFIABLE, 20 = UNSATISFIABLE,
+ * 0 = UNKNOWN. The C API does not give them names, so the constants live here. */
+static VALUE result_sym(int r) {
+  return ID2SYM(r == 10 ? id_sat : r == 20 ? id_unsat : id_unknown);
+}
+
+/* --- wrapper struct --- */
+
+/* The wrapper struct for a CCaDiCaL handle. */
+typedef struct {
+  CCaDiCaL *solver;
+  VALUE on_terminate; /* proc or Qnil */
+  VALUE on_learn;     /* proc or Qnil */
+  VALUE pending_exc;  /* exception from a callback, to re-raise after solve; or Qnil */
+  FILE *proof_file;   /* open proof-trace file we own, or NULL */
+  int state;          /* current solver state (mirrors cadical.hpp's State enum). get_cad
+                       * checks each method's require() contract against it; the mutators
+                       * update it. Turns CaDiCaL's fatal "wrong state" aborts into exceptions. */
+} cadical_t;
+
+static void cad_mark(void *p) {
+  cadical_t *c = p;
+  rb_gc_mark(c->on_terminate);
+  rb_gc_mark(c->on_learn);
+  rb_gc_mark(c->pending_exc);
+}
+
+static void cad_free(void *p) {
+  cadical_t *c = p;
+  if (c->proof_file) fclose(c->proof_file);
+  if (c->solver) ccadical_release(c->solver);
+  xfree(c);
+}
+
+static size_t cad_memsize(const void *p) {
+  (void)p;
+  return sizeof(cadical_t);
+}
+
+static const rb_data_type_t cadical_type = {
+    "CaDiCaL",
+    {cad_mark, cad_free, cad_memsize},
+    NULL,
+    NULL,
+    RUBY_TYPED_FREE_IMMEDIATELY,
+};
+
+/* Solver states we can observe from Ruby, a subset of cadical.hpp's State enum with the same
+ * bit values. We always terminate clauses, so the transient ADDING state is never left set
+ * between calls; SOLVING / INITIALIZING / DELETING are likewise unobservable. Hence for us
+ * VALID == READY, and every method's require() contract is one of the masks below. */
+enum {
+  CONFIGURING = 2, STEADY = 4, SATISFIED = 32, UNSATISFIED = 64, INCONCLUSIVE = 256
+};
+#define SOLVED (SATISFIED | UNSATISFIED | INCONCLUSIVE)
+#define READY (CONFIGURING | STEADY | SOLVED)
+
+static const char *state_name(int s) {
+  switch (s) {
+  case CONFIGURING: return "configuring";
+  case STEADY: return "steady";
+  case SATISFIED: return "satisfied";
+  case UNSATISFIED: return "unsatisfied";
+  case INCONCLUSIVE: return "inconclusive";
+  default: return "invalid";
+  }
+}
+
+/* Fetch the solver, checking it is live and in one of the +allowed+ states (the method's
+ * require() contract). Raising here turns CaDiCaL's fatal state aborts into Ruby exceptions. */
+static cadical_t *get_cad(VALUE self, int allowed) {
+  cadical_t *c;
+  TypedData_Get_Struct(self, cadical_t, &cadical_type, c);
+  if (!c->solver) rb_raise(rb_eRuntimeError, "CaDiCaL already released");
+  if (!(c->state & allowed))
+    rb_raise(rb_eRuntimeError, "CaDiCaL: operation not allowed in the '%s' state", state_name(c->state));
+  return c;
+}
+
+/* Record the state a call transitions to (cadical.hpp's 'ensure' postcondition). */
+static void ensure(cadical_t *c, int state) { c->state = state; }
+
+static VALUE cad_alloc(VALUE klass) {
+  cadical_t *c;
+  VALUE obj = TypedData_Make_Struct(klass, cadical_t, &cadical_type, c);
+  c->solver = ccadical_init();
+  c->on_terminate = Qnil;
+  c->on_learn = Qnil;
+  c->pending_exc = Qnil;
+  c->proof_file = NULL;
+  c->state = CONFIGURING;
+  return obj;
+}
+
+/*
+ * call-seq:
+ *   solver.release -> nil
+ *
+ * Release the solver and its resources now (instead of at GC); the object is unusable
+ * afterwards.
+ */
+static VALUE cad_release(VALUE self) {
+  cadical_t *c = get_cad(self, READY);
+  if (c->proof_file) {
+    fclose(c->proof_file);
+    c->proof_file = NULL;
+  }
+  ccadical_release(c->solver);
+  c->solver = NULL;
+  return Qnil;
+}
+
+/* --- clauses / assumptions / constraints --- */
+
+/*
+ * call-seq:
+ *   solver.add(*lits) -> self
+ *
+ * Add a permanent clause: the disjunction of the given literals.
+ *
+ * Unlike the C API you need not add the terminating 0, it is appended for you. With no
+ * literals it adds the empty clause (an unsatisfiable formula).
+ */
+static VALUE cad_add(int argc, VALUE *argv, VALUE self) {
+  cadical_t *c = get_cad(self, READY);
+  int i;
+  for (i = 0; i < argc; i++) ccadical_add(c->solver, NUM2INT(argv[i]));
+  ccadical_add(c->solver, 0);
+  ensure(c, STEADY); /* adding a clause leaves the SATISFIED / UNSATISFIED state */
+  return self;
+}
+
+/*
+ * call-seq:
+ *   solver.assume(lit) -> self
+ *
+ * Assume valid non-zero literal +lit+ for next call to #solve. These assumptions are reset
+ * after the call to #solve as well as after returning from #simplify.
+ *
+ * See #failed.
+ */
+static VALUE cad_assume(VALUE self, VALUE lit) {
+  cadical_t *c = get_cad(self, READY);
+  ccadical_assume(c->solver, NUM2INT(lit));
+  ensure(c, STEADY);
+  return self;
+}
+
+/*
+ * call-seq:
+ *   solver.constrain(*lits) -> self
+ *
+ * Same functionality as #add, but the clause only exists for the next call to #solve (same
+ * lifetime as assumptions). Only one constraint may exist at a time. A new constraint
+ * replaces the old.
+ *
+ * See #constraint_failed?.
+ */
+static VALUE cad_constrain(int argc, VALUE *argv, VALUE self) {
+  cadical_t *c = get_cad(self, READY);
+  int i;
+  for (i = 0; i < argc; i++) ccadical_constrain(c->solver, NUM2INT(argv[i]));
+  ccadical_constrain(c->solver, 0);
+  ensure(c, STEADY);
+  return self;
+}
+
+/* --- solving --- */
+
+/* Re-raise an exception deferred from a callback during the last solve/simplify. */
+static void reraise_pending(cadical_t *c) {
+  if (!NIL_P(c->pending_exc)) {
+    VALUE e = c->pending_exc;
+    c->pending_exc = Qnil;
+    rb_exc_raise(e);
+  }
+}
+
+/* #solve / #simplify run the (possibly long) search with the GVL released, so other Ruby
+ * threads keep running. The terminate/learn callbacks re-acquire the GVL (see below). */
+struct solve_call {
+  CCaDiCaL *solver;
+  int result;
+};
+
+static void *do_solve(void *p) {
+  struct solve_call *a = p;
+  a->result = ccadical_solve(a->solver);
+  return NULL;
+}
+
+static void *do_simplify(void *p) {
+  struct solve_call *a = p;
+  a->result = ccadical_simplify(a->solver);
+  return NULL;
+}
+
+/* Unblock a GVL-released search if the calling thread is interrupted (e.g. Thread#kill):
+ * ccadical_terminate stops the search asynchronously, as the C API allows. */
+static void unblock_solve(void *p) {
+  struct solve_call *a = p;
+  ccadical_terminate(a->solver);
+}
+
+/*
+ * call-seq:
+ *   solver.solve -> :sat or :unsat or :unknown
+ *
+ * Try to solve the current formula. Returns +:sat+ (satisfiable), +:unsat+ (unsatisfiable),
+ * or +:unknown+ (limit reached or interrupted through #terminate).
+ */
+static VALUE cad_solve(VALUE self) {
+  cadical_t *c = get_cad(self, READY);
+  struct solve_call a = { c->solver, 0 };
+  rb_thread_call_without_gvl(do_solve, &a, unblock_solve, &a);
+  ensure(c, a.result == 10 ? SATISFIED : a.result == 20 ? UNSATISFIED : INCONCLUSIVE);
+  reraise_pending(c);
+  return result_sym(a.result);
+}
+
+/*
+ * call-seq:
+ *   solver.simplify -> :sat or :unsat or :unknown
+ *
+ * This function executes preprocessing rounds. It is similar to #solve except that no CDCL nor local search, nor
+ * lucky phases are executed. The result values are also the same: +:sat+, +:unsat+, or
+ * +:unknown+.
+ *
+ * As #solve it resets current assumptions and limits before returning.
+ */
+static VALUE cad_simplify(VALUE self) {
+  cadical_t *c = get_cad(self, READY);
+  struct solve_call a = { c->solver, 0 };
+  rb_thread_call_without_gvl(do_simplify, &a, unblock_solve, &a);
+  ensure(c, a.result == 10 ? SATISFIED : a.result == 20 ? UNSATISFIED : INCONCLUSIVE);
+  reraise_pending(c);
+  return result_sym(a.result);
+}
+
+/*
+ * call-seq:
+ *   solver.val(lit) -> integer
+ *
+ * Get the value of a valid non-zero literal +lit+. This follows the IPASIR semantics which
+ * says to return +lit+ if +lit+ is assigned to true and +-lit+ if +lit+ is assigned to false.
+ * This has the consequence that the returned literal is always assigned to true and thus might
+ * be a bit confusing. To avoid the headache of these semantics (which we unfortunately should
+ * follow to be compatible with IPASIR) the user can simply use positive variable indices
+ * instead of literals. Then the returned integer is negative if the variable is assigned to
+ * false and positive if it is assigned to true.
+ *
+ * Raises RuntimeError unless the last #solve returned +:sat+.
+ */
+static VALUE cad_val(VALUE self, VALUE lit) {
+  return INT2NUM(ccadical_val(get_cad(self, SATISFIED)->solver, NUM2INT(lit)));
+}
+
+/*
+ * call-seq:
+ *   solver.true?(lit) -> true or false
+ *
+ * Determine whether +lit+ is assigned to true (i.e. <tt>val(lit) == lit</tt>).
+ * 
+ * Raises RuntimeError unless the last #solve returned +:sat+.
+ */
+static VALUE cad_is_true(VALUE self, VALUE lit) {
+  int l = NUM2INT(lit);
+  return ccadical_val(get_cad(self, SATISFIED)->solver, l) == l ? Qtrue : Qfalse;
+}
+
+/*
+ * call-seq:
+ *   solver.failed(lit) -> true or false
+ *
+ * Determine whether the valid non-zero literal +lit+ is in the core. Returns true if the
+ * literal is in the core and false otherwise. Note that the core does not have to be minimal.
+ *
+ * Raises RuntimeError unless the last #solve returned +:unsat+.
+ */
+static VALUE cad_failed(VALUE self, VALUE lit) {
+  return ccadical_failed(get_cad(self, UNSATISFIED)->solver, NUM2INT(lit)) ? Qtrue : Qfalse;
+}
+
+/*
+ * call-seq:
+ *   solver.constraint_failed? -> true or false
+ *
+ * Determine whether the constraint was used to prove the unsatisfiability. Note that the
+ * formula might still be unsatisfiable without the constraint.
+ *
+ * Raises RuntimeError unless the last #solve returned +:unsat+.
+ */
+static VALUE cad_constraint_failed(VALUE self) {
+  return ccadical_constraint_failed(get_cad(self, UNSATISFIED)->solver) ? Qtrue : Qfalse;
+}
+
+/*
+ * call-seq:
+ *   solver.fixed(lit) -> 1, -1, or 0
+ *
+ * Root level assigned variables can be queried with this function. It returns +1+ if the
+ * literal is implied by the formula, +-1+ if its negation is implied, or +0+ if this is
+ * unclear at this point.
+ */
+static VALUE cad_fixed(VALUE self, VALUE lit) {
+  return INT2NUM(ccadical_fixed(get_cad(self, READY)->solver, NUM2INT(lit)));
+}
+
+/* --- callbacks (set_terminate / set_learn) --- */
+
+static VALUE call_proc0(VALUE proc) { return rb_funcall(proc, id_call, 0); }
+
+static void *terminate_body(void *state) {
+  cadical_t *c = state;
+  int err = 0;
+  VALUE r = rb_protect(call_proc0, c->on_terminate, &err);
+  if (err) {
+    c->pending_exc = rb_errinfo();
+    rb_set_errinfo(Qnil);
+    return (void *)1; /* abort the solve so we return and can re-raise */
+  }
+  return (void *)(intptr_t)(RTEST(r) ? 1 : 0);
+}
+
+static int terminate_trampoline(void *state) {
+  cadical_t *c = state;
+  if (NIL_P(c->on_terminate)) return 0;             /* no callback: cheap, no GVL needed */
+  if (!NIL_P(c->pending_exc)) return 1;             /* already failed: keep aborting */
+  return (int)(intptr_t)rb_thread_call_with_gvl(terminate_body, c);
+}
+
+struct learn_call {
+  cadical_t *c;
+  int *clause;
+};
+
+static VALUE learn_invoke(VALUE arg) {
+  struct learn_call *lc = (struct learn_call *)arg;
+  VALUE ary = rb_ary_new();
+  int *p;
+  for (p = lc->clause; *p; p++) rb_ary_push(ary, INT2NUM(*p));
+  return rb_funcall(lc->c->on_learn, id_call, 1, ary);
+}
+
+static void *learn_body(void *arg) {
+  struct learn_call *lc = arg;
+  int err = 0;
+  rb_protect(learn_invoke, (VALUE)lc, &err);
+  if (err) {
+    lc->c->pending_exc = rb_errinfo();
+    rb_set_errinfo(Qnil);
+    /* Unlike terminate, the learn callback returns void and cannot signal an abort, so ask
+     * the solver to stop asynchronously; #solve then returns and re-raises the exception. */
+    ccadical_terminate(lc->c->solver);
+  }
+  return NULL;
+}
+
+static void learn_trampoline(void *state, int *clause) {
+  cadical_t *c = state;
+  struct learn_call lc;
+  if (NIL_P(c->on_learn) || !NIL_P(c->pending_exc)) return;
+  lc.c = c;
+  lc.clause = clause;
+  rb_thread_call_with_gvl(learn_body, &lc);
+}
+
+/*
+ * call-seq:
+ *   solver.set_terminate { -> bool } -> self
+ *   solver.set_terminate             -> self
+ *
+ * Add a callback which is checked regularly for termination: return a truthy value from the
+ * block to abort the search (#solve then returns +:unknown+). There can only be one such
+ * callback; installing a second replaces the first, and calling with no block clears it.
+ */
+static VALUE cad_set_terminate(VALUE self) {
+  cadical_t *c = get_cad(self, READY);
+  if (rb_block_given_p()) {
+    c->on_terminate = rb_block_proc();
+    ccadical_set_terminate(c->solver, c, terminate_trampoline);
+  } else {
+    c->on_terminate = Qnil;
+    ccadical_set_terminate(c->solver, NULL, NULL);
+  }
+  return self;
+}
+
+/*
+ * call-seq:
+ *   solver.set_learn(max_length) { |clause| ... } -> self
+ *   solver.set_learn(max_length)                  -> self
+ *
+ * Add a callback which allows to export learned clauses: the block is invoked with each
+ * learned clause of at most +max_length+ literals, as an Array of literals.
+ * Installing a second callback replaces the first, and calling with no block clears it.
+ */
+static VALUE cad_set_learn(VALUE self, VALUE max_length) {
+  cadical_t *c = get_cad(self, READY);
+  if (rb_block_given_p()) {
+    c->on_learn = rb_block_proc();
+    ccadical_set_learn(c->solver, c, NUM2INT(max_length), learn_trampoline);
+  } else {
+    c->on_learn = Qnil;
+    ccadical_set_learn(c->solver, NULL, NUM2INT(max_length), NULL);
+  }
+  return self;
+}
+
+/*
+ * call-seq:
+ *   solver.terminate -> self
+ *
+ * Force termination of #solve asynchronously.
+ */
+static VALUE cad_terminate(VALUE self) {
+  ccadical_terminate(get_cad(self, READY)->solver);
+  return self;
+}
+
+/* --- options / limits / stats --- */
+
+/*
+ * call-seq:
+ *   solver.set_option(name, value) -> self
+ *
+ * Set the option +name+ to +value+. If the option value is out of range the actual value is
+ * computed as the closest (minimum or maximum) value possible. Options can only be set right
+ * after initialization; the binding raises RuntimeError otherwise.
+ */
+static VALUE cad_set_option(VALUE self, VALUE name, VALUE val) {
+  ccadical_set_option(get_cad(self, CONFIGURING)->solver, StringValueCStr(name), NUM2INT(val));
+  return self;
+}
+
+/*
+ * call-seq:
+ *   solver.get_option(name) -> integer
+ *
+ * Get the current value of the option +name+. If +name+ is invalid then zero is returned.
+ */
+static VALUE cad_get_option(VALUE self, VALUE name) {
+  return INT2NUM(ccadical_get_option(get_cad(self, READY)->solver, StringValueCStr(name)));
+}
+
+/*
+ * call-seq:
+ *   solver.limit(name, value) -> self
+ *
+ * Specify search limits, where currently +name+ can be "conflicts", "decisions",
+ * "preprocessing", or "localsearch". The first two limits are unbounded by default. Thus using
+ * a negative limit for conflicts or decisions switches back to the default of unlimited search
+ * (for that particular limit). The preprocessing limit determines the number of preprocessing
+ * rounds, which is zero by default. Similarly, the local search limit determines the number of
+ * local search rounds (zero by default).
+ *
+ * These limits are only valid for the next #solve or #simplify call and reset to their default
+ * after #solve returns (as well as overwritten and reset during calls to #simplify).
+ *
+ * An unknown +name+ raises ArgumentError.
+ */
+static VALUE cad_limit(VALUE self, VALUE name, VALUE limit) {
+  const char *n = StringValueCStr(name);
+  cadical_t *c = get_cad(self, READY);
+  if (strcmp(n, "conflicts") && strcmp(n, "decisions") &&
+      strcmp(n, "preprocessing") && strcmp(n, "localsearch"))
+    rb_raise(rb_eArgError, "unknown CaDiCaL limit: %s", n);
+  ccadical_limit(c->solver, n, NUM2INT(limit));
+  return self;
+}
+
+/*
+ * call-seq:
+ *   solver.active -> integer
+ *
+ * Returns the number of currently active variables. A variable becomes active if a clause is
+ * added with it, and inactive again if it is eliminated or fixed at the root level.
+ */
+static VALUE cad_active(VALUE self) {
+  return LL2NUM(ccadical_active(get_cad(self, READY)->solver));
+}
+
+/*
+ * call-seq:
+ *   solver.irredundant -> integer
+ *
+ * Returns the number of currently active irredundant clauses. A clause becomes inactive if it
+ * is satisfied, subsumed, or eliminated.
+ */
+static VALUE cad_irredundant(VALUE self) {
+  return LL2NUM(ccadical_irredundant(get_cad(self, READY)->solver));
+}
+
+/* --- variables / phases / freezing --- */
+
+/*
+ * call-seq:
+ *   solver.declare_one_more_variable -> integer
+ *
+ * Returns the next fresh variable that was not used internally.
+ */
+static VALUE cad_declare_one_more_variable(VALUE self) {
+  cadical_t *c = get_cad(self, READY);
+  int v = ccadical_declare_one_more_variable(c->solver);
+  ensure(c, STEADY);
+  return INT2NUM(v);
+}
+
+/*
+ * call-seq:
+ *   solver.declare_more_variables(n) -> integer
+ *
+ * Increase the maximum variable index by +n+ new variables. Returns the new maximum variable
+ * index, which is the highest variable name of the consecutive range of newly declared
+ * variables.
+ */
+static VALUE cad_declare_more_variables(VALUE self, VALUE n) {
+  cadical_t *c = get_cad(self, READY);
+  int v = ccadical_declare_more_variables(c->solver, NUM2INT(n));
+  ensure(c, STEADY);
+  return INT2NUM(v);
+}
+
+/*
+ * call-seq:
+ *   solver.vars -> integer
+ *
+ * The library internally keeps a maximum variable index, which this returns.
+ */
+static VALUE cad_vars(VALUE self) {
+  return INT2NUM(ccadical_vars(get_cad(self, READY)->solver));
+}
+
+/*
+ * call-seq:
+ *   solver.phase(lit) -> self
+ *
+ * Force the default decision phase of a variable to a certain value (the sign of +lit+).
+ */
+static VALUE cad_phase(VALUE self, VALUE lit) {
+  ccadical_phase(get_cad(self, READY)->solver, NUM2INT(lit));
+  return self;
+}
+
+/*
+ * call-seq:
+ *   solver.unphase(lit) -> self
+ *
+ * Reset the default decision phase of +lit+'s variable forced by #phase.
+ */
+static VALUE cad_unphase(VALUE self, VALUE lit) {
+  ccadical_unphase(get_cad(self, READY)->solver, NUM2INT(lit));
+  return self;
+}
+
+/* CaDiCaL's freeze/melt/frozen for literals, exposed as #freeze_lit / #melt_lit / #frozen_lit?.
+ * The +_lit+ suffix keeps #freeze_lit and #frozen_lit? from shadowing Ruby's Object#freeze /
+ * #frozen? (which take no argument and mean object immutability); #melt_lit follows suit. */
+
+/*
+ * call-seq:
+ *   solver.freeze_lit(lit) -> self
+ *
+ * #freeze_lit, #melt_lit and #frozen_lit? are reference-counting functions which avoid restoring
+ * clauses but require substantial user guidance. This was the only way to use inprocessing in
+ * incremental SAT solving in Lingeling (and before in MiniSAT's 'freeze' / 'thaw') and which did
+ * not use automatic clause restoring. In general this is slower than restoring clauses and should
+ * not be used.
+ *
+ * In essence the user freezes variables which potentially are still needed in clauses added or
+ * assumptions used after the next #solve call. As in Lingeling you can freeze a variable multiple
+ * times, but then have to #melt_lit it the same number of times again in order to enable variable
+ * eliminating on it etc. The arguments can be literals (negative indices) but conceptually
+ * variables are frozen.
+ *
+ * In the old way of doing things without restore you should not use a variable incrementally (in
+ * #add or #assume), which was used before and potentially could have been eliminated in a previous
+ * #solve call. This can lead to spurious satisfying assignment. In order to check this API
+ * contract one can use the "checkfrozen" option (via #set_option). This has the drawback that
+ * restoring clauses implicitly would fail with a fatal error message even if in principle the
+ * solver could just restore clauses. Thus this option is disabled by default.
+ *
+ * See the CaDiCaL SAT'19 paper [FazekasBiereScholl-SAT'19] for more details.
+ */
+static VALUE cad_freeze_lit(VALUE self, VALUE lit) {
+  ccadical_freeze(get_cad(self, READY)->solver, NUM2INT(lit));
+  return self;
+}
+
+/*
+ * call-seq:
+ *   solver.melt_lit(lit) -> self
+ *
+ * Melt (thaw) the variable of +lit+, reversing one #freeze_lit: once its freeze count reaches
+ * zero, simplification may eliminate the variable again. The variable must currently be frozen.
+ */
+static VALUE cad_melt_lit(VALUE self, VALUE lit) {
+  ccadical_melt(get_cad(self, READY)->solver, NUM2INT(lit));
+  return self;
+}
+
+/*
+ * call-seq:
+ *   solver.frozen_lit?(lit) -> true or false
+ *
+ * Returns whether the variable of +lit+ is currently frozen (see #freeze_lit).
+ */
+static VALUE cad_frozen_lit(VALUE self, VALUE lit) {
+  return ccadical_frozen(get_cad(self, READY)->solver, NUM2INT(lit)) ? Qtrue : Qfalse;
+}
+
+/* --- proof tracing --- */
+
+/*
+ * call-seq:
+ *   solver.trace_proof(path) -> true or false
+ *
+ * Enable clausal proof tracing to the file at +path+; returns true if it was successfully
+ * opened for writing. Must be called before any #add or #solve, else it raises RuntimeError.
+ */
+static VALUE cad_trace_proof(VALUE self, VALUE path) {
+  cadical_t *c = get_cad(self, CONFIGURING);
+  const char *p = StringValueCStr(path);
+  FILE *f = fopen(p, "w");
+  int ok;
+  if (!f) rb_sys_fail(p);
+  ok = ccadical_trace_proof(c->solver, f, p);
+  if (!ok) {
+    fclose(f);
+    return Qfalse;
+  }
+  if (c->proof_file) fclose(c->proof_file);
+  c->proof_file = f;
+  return Qtrue;
+}
+
+/*
+ * call-seq:
+ *   solver.close_proof -> self
+ *
+ * Close the proof trace early. Before actually closing, CaDiCaL checks whether a proof step (a
+ * clause addition or deletion) has been traced since the last flush and, if so, flushes it
+ * first. The file opened by #trace_proof is closed as well.
+ *
+ * Raises RuntimeError unless a proof trace is currently open (CaDiCaL would otherwise abort the
+ * process).
+ */
+static VALUE cad_close_proof(VALUE self) {
+  cadical_t *c = get_cad(self, READY);
+  if (!c->proof_file) rb_raise(rb_eRuntimeError, "no proof trace is open (see #trace_proof)");
+  ccadical_close_proof(c->solver);
+  fclose(c->proof_file);
+  c->proof_file = NULL;
+  return self;
+}
+
+/*
+ * call-seq:
+ *   solver.conclude -> self
+ *
+ * Triggers the conclusion of incremental proofs. If the solver is satisfied it gives the model
+ * to the proof tracer; if it is unsatisfied it learns the failing core (for failed assumptions
+ * the core negated as a single clause, for a failing constraint possibly several) and concludes
+ * with the ids of the newly learnt clauses or the id of the global conflict; if the result was
+ * unknown it collects the currently entailed literals and adds them to the proof.
+ *
+ * Raises RuntimeError unless a #solve or #simplify has completed.
+ */
+static VALUE cad_conclude(VALUE self) {
+  ccadical_conclude(get_cad(self, SOLVED)->solver);
+  return self;
+}
+
+/* --- class-level --- */
+
+/*
+ * call-seq:
+ *   CaDiCaL.signature -> string
+ *
+ * The name of this library.
+ */
+static VALUE cad_signature(VALUE klass) {
+  (void)klass;
+  return rb_str_new_cstr(ccadical_signature());
+}
+
+void Init_cadical(void) {
+  VALUE c;
+
+  id_sat = rb_intern("sat");
+  id_unsat = rb_intern("unsat");
+  id_unknown = rb_intern("unknown");
+  id_call = rb_intern("call");
+
+  c = rb_define_class("CaDiCaL", rb_cObject);
+  rb_define_alloc_func(c, cad_alloc);
+
+  rb_define_singleton_method(c, "signature", cad_signature, 0);
+
+  rb_define_method(c, "release", cad_release, 0);
+
+  rb_define_method(c, "add", cad_add, -1);
+  rb_define_method(c, "assume", cad_assume, 1);
+  rb_define_method(c, "constrain", cad_constrain, -1);
+
+  rb_define_method(c, "solve", cad_solve, 0);
+  rb_define_method(c, "simplify", cad_simplify, 0);
+  rb_define_method(c, "val", cad_val, 1);
+  rb_define_method(c, "true?", cad_is_true, 1);
+  rb_define_method(c, "failed", cad_failed, 1);
+  rb_define_method(c, "constraint_failed?", cad_constraint_failed, 0);
+  rb_define_method(c, "fixed", cad_fixed, 1);
+
+  rb_define_method(c, "set_terminate", cad_set_terminate, 0);
+  rb_define_method(c, "set_learn", cad_set_learn, 1);
+  rb_define_method(c, "terminate", cad_terminate, 0);
+
+  rb_define_method(c, "set_option", cad_set_option, 2);
+  rb_define_method(c, "get_option", cad_get_option, 1);
+  rb_define_method(c, "limit", cad_limit, 2);
+  rb_define_method(c, "active", cad_active, 0);
+  rb_define_method(c, "irredundant", cad_irredundant, 0);
+
+  rb_define_method(c, "declare_one_more_variable", cad_declare_one_more_variable, 0);
+  rb_define_method(c, "declare_more_variables", cad_declare_more_variables, 1);
+  rb_define_method(c, "vars", cad_vars, 0);
+  rb_define_method(c, "phase", cad_phase, 1);
+  rb_define_method(c, "unphase", cad_unphase, 1);
+  rb_define_method(c, "freeze_lit", cad_freeze_lit, 1);
+  rb_define_method(c, "melt_lit", cad_melt_lit, 1);
+  rb_define_method(c, "frozen_lit?", cad_frozen_lit, 1);
+
+  rb_define_method(c, "trace_proof", cad_trace_proof, 1);
+  rb_define_method(c, "close_proof", cad_close_proof, 0);
+  rb_define_method(c, "conclude", cad_conclude, 0);
+}