Getting Started¶

coposit accepts exact symmetric matrices through the command line, Python, or C++. Ordinary users do not select an algorithm: all three public interfaces use the production solver and the complete exact preprocessing pipeline.

Install¶

Python¶

Python 3.11 through 3.14 users can install the package from PyPI:

python -m pip install pycoposit

Command line¶

Download the package for Linux, macOS, or Windows from the release page and extract it. Run coposit; the other packaged files are private runtime dependencies and are not user interfaces.

Windows examples use coposit.exe instead of ./coposit.

Build from source¶

A source build requires CMake 3.18 or newer, C and C++17 compilers, Python 3.11 or newer, FLINT, MPFR, and GMP. This minimal build creates the production solver and command line without the retained research experiments:

git clone https://github.com/reinhardullrich/coposit.git
cd coposit
cmake -S cpp -B cpp/build-release -DCMAKE_BUILD_TYPE=Release \
  -DCOPOSIT_BUILD_EXPERIMENTS=OFF \
  -DCOPOSIT_BUILD_TESTS=OFF \
  -DCOPOSIT_BUILD_PYTHON=OFF
cmake --build cpp/build-release --parallel

Encode a matrix¶

Compact upper-triangular form¶

The compact form is dimension#values. Write the upper triangle row by row. For

\[\begin{split}A=\begin{pmatrix} a_{11}&a_{12}&a_{13}\\ a_{12}&a_{22}&a_{23}\\ a_{13}&a_{23}&a_{33} \end{pmatrix},\end{split}\]

the input is:

3#a11,a12,a13,a22,a23,a33

Exactly \(n(n+1)/2\) values are required. Values may be integers, fractions, finite decimals, or scientific notation, such as -3/5, -0.6, and -6e-1. All three are converted exactly. A fraction’s denominator must be positive, so write -1/2 rather than 1/-2.

Compact circular-symmetric form¶

A shorter form is available when the matrix is unchanged by a simultaneous cyclic shift of its row and column indices. Supply the common diagonal followed by one value for each positive circular distance:

n#c0,c1,c2,...,c_floor(n/2)

For example, 5#2,3,5 expands to a 5-by-5 matrix whose first row is 2,3,5,5,3. The shorter value count selects this form automatically.

Matrix Market¶

The command line also accepts symmetric Matrix Market array and coordinate files. Integer, real, pattern, and complex fields are supported; complex entries must have zero imaginary part. Decimal and scientific values remain exact.

Run one matrix from the command line¶

Run both classifications:

./coposit '2#1,-1,1'

The result is:

copositive=true
strictly_copositive=false

To ask only one question, use --mode non-strict or --mode strict:

./coposit --mode non-strict '2#1,-1,1'
./coposit --mode strict '2#1,-1,1'

The command also accepts a file path or standard input:

./coposit matrix.mtx
./coposit -

Timeouts and diagnostics¶

Set a wall-clock limit in seconds with --timeout:

./coposit --timeout 30 matrix.mtx

A timeout is unresolved. The command emits no Boolean answer and exits with status 124. Add --diagnostics to print the current phase and work counters to standard error about once per second:

./coposit --diagnostics --timeout 30 matrix.mtx

Diagnostics describe completed work; they are not an estimate of the remaining time.

Run one matrix from Python¶

check() accepts compact text, inline Matrix Market text, or a file path. It checks both properties by default:

from pycoposit import check

result = check("2#1,-1,1")
if result["status"] == 0:
    print(result["is_copositive"])
    print(result["is_strictly_copositive"])
else:
    print(result["error_message"])

Request one property with mode="copositive" or mode="strictly_copositive". The unrequested result is None.

Run several matrices¶

The explicit-model research interface can process matrices sequentially or across worker processes. Results from run_multiprocessing() arrive in completion order, so attach matrix_id values rather than relying on list position:

from pycoposit import MPConfig, Matrix, run_multiprocessing

matrices = [
    Matrix("2#1,-1,1", matrix_id=1),
    Matrix("2#1,0,1", matrix_id=2),
]
results = run_multiprocessing(
    "hadeler_1983",
    matrices,
    mp_config=MPConfig(workers=2),
    mode="both",
)
for result in results:
    print(result["matrix_id"], result["is_copositive"], result["is_strictly_copositive"])

See Python API for the complete wrapper contract. Research builds can select retained models explicitly; ordinary applications should use check() and leave exact preprocessing enabled.

Interpret failures¶

Always inspect status before consuming a Python result. Invalid input, an execution failure, a timeout, a node limit, or an internal failure leaves the requested classifications as None. None of these conditions means that the matrix is not copositive.

There is no fixed mathematical dimension limit in the maintained representation. The search space can nevertheless grow exponentially, so a valid high-dimensional input may require impractical time or memory.

coposit

Navigation

Table of Contents