API Reference

Represents a tropical Puiseux polynomial, i.e. a tropical polynomial in several variables, whose exponents might be rational numbers (i.e. we use this structure when T is a subtype of the rational numbers). The coefficients are elements of the tropical semiring.

Example

julia> f = Signomial(Dict([1, 2] => 1, [2, 1] => 2), [[1, 2], [2, 1]]) Signomial{Int64}(Dict([2, 1] => 2, [1, 2] => 1), [[1, 2], [2, 1]])

Represents a quotient of signomials.

LinearRegion{T}

Represents one linear region of a tropical Puiseux rational function.

A linear region is the maximal set on which the rational function restricts to a single affine linear map. This set may be non-convex; regions holds all the full-dimensional convex polyhedra whose union makes up the linear region.

Supports length, iterate, and integer indexing over regions.

LinearRegions{T}

The return type of enum_linear_regions_rat. Holds all linear regions of a tropical Puiseux rational function as a vector of LinearRegion{T} objects.

Each element of regions is a LinearRegion corresponding to a distinct affine linear map realised by the rational function. A LinearRegion may contain more than one convex polyhedron when the same linear map is realised on several disconnected pieces.

Supports length, iterate, and integer indexing over the LinearRegion entries.

Signomial_const(n, c, f::Signomial{T})

Construct the constant c as a signomial in n variables.

Arguments

• n: number of variables
• c: the tropical coefficient (a TropicalSemiringElem)
• f: a Signomial{T} used only to infer the exponent type T; its value is irrelevant

Returns a Signomial{T} with a single monomial whose exponent is the zero vector and whose coefficient is c.

When the type is known statically, the cleaner alternatives Base.zero(Signomial{T}, n) and Base.one(Signomial{T}, n) are also available.

Signomial_zero(n, f::Signomial{T})

Construct the tropical-zero signomial in n variables.

Tropical zero is the identity element for tropical addition (max), i.e. the element that satisfies max(a, -∞) = a. It is represented as a monomial with coefficient -∞ (the additive identity of the tropical semiring) and the zero exponent vector.

The argument f is used only to infer the exponent type T; its value is irrelevant. Returns a Signomial{T}.

When the type T is known statically, prefer Base.zero(Signomial{T}, n) for a type-explicit API that does not require an existing Signomial instance.

Signomial_one(n, f::Signomial{T})

Construct the tropical-one signomial in n variables.

Tropical one is the identity element for tropical multiplication, i.e. the element that satisfies a * 0 = a in the tropical semiring. It is represented as a monomial with coefficient 0 and the zero exponent vector.

The argument f is used only to infer the exponent type T; its value is irrelevant. Returns a Signomial{T}.

When the type T is known statically, prefer Base.one(Signomial{T}, n) for a type-explicit API that does not require an existing Signomial instance.

SignomialMonomial(c, exp::Vector{T})

Constructs a signomial from a scalar c and a vector of exponents. This is a monomial whose coefficient is c and exponents are given by exp.

signomial_to_rational(f)

Constructs a rational signomial from a signomial f, by setting the denominator to be the tropical one.

RationalSignomial_identity(n, c)

Return the vector of coordinate projections [x₁, x₂, ..., xₙ] as rational signomials.

Each xᵢ is represented as a RationalSignomial whose numerator is the monomial 1 * T^eᵢ (where eᵢ is the i-th standard basis vector) and whose denominator is the tropical-one monomial.

Arguments

• n: number of variables (length of the returned vector)
• c: a tropical semiring element used only to infer the coefficient type; its value is not otherwise used (only one(c) is called on it)

Returns

Vector{RationalSignomial} of length n.

Example

R = Oscar.tropical_semiring(max)
id = RationalSignomial_identity(3, one(R))
# id[1] represents x₁, id[2] represents x₂, id[3] represents x₃

RationalSignomial_zero(n, f::RationalSignomial{T})

Construct the tropical-zero rational signomial in n variables.

Tropical zero is the identity for tropical addition (max), i.e. the element −∞. It is represented as the rational signomial whose numerator is the tropical-zero signomial and whose denominator is the tropical-one signomial.

The argument f is used only to infer the exponent type T; its value is irrelevant. Returns a RationalSignomial{T}.

You can also use Base.zero(RationalSignomial{T}, n) for a type-explicit API that does not require an existing RationalSignomial instance.

RationalSignomial_one(n, f)

Construct the tropical-one rational signomial in n variables.

Tropical one is the identity for tropical multiplication, corresponding to the value 0 in the tropical semiring. It is represented as the rational signomial whose numerator and denominator are both the tropical-one signomial (so the quotient is 0 - 0 = 0 in the tropical sense, i.e. the multiplicative identity).

The argument f is used only to infer the exponent type T via f.num; its value is irrelevant. Returns a RationalSignomial{T}.

You can also use Base.one(RationalSignomial{T}, n) for a type-explicit API that does not require an existing RationalSignomial instance.

evaluate(f::Signomial, a::Vector)

Evaluates the signomial f at the point a.

evaluate(f::RationalSignomial{T}, a::Vector)

Evaluates the rational signomial f at the point a.

evaluate(F::Vector{RationalSignomial{T}}, a::Vector)

Evaluates the vector of rational signomials F at the point a.

evaluate(g::StandardizedTropicalPoly, x::Vector) -> TropicalSemiringElem

Evaluate the standardized tropical polynomial at the point x. Uses the identity x[i]^(exp[i] // denom) = x[i] ^ Rational(exp[i], denom).

quicksum(F::Vector{Signomial{T}})

Faster alternative to iterated + when summing many polynomials. Instead of O(n) pairwise sorted merges, collects all terms and sorts once at the end.

quicksum(polys::Vector{<:StandardizedTropicalPoly}) -> StandardizedTropicalPoly

Tropical sum (element-wise max) of a vector of standardized polynomials.

mlp_to_trop(linear_maps, bias, thresholds; quicksum=false, strong_elim=false, dedup=false)

Convert a ReLU multilayer perceptron to a tropical Puiseux rational function.

This function converts a neural network with ReLU-like activation functions (max(x,t)) into an exact tropical geometric representation, enabling analysis of linear regions and network expressivity.

Arguments

• linear_maps::Vector{Matrix{T}}: Weight matrices for each layer
• bias: Bias vectors for each layer
• thresholds: Activation threshold vectors for each layer (standard ReLU uses zeros)

where T<:Union{Oscar.scalar_types, Rational{BigInt}}

Keyword Arguments

• quicksum::Bool=false: Use faster but less accurate quicksum operations for composition
• strong_elim::Bool=false: Apply monomial elimination to remove non-full-dimensional polyhedra at each layer
• dedup::Bool=false: Apply deduplication to remove duplicate monomials at each layer

Returns

• Vector{RationalSignomial{T}}: Tropical rational functions representing the MLP outputs

Throws

• DimensionMismatch: If matrix/vector dimensions don't match at any layer

Performance Notes

• quicksum=true: Faster for large networks (>3 layers, >10 neurons), defers sorting
• strong_elim=true: Reduces complexity by removing redundant monomials, but adds computational overhead
• dedup=true: Removes duplicate monomials, useful when composition creates duplicates

Examples

# Convert a random 2-3-1 MLP (standard)
W, b, t = random_mlp([2, 3, 1])
f = mlp_to_trop(W, b, t)

# Convert with quicksum for better performance
f_fast = mlp_to_trop(W, b, t, quicksum=true)

# Convert with monomial elimination for reduced complexity
f_reduced = mlp_to_trop(W, b, t, strong_elim=true)

# Combine options for large networks
f_optimized = mlp_to_trop(W, b, t, quicksum=true, strong_elim=true)

# Analyze linear regions
regions = enum_linear_regions_rat(f[1])

See Also

• single_to_trop: Convert a single layer
• comp, comp_with_quicksum: Composition functions
• monomial_strong_elim, dedup_monomials: Simplification functions

single_to_trop(A, b, t)

Convert a single ReLU layer to tropical Puiseux rational functions.

Arguments

• A::Matrix{T}: Weight matrix
• b::AbstractVector: Bias vector
• t::AbstractVector: Activation threshold vector

Returns

• Vector{RationalSignomial{T}}: Tropical representation of max(Ax+b, t)

Throws

• DimensionMismatch: If dimensions don't match (A has size(A,1) rows, b and t must have the same length)

random_mlp(dims; random_thresholds=false, symbolic=true)

Generate a random multilayer perceptron with specified architecture.

Arguments

• dims::AbstractVector{<:Integer}: Array of integers specifying the width of each layer (e.g., [2, 3, 1] for 2 inputs, 3 hidden neurons, 1 output)

Keyword Arguments

• random_thresholds::Bool=false: If true, activation thresholds are chosen randomly. If false, all thresholds are 0 (standard ReLU)
• symbolic::Bool=true: If true, use exact rational arithmetic (Rational{BigInt}). If false, use floating point

Returns

• Tuple{Vector{Matrix}, Vector{Vector}, Vector{Vector}}: (weights, biases, thresholds) for the MLP

Examples

# Create a 2-3-1 MLP with ReLU activations
W, b, t = random_mlp([2, 3, 1])

# Create with random thresholds using floating point
W, b, t = random_mlp([2, 4, 1], random_thresholds=true, symbolic=false)

random_pmap(n_vars, n_mons)

Returns a random tropical polynomial in n_vars variables with n_mons monomials.

Both coefficients and exponent components are drawn i.i.d. from Normal(0, 1/sqrt(2)). This distribution is consistent with the He initialisation used in random_mlp, where weights are sampled from Normal(0, sqrt(2/fan_in)).

Arguments

• n_vars::Integer: Number of variables in the tropical polynomial
• n_mons::Integer: Number of monomials

Returns

• Signomial{Rational{BigInt}}: A random tropical polynomial with n_mons monomials in n_vars variables, with coefficients and exponents drawn from Normal(0, 1/sqrt(2)) and converted to Rational{BigInt}

monomial_strong_elim(f::Signomial{T}; parallel::Bool=true)

Removes redundant monomials from a tropical Puiseux polynomial f.

A monomial is considered redundant if its corresponding polyhedron (the region where that monomial dominates) is not full-dimensional.

When parallel=true (default), uses multithreading to parallelize the full-dimensionality checks, which can provide significant speedup for polynomials with many monomials.

Arguments

• f::Signomial{T}: The polynomial to simplify
• parallel::Bool=true: Whether to use parallel computation

Returns

• Signomial{T}: A new polynomial with redundant monomials removed

Note

The parallel version requires Julia to be started with multiple threads (e.g., julia -t auto or JULIA_NUM_THREADS=4 julia).

monomial_strong_elim(f::RationalSignomial{T}; parallel::Bool=true)

Removes redundant monomials from both numerator and denominator of a tropical Puiseux rational function.

Arguments

• f::RationalSignomial{T}: The rational function to simplify
• parallel::Bool=true: Whether to use parallel computation

monomial_strong_elim(F::Vector{RationalSignomial{T}}; parallel::Bool=true)

Removes redundant monomials from a vector of tropical Puiseux rational functions.

Arguments

• F::Vector{RationalSignomial{T}}: The vector of rational functions to simplify
• parallel::Bool=true: Whether to use parallel computation

polyhedron(f::Signomial, i::Int)

Outputs the polyhedron corresponding to points where f is given by the linear map corresponding to the i-th monomial of f.

Example

Output the polyhedron where f = max(x, y) is equal to x

julia> f = Signomial(Dict([1, 0] => 0, [0, 1] => 0), [[1, 0], [0, 1]]);

julia> polyhedron(f, 1)
Polyhedron in ambient dimension 2 with Float64 type coefficients

enum_linear_regions(f::Signomial)

Outputs an array of tuples (poly, bool) indexed by the same set as the exponents of f. The tuple element poly is the linear region corresponding to the exponent, and bool is true when this region is nonemtpy.

Example

Enumerates the linear regions of f = max(x, y).

julia> f = Signomial(Dict([1, 0] => 0, [0, 1] => 0), [[1, 0], [0, 1]]);

julia> enum_linear_regions(f)
2-element Vector{Tuple{Oscar.Polyhedron{Float64}, Bool}}:
 (Polyhedron in ambient dimension 2 with Float64 type coefficients, 1)
 (Polyhedron in ambient dimension 2 with Float64 type coefficients, 1)

enum_linear_regions_rat(q::RationalSignomial)

Computes the linear regions of a tropical Puiseux rational function.

Arguments

• q::RationalSignomial: The rational function whose linear regions are computed.

Returns

A LinearRegions object whose regions field is a Vector{LinearRegion}. Each LinearRegion corresponds to one distinct affine linear map realised by q, and its regions field holds the full-dimensional convex polyhedra on which that map is attained. When the same linear map appears on several disconnected pieces, all pieces are collected in one LinearRegion.

Example

Enumerates the linear regions of f/g where f = max(x, y) and g = 0. f/g has two linear regions (one per monomial of f), each a single half-plane.

julia> f = Signomial(Dict([1, 0] => 0, [0, 1] => 0), [[1, 0], [0, 1]]);

julia> g = Signomial(Dict([0, 0] => 0), [[0, 0]]);

julia> lr = enum_linear_regions_rat(f / g);

julia> length(lr)
2

julia> length(lr[1].regions)
1

polyhedron_highs(f::Signomial, i::Int)

Outputs the (A, b) matrix representation of the polyhedron corresponding to points where f is given by the linear map corresponding to the i-th monomial of f.

Returns a tuple (A, b) where the polyhedron is {x : Ax ≤ b}.

Example

Output the polyhedron where f = max(x, y) is equal to x

julia> f = Signomial(Dict([1, 0] => 0, [0, 1] => 0), [[1, 0], [0, 1]]);

julia> A, b = polyhedron_highs(f, 1);

julia> size(A)
(2, 2)

enum_linear_regions_highs(f::Signomial; tol=HIGHS_DEFAULT_TOL)

Outputs an array of tuples ((A, b), bool) indexed by the same set as the exponents of f. The tuple element (A, b) is the matrix representation of the linear region corresponding to the exponent, and bool is true when this region is nonempty.

Uses HiGHS LP solver for fast feasibility checks.

Example

Enumerates the linear regions of f = max(x, y).

julia> f = Signomial(Dict([1, 0] => 0, [0, 1] => 0), [[1, 0], [0, 1]]);

julia> length(enum_linear_regions_highs(f))
2

enum_linear_regions_rat_highs(q::RationalSignomial; tol=HIGHS_DEFAULT_TOL)

Computes the linear regions of a tropical Puiseux rational function f/g using HiGHS.

Faster alternative to enum_linear_regions_rat: uses the HiGHS LP solver directly instead of building Oscar Polyhedron objects. The return type mirrors that of enum_linear_regions_rat — a LinearRegions object — so both backends can be used interchangeably. Each LinearRegion stores one or more (A, b) matrix pairs (instead of Oscar.Polyhedron objects) representing the convex pieces of that region.

Arguments

• q::RationalSignomial: The rational function whose linear regions are computed.
• tol: Numerical tolerance for LP feasibility and full-dimensionality checks.

Returns

A LinearRegions object. Each element is a LinearRegion whose regions field holds the (A, b) pairs (where the polyhedron is {x : Ax ≤ b}) making up that region.

components(V::Vector{T}, D::Dict{Tuple{T, T}, Bool})

Outputs an array representing the connected components of the graph given by the vertices V and the edges D (more precisely, the edges are given by the keys of D whose entries are "true").

Example

julia> V = [1, 2, 3, 4];

julia> D = Dict{Tuple{Int, Int}, Bool}((1, 2) => true, (3, 4) => true, (2, 3) => false);

julia> components(V, D)
2-element Vector{Vector{Int64}}:
 [1, 2]
 [3, 4]

map_statistic(statistic, f)

Applies a statistic function to a tropical polynomial or tropical rational map by calling the statistic on the corresponding linear regions.

Arguments

• statistic::Function: Function to apply to linear regions (e.g., length to count regions)
• f::Union{Signomial, RationalSignomial}: The tropical function to analyze

Returns

• Result of applying statistic to the identified linear regions

separate_components(linear_regions::Dict)

Separates linear regions into its disjoint components.

interior_points(polys::Array)

Returns an approximate interior point for each polyhedron in polys, computed as the centroid of the vertex set (i.e. the average of Oscar.vertices(poly)).

interior_points(linear_regions::Dict)

Returns interior points for the collection of polyhedron comprising linear regions.

interior_points(linear_regions::Dict)

Returns interior points for the collection of polyhedron comprising linear regions corresponding to the tropical polynomial or tropical rational map.

bounds(polys::Array)

Determines whether the polyhedra in a collection are bounded.

bounds(linear_regions::Dict)

Determines whether the polyhedra constituting linear regions are bounded.

bounds(f::Union{Signomial,RationalSignomial})

Determines whether the polyhedra constituting the linear region of a tropical polynomial or a tropical rational map are bounded.

volumes(polys::Array)

Finds the volumes of the polyhedra in a collection.

volumes(linear_regions::Dict)

Finds the volumes of the linear regions.

volumes(f::Union{Signomial,RationalSignomial})

Finds the volumes of the linear regions corresponding to the tropical polynomial or tropical rational map.

polyhedron_counts(linear_regions::Dict)

Returns the number of polyhedra in each linear region.

polyhedron_counts(f::Union{Signomial,RationalSignomial})

Returns the number of polyhedra in each linear region of the tropical polynomial or tropical rational map.

get_graph(linear_regions::Dict)

Constructs a graph from linear regions, where linear regions are connected if they share an edge.

get_graph(f::Union{Signomial,RationalSignomial})

Constructs a graph of linear regions corresponding to the tropical polynomial or tropical rational map.

edge_count(g::MetaGraph)

Counts the number of edges in a graph.

edge_count(f::Union{Signomial,RationalSignomial})

Counts the number of edges in the graph constructed from the linear regions of the corresponding tropical polynomial or tropical rational map.

edge_lengths(g::MetaGraph)

Calculate the lengths of the edges at the intersection of linear regions. Only returns the lengths of finite edges.

edge_lengths(f::Union{Signomial,RationalSignomial})

Calculates the lengths of the edges emanating from each vertex, along with providing the length of each unique edge, for the linear regions corresponding to the tropical polynomial or tropical rational map.

edge_directions(g::MetaGraph)

Calculate the direction vector of the edges at the intersection of linear regions.

edge_directions(f::Union{Signomial,RationalSignomial})

Calculate the direction vector of the edges at the intersection of linear regions for the corresponding tropical polynomial or tropical rational map.

edge_gradients(edge_attributes::Dict)

Identifies the gradients of the edges emanating from each vertex, along with providing the gradients of each unique edge.

edge_gradients(f::Union{Signomial,RationalSignomial})

Identifies the gradients of the edges emanating from each vertex, along with providing the gradients of each unique edge, for the linear regions corresponding to the tropical polynomial or tropical rational map.

vertex_collection(g::MetaGraph)

Collects the vertices of the linear regions, along with their multiplicities, that is, how many regions share that vertex.

vertex_collection(f::Union{Signomial,RationalSignomial})

Collects the vertices of the linear regions corresponding to the tropical polynomial or tropical rational map, along with their multiplicities, that is, how many regions share that vertex.

vertex_count(g::MetaGraph)

Counts the number of vertices in the linear regions from which the graph was obtained.

vertex_count(f::Union{Signomial,RationalSignomial})

Counts the number of vertices in the linear regions corresponding to the tropical polynomial or tropical rational map.

surjectivity_test(A::Matrix) -> (x_val, t_val)

Test whether the matrix A is A-surjective — a condition arising in Hoffman constant computation for tropical polynomials.

A matrix $\tilde{A}$ (a "tilde matrix" derived from the linear-map matrix $A$ via tilde_matrices) is A-surjective if the image of the positive orthant under $\tilde{A}^T$ intersects every open halfspace through the origin; equivalently, there is no direction in which all rows of $\tilde{A}$ have non-positive dot product. A-surjectivity is the precondition under which the Hoffman constant $H(\tilde{A})$ is finite (see exact_hoff).

The test solves the LP

min  t
s.t. ‖Aᵀx‖₁ ≤ t,  sum(x) = 1,  x ≥ 0

Arguments

• A::Matrix: A tilde matrix (typically one element of the vector returned by tilde_matrices).

Returns

• (x_val, t_val): the optimal primal variable x (a probability vector over the rows of A) and the optimal objective value t. If t_val > 0 the matrix is A-surjective and $H(\tilde{A}) = 1 / t_{\min}$ where $t_{\min}$ is the minimum over all feasible probability vectors; if t_val == 0 then A is not A-surjective and the Hoffman constant is infinite.

exact_hoff(A::Matrix)

Computes the Hoffman constant of the matrix A using a brute force approach.

exact_hoff(f::Union{Signomial,RationalSignomial};return_matrices::Bool=false)

Returns the exact value of the Hoffman constant of a given tropical polynomial or tropical rational map.

upper_hoff(A::Matrix)

Computes an upper bound on Hoffman constant of the matrix A by using the lowest singular value as a proxy for the optimal value of the optimisation problem for A-surjectivity.

upper_hoff(f::Union{Signomial,RationalSignomial};return_matrices::Bool=false)

Returns an upper bound on the exact value of the Hoffman constant of a given tropical polynomial or tropical rational map.

lower_hoff(A::Matrix,num_samples::Int=10)

Computes a lower bound on Hoffman constant of the matrix A by only considering a fixed number of random sub-matrices of A.

lower_hoff(f::Union{Signomial,RationalSignomial},num_samples::Int=10)

Returns a lower bound on the exact value of the Hoffman constant of a given tropical polynomial or tropical rational map.

exact_er(f::Signomial)

Provides an upper bound on the effective radius of a tropical polynomial using exact Hoffman constant computations.

exact_er(f::RationalSignomial)

Provides an upper bound on the effective radius of a tropical rational map using exact Hoffman constant computations.

upper_er(f::Signomial)

Provides an upper bound on the effective radius of a tropical polynomial using upper bound approximations of the Hoffman constant.

upper_er(f::RationalSignomial)

Provides an upper bound on the effective radius of a tropical rational map using upper bound approximations of the Hoffman constant.

linearmap_matrices(f::Signomial)

Returns the matrix of coefficients of the linear maps operating on the polyhedra of a tropical polynomial.

linearmap_matrices(f::RationalSignomial)

Returns the matrix of coefficients of the linear maps operating on the polyhedra of a tropical rational map.

tilde_matrices(A::Matrix)

Finds all of the transformed 'tilde' matrices whose Hoffman constants are considered when obtaining the Hoffman constant of the corresponding tropical polynomial.

tilde_matrices(As::Tuple{Matrix, Matrix})

Finds all of the transformed 'tilde' matrices whose Hoffman constants are considered when obtaining the Hoffman constant of the corresponding tropical rational map.

tilde_vectors(b::Vector)

Find the transformed vectors used to determine the effective radius of a tropical polynomial

positive_component(b::Vector)

Returns the vector with its negative entries set to zero.