Python API

The pycoposit package launches the same exact command-line implementation used by standalone releases. Inputs are small dataclasses and every result is an ordinary dictionary.

Public and research interfaces

Use pycoposit.check() in an application. It selects the production solver and the complete preprocessing pipeline. The other execution functions require an explicit model name and are intended for controlled research comparisons.

pycoposit.check(matrix, mode='both')

Check one matrix with the current incumbent model.

Parameters:

• matrix (Matrix | str)

• mode (Literal['copositive', 'strictly_copositive', 'both'])

Return type:

dict

Result dictionary

Every execution result contains these fields:

Field	Meaning
algorithm	coposit for pycoposit.check(); the selected model identifier for an explicit research run.
mode	Requested classification: copositive, strictly_copositive, or both.
preprocessing	both for the complete preprocessing pipeline or none for an explicit research run.
model_parameter	Model-specific research parameter, otherwise None.
matrix_id	Optional signed 64-bit identifier copied from pycoposit.Matrix.
status	Integer pycoposit.StatusCode. Only 0 means a completed classification.
is_copositive	Exact Boolean answer when requested and completed; otherwise None.
is_strictly_copositive	Exact Boolean answer when requested and completed; otherwise None.
elapsed_ns	Native execution duration in nanoseconds measured with a monotonic clock.
error_message	Empty on success; otherwise a parser, execution, worker, or resource diagnostic.
diagnostics	Captured textual diagnostics when requested.
certificate_joint_distribution	Model-specific certificate counters used for analysis and visualization.

Core types

class pycoposit.StatusCode(*values)

Status values returned by native matrix computation.

class pycoposit.Matrix(matrix, matrix_id=None)

Matrix text or path with an optional correlation ID.

Parameters:

• matrix (str)

• matrix_id (int | None)

class pycoposit.MPConfig(workers=4, prefetch_per_worker=128, queue_maxsize=4096, start_method='spawn')

Process scheduling for run_multiprocessing().

Parameters:

• workers (int)

• prefetch_per_worker (int)

• queue_maxsize (int)

• start_method (Literal['spawn', 'forkserver', 'fork'])

Sequential research execution

compute_matrix() is the single-matrix primitive. run() returns one dictionary for one pycoposit.Matrix, or a lazy input-ordered iterator for an iterable.

pycoposit.compute_matrix(algorithm, matrix, mode=None, preprocessing='both', diagnostics=False, collect_certificate_joint_distribution=False, model_parameter=None, *, _stream_diagnostics=False)

Run one matrix through an explicitly selected research model.

Parameters:

• algorithm (Literal['dutour_2018', 'danninger_1990', 'copomatrix_2011', 'adaptive_dutour_danninger', 'adaptive_dutour_copomatrix', 'adaptive_sponsel_copomatrix', 'adaptive_zischg_sponsel_copomatrix', 'hadeler_1983', 'dickinson_2019', 'dense_bitset_dickinson', 'interval_recursive_dickinson', 'bdd_dickinson', 'zdd_dickinson', 'cbdd_dickinson', 'cbdd_halfspace_dickinson', 'upper_endpoint_cbdd_dickinson', 'cbdd_dickinson_improved_1', 'wide_certificate_cbdd_dickinson', 'multithreaded_cbdd_dickinson', 'ceiling_pruned_dickinson', 'kernel_cone_dickinson', 'affine_companion_dickinson', 'layered_singular_lift_dickinson', 'breadth_first_singular_lift_dickinson', 'czdd_dickinson', 'sat_dickinson', 'sat_halfspace_dickinson', 'sat_halfspace_rays_dickinson', 'sat_b1', 'sat_b2', 'sat_b3', 'branch_n_prune_1', 'branch_n_prune_2', 'clasp_b3', 'bdd_b3', 'sat_b4', 'sat_b5', 'nbc_b6', 'nbc_b7', 'improved_nbc_b7', 'improved_nbc_x2', 'improved_nbc_x3', 'improved_nbc_x4', 'improved_nbc_x5', 'improved_nbc_x6', 'improved_nbc_x7', 'improved_nbc_x8', 'improved_nbc_x9', 'improved_nbc_x10', 'improved_nbc_x11', 'improved_nbc_x12', 'improved_nbc_x13', 'improved_nbc_x14', 'improved_nbc_x15', 'improved_nbc_x16', 'improved_nbc_x17', 'improved_nbc_x18', 'improved_nbc_x19', 'improved_nbc_x20', 'improved_nbc_x21', 'improved_nbc_x22', 'improved_nbc_x23', 'ccudd_x24', 'improved_nbc_x25', 'improved_nbc_x26', 'improved_nbc_x27', 'improved_nbc_x28', 'improved_nbc_x29', 'improved_nbc_x30', 'improved_nbc_x31', 'improved_nbc_x32', 'interval_supports_g3', 'minimal_sat_g4', 'cadical_x1', 'dual_frontier_nbc', 'dual_frontier_nbc_two', 'dual_frontier_nbc_three', 'dual_frontier_nbc_four', 'improved_nbc_b8', 'improved_nbc_b9', 'improved_nbc_g2', 'sat_c1', 'sat_c2', 'sat_c3', 'sat_c4', 'f1', 'f2', 'g1', 'milp_1', 'sat_a1', 'sat_a2', 'sat_a3', 'sat_a4', 'sat_a5', 'sat_halfspace_lp_dickinson', 'sat_halfspace_milp_dickinson', 'sat_halfspace_rays_lookahead_dickinson', 'sat_halfspace_rays_wide_dickinson', 'wide_certificate_sat_dickinson', 'xxx', 'xxx_two', 'clingo_dickinson', 'clingo_halfspace_dickinson', 'support_pruned_dickinson', 'nullity_support_pruned_dickinson', 'rhs_dickinson', 'frank_wolfe_dickinson', 'one_step_frank_wolfe_dickinson', 'pairwise_frank_wolfe_dickinson', 'support_polished_frank_wolfe_dickinson', 'safi_2021', 'bundfuss_2008', 'sponsel_2012', 'frank_wolfe_sponsel', 'fracessa', 'zischg_hadeler', 'zischg_dickinson', 'zischg_fracessa'])

• matrix (Matrix)

• mode (Literal['copositive', 'strictly_copositive', 'both'] | None)

• preprocessing (Literal['none', 'both'])

• diagnostics (bool)

• collect_certificate_joint_distribution (bool)

• model_parameter (str | None)

• _stream_diagnostics (bool)

Return type:

dict

pycoposit.run(algorithm, matrices, mode=None, preprocessing='both', diagnostics=False, model_parameter=None)

Run one matrix immediately or lazily yield an iterable in input order.

Parameters:

• algorithm (Literal['dutour_2018', 'danninger_1990', 'copomatrix_2011', 'adaptive_dutour_danninger', 'adaptive_dutour_copomatrix', 'adaptive_sponsel_copomatrix', 'adaptive_zischg_sponsel_copomatrix', 'hadeler_1983', 'dickinson_2019', 'dense_bitset_dickinson', 'interval_recursive_dickinson', 'bdd_dickinson', 'zdd_dickinson', 'cbdd_dickinson', 'cbdd_halfspace_dickinson', 'upper_endpoint_cbdd_dickinson', 'cbdd_dickinson_improved_1', 'wide_certificate_cbdd_dickinson', 'multithreaded_cbdd_dickinson', 'ceiling_pruned_dickinson', 'kernel_cone_dickinson', 'affine_companion_dickinson', 'layered_singular_lift_dickinson', 'breadth_first_singular_lift_dickinson', 'czdd_dickinson', 'sat_dickinson', 'sat_halfspace_dickinson', 'sat_halfspace_rays_dickinson', 'sat_b1', 'sat_b2', 'sat_b3', 'branch_n_prune_1', 'branch_n_prune_2', 'clasp_b3', 'bdd_b3', 'sat_b4', 'sat_b5', 'nbc_b6', 'nbc_b7', 'improved_nbc_b7', 'improved_nbc_x2', 'improved_nbc_x3', 'improved_nbc_x4', 'improved_nbc_x5', 'improved_nbc_x6', 'improved_nbc_x7', 'improved_nbc_x8', 'improved_nbc_x9', 'improved_nbc_x10', 'improved_nbc_x11', 'improved_nbc_x12', 'improved_nbc_x13', 'improved_nbc_x14', 'improved_nbc_x15', 'improved_nbc_x16', 'improved_nbc_x17', 'improved_nbc_x18', 'improved_nbc_x19', 'improved_nbc_x20', 'improved_nbc_x21', 'improved_nbc_x22', 'improved_nbc_x23', 'ccudd_x24', 'improved_nbc_x25', 'improved_nbc_x26', 'improved_nbc_x27', 'improved_nbc_x28', 'improved_nbc_x29', 'improved_nbc_x30', 'improved_nbc_x31', 'improved_nbc_x32', 'interval_supports_g3', 'minimal_sat_g4', 'cadical_x1', 'dual_frontier_nbc', 'dual_frontier_nbc_two', 'dual_frontier_nbc_three', 'dual_frontier_nbc_four', 'improved_nbc_b8', 'improved_nbc_b9', 'improved_nbc_g2', 'sat_c1', 'sat_c2', 'sat_c3', 'sat_c4', 'f1', 'f2', 'g1', 'milp_1', 'sat_a1', 'sat_a2', 'sat_a3', 'sat_a4', 'sat_a5', 'sat_halfspace_lp_dickinson', 'sat_halfspace_milp_dickinson', 'sat_halfspace_rays_lookahead_dickinson', 'sat_halfspace_rays_wide_dickinson', 'wide_certificate_sat_dickinson', 'xxx', 'xxx_two', 'clingo_dickinson', 'clingo_halfspace_dickinson', 'support_pruned_dickinson', 'nullity_support_pruned_dickinson', 'rhs_dickinson', 'frank_wolfe_dickinson', 'one_step_frank_wolfe_dickinson', 'pairwise_frank_wolfe_dickinson', 'support_polished_frank_wolfe_dickinson', 'safi_2021', 'bundfuss_2008', 'sponsel_2012', 'frank_wolfe_sponsel', 'fracessa', 'zischg_hadeler', 'zischg_dickinson', 'zischg_fracessa'])

• matrices (Matrix | Iterable[Matrix])

• mode (Literal['copositive', 'strictly_copositive', 'both'] | None)

• preprocessing (Literal['none', 'both'])

• diagnostics (bool)

• model_parameter (str | None)

Return type:

dict | Iterator[dict]

Leaving mode unset selects both only for models that implement combined classification in one traversal. A model that does not support that contract requires an explicit single-property mode. preprocessing="none" is for algorithm experiments; normal use should keep preprocessing="both".

Multiprocessing

pycoposit.run_multiprocessing(algorithm, matrices, mp_config=None, mode=None, preprocessing='both', model_parameter=None)

Run one matrix or an iterable across worker processes in completion order.

Parameters:

• algorithm (Literal['dutour_2018', 'danninger_1990', 'copomatrix_2011', 'adaptive_dutour_danninger', 'adaptive_dutour_copomatrix', 'adaptive_sponsel_copomatrix', 'adaptive_zischg_sponsel_copomatrix', 'hadeler_1983', 'dickinson_2019', 'dense_bitset_dickinson', 'interval_recursive_dickinson', 'bdd_dickinson', 'zdd_dickinson', 'cbdd_dickinson', 'cbdd_halfspace_dickinson', 'upper_endpoint_cbdd_dickinson', 'cbdd_dickinson_improved_1', 'wide_certificate_cbdd_dickinson', 'multithreaded_cbdd_dickinson', 'ceiling_pruned_dickinson', 'kernel_cone_dickinson', 'affine_companion_dickinson', 'layered_singular_lift_dickinson', 'breadth_first_singular_lift_dickinson', 'czdd_dickinson', 'sat_dickinson', 'sat_halfspace_dickinson', 'sat_halfspace_rays_dickinson', 'sat_b1', 'sat_b2', 'sat_b3', 'branch_n_prune_1', 'branch_n_prune_2', 'clasp_b3', 'bdd_b3', 'sat_b4', 'sat_b5', 'nbc_b6', 'nbc_b7', 'improved_nbc_b7', 'improved_nbc_x2', 'improved_nbc_x3', 'improved_nbc_x4', 'improved_nbc_x5', 'improved_nbc_x6', 'improved_nbc_x7', 'improved_nbc_x8', 'improved_nbc_x9', 'improved_nbc_x10', 'improved_nbc_x11', 'improved_nbc_x12', 'improved_nbc_x13', 'improved_nbc_x14', 'improved_nbc_x15', 'improved_nbc_x16', 'improved_nbc_x17', 'improved_nbc_x18', 'improved_nbc_x19', 'improved_nbc_x20', 'improved_nbc_x21', 'improved_nbc_x22', 'improved_nbc_x23', 'ccudd_x24', 'improved_nbc_x25', 'improved_nbc_x26', 'improved_nbc_x27', 'improved_nbc_x28', 'improved_nbc_x29', 'improved_nbc_x30', 'improved_nbc_x31', 'improved_nbc_x32', 'interval_supports_g3', 'minimal_sat_g4', 'cadical_x1', 'dual_frontier_nbc', 'dual_frontier_nbc_two', 'dual_frontier_nbc_three', 'dual_frontier_nbc_four', 'improved_nbc_b8', 'improved_nbc_b9', 'improved_nbc_g2', 'sat_c1', 'sat_c2', 'sat_c3', 'sat_c4', 'f1', 'f2', 'g1', 'milp_1', 'sat_a1', 'sat_a2', 'sat_a3', 'sat_a4', 'sat_a5', 'sat_halfspace_lp_dickinson', 'sat_halfspace_milp_dickinson', 'sat_halfspace_rays_lookahead_dickinson', 'sat_halfspace_rays_wide_dickinson', 'wide_certificate_sat_dickinson', 'xxx', 'xxx_two', 'clingo_dickinson', 'clingo_halfspace_dickinson', 'support_pruned_dickinson', 'nullity_support_pruned_dickinson', 'rhs_dickinson', 'frank_wolfe_dickinson', 'one_step_frank_wolfe_dickinson', 'pairwise_frank_wolfe_dickinson', 'support_polished_frank_wolfe_dickinson', 'safi_2021', 'bundfuss_2008', 'sponsel_2012', 'frank_wolfe_sponsel', 'fracessa', 'zischg_hadeler', 'zischg_dickinson', 'zischg_fracessa'])

• matrices (Matrix | Iterable[Matrix])

• mp_config (MPConfig | None)

• mode (Literal['copositive', 'strictly_copositive', 'both'] | None)

• preprocessing (Literal['none', 'both'])

• model_parameter (str | None)

Return type:

dict | Iterator[dict]

One worker analyzes one matrix at a time, and results are yielded in completion order. Submission is bounded by min(queue_maxsize, workers * prefetch_per_worker) so a lazy input iterable does not become an unbounded in-memory queue. Closing an unfinished iterator terminates its workers. Scripts using the default spawn method must protect their entry point:

if __name__ == "__main__":
    main()

Input contract

pycoposit.Matrix stores compact matrix text, inline Matrix Market text, or a file path. Compact and Matrix Market formats are described in Getting Started. matrix_id is correlation metadata only and does not affect the calculation.

The package locates coposit beside itself, in the standard source-build directories, or on PATH. Set the COPOSIT environment variable to an explicit launcher path when embedding a custom research build.