C++ API

The public native interface consists of the synchronous analyzer and its candidate records. The CLI and Python binding parse input with the embedded coposit parser and pass its exact integer-scaled result directly to the analyzer. Direct C++ callers receive exceptions from invalid method names, malformed input, allocation failures, or arithmetic failures; the CLI and Python binding translate them into their public status formats.

Core types

enum class fracessa::search_method

Candidate-search method selected by the CLI or native caller.

Values:

enumerator fast

Potentially incomplete binary64 candidate filter followed by exact candidate verification and stability.

enumerator safe

Complete exact candidate search and exact stability.

fracessa::candidate stores one exact symmetric Nash equilibrium. Its support handles use the matrix-wide support context, so the same type represents every supported dimension. is_ess and stability record the later exact stability decision.

class candidate

Result of the exact equilibrium test for one support.

Public Functions

inline std::string support_string() const

Return support as an arbitrary-width decimal integer bit mask.

inline std::string extended_support_string() const

Return extended_support as an arbitrary-width decimal integer bit mask.

inline std::string to_string() const

Serialize this candidate as one semicolon-separated CLI row.

Public Members

size_t candidate_id = 0

One-based stored-representative ID in deterministic search order; attempted and represented orbit members are not IDs.

std::vector<numeric::fraction> vector

Full n-dimensional exact mixed strategy. Entries outside I(x) are zero.

support::Support support

I(x), the strategies used with positive probability.

size_t support_size = 0

Number of strategies in I(x).

support::Support extended_support

J(x), all pure strategies that are best replies to x.

size_t extended_support_size = 0

Number of strategies in J(x).

std::optional<size_t> multiplier

Number of distinct rotations/reflections represented by this row; ordinary candidates have no multiplier.

bool is_ess = false

Whether exact stability checking accepted this candidate as an ESS.

std::string stability

Machine-readable reason code produced by exact stability checking.

numeric::fraction payoff

Exact equilibrium payoff x^T A x.

double payoff_dbl = 0.0

Lossy output-only approximation of payoff; no mathematical decision uses it.

Public Static Functions

static inline std::string header()

Return the semicolon-separated column names produced by to_string().

Analyzer

Constructing fracessa::analyzer runs the configured analysis synchronously. The analyzer creates one matrix-wide support context and uses the same public search path for every dimension.

The public count and structure fields are always populated and include circular multipliers. They contain every candidate found by the ESS search; only safe guarantees a complete ESS result. They are not an enumeration of every degenerate or strict-superset Nash equilibrium. The candidates_ vector is populated only when with_candidates was true, and omitting rows does not change the counts. A non-none safe_fallback_ records only a whole-matrix switch from fast to exact candidate search.

search_method fracessa::parse_search_method(std::string_view name)

class analyzer

Runs the configured ESS search for one payoff matrix.

Public Members

size_t candidate_count_ = 0

Candidate count found by the selected method, including circular multipliers.

size_t ess_count_ = 0

ESS count found by the selected method, including circular multipliers.

structure_type candidate_structure_

Candidate counts indexed by support size; index zero is unused.

structure_type ess_structure_

ESS counts indexed by support size; index zero is unused.

search::safe_fallback safe_fallback_ = search::safe_fallback::none

Whole-matrix fast-to-safe fallback reason; per-support exact retries do not set it.

std::vector<candidate_type> candidates_

Representative candidate rows. Populated only when with_candidates is true.

Input and output

coposit’s coposit::parsers::matrix_parser accepts exact integers, fractions, finite decimals, and scientific notation in either the full upper-triangular layout or the compact circular layout. The latter begins with the common diagonal and continues with one value per positive circular distance. A fraction has an optional sign before its numerator and a positive integer denominator, so -1/2 is valid and 1/-2 is not. The parser also accepts symmetric Matrix Market input and returns coposit::parsers::parsed_matrix: one integer matrix, its common positive denominator, and the compact-circular marker consumed by fracessa::analyzer.

matrix_parser::parse() reads matrix contents. Use matrix_parser::parse_file() when a direct C++ caller has a path. The compact circular layout is explained in Getting Started.

Minimal native example

The analyzer takes ownership of the parsed matrix:

#include <coposit/parsers/matrix_parser.hpp>
#include <fracessa/fracessa.hpp>

#include <iostream>
#include <utility>

int main()
{
    auto game = coposit::parsers::matrix_parser::parse("3#-1,0,0,-2,0,-3");
    fracessa::analyzer result(fracessa::search_method::safe, std::move(game), true);
    std::cout << result.ess_count_ << '\n';
}

Construction blocks until the complete analysis finishes. Pass false instead of true for the third argument when only counts and support-size structures are needed; this avoids retaining individual candidate vectors without changing the computation.