API Reference

Signomial{T,C}

Max-plus tropical signomial. T is the exponent type, and C is the tropical coefficient type.

Use convert(Signomial{S}, f) to convert the exponent type of f to S.

Fields

• exp: Exponent matrix with one exponent vector per column.
• coeff: Coefficients in the same order as the exponent columns.
• dim: Number of variables.

RationalSignomial{T,C}

Tropical rational function represented by a quotient of two signomials. T is the exponent type, and C is the tropical coefficient type.

Use convert(RationalSignomial{S}, f) to convert the exponent type of f to S.

AbstractNeuralNetworkLayer{T}

Abstract type for neural-network layers with scalar type T.

AffineLayer(weight, bias)

Store the affine layer x -> weight * x + bias. The weight and bias element types must be T. The number of weight rows must equal the bias length.

ActivationLayer(activations...)
ActivationLayer(activations)
ActivationLayer(activation, repeats)

Store a layer of tropical rational activations. Split the layer input into consecutive segments, one segment for each activation. The length of a segment is the number of variables in its activation. Each activation returns one scalar. All activations must use scalar type T. Use repeats to apply one activation to multiple consecutive segments.

NeuralNetwork(layers...)
NeuralNetwork(layers)

Store an ordered tuple of compatible neural-network layers. All layers must use scalar type T. The network must contain at least one layer. The output dimension of each layer must equal the input dimension of the next layer. A network is also a layer and can contain another network.

Cell(A, b, matrix, offset)

One affine cell of a tropical signomial or rational signomial. The inequalities A * x <= b define the cell. On the cell, the function is matrix * x + offset.

LinearRegion{C}

One linear region of a tropical signomial or rational signomial. A linear region can contain more than one affine cell.

LinearRegions{C}

Result of linear_regions. Each element is a LinearRegion.

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

Construct the constant c in n variables. Use f to infer the exponent type.

signomial_zero(n, f::Signomial)

Construct tropical zero in n variables. Use f to infer the types.

signomial_one(n, f::Signomial)

Construct tropical one in n variables. Use f to infer the types.

signomial_monomial(c, exp::AbstractVector{T})

Construct a one-monomial signomial with coefficient c and exponent exp. exp can be any AbstractVector. The constructor copies it.

signomial_to_rational(f::Signomial)

Return f as a RationalSignomial with denominator equal to tropical one.

rational_signomial_identity(n, c)

Return the coordinate projections [x₁, x₂, …, xₙ]. Use c to infer the coefficient type.

rational_signomial_zero(n, f::RationalSignomial)

Construct tropical zero in n variables. Use f to infer the types.

rational_signomial_one(n, f::RationalSignomial)

Construct tropical one in n variables. Use f to infer the types.

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

Evaluate f at point a. a can be any AbstractVector of suitable scalars.

evaluate(f::RationalSignomial, a::AbstractVector)

Evaluate f at point a. a can be any AbstractVector of suitable scalars.

evaluate(F::AbstractVector{<:RationalSignomial}, a::AbstractVector)

Evaluate each function in F at point a. F and a can be any suitable AbstractVector values.

quicksum(F::AbstractVector{<:RationalSignomial})

Return the tropical sum of F. F can be any AbstractVector of rational signomials.

comp(f::Signomial, G::AbstractVector{<:Signomial}; quicksum=false)

Substitute G[i] for variable i in f. Set quicksum=true to batch the intermediate tropical sums.

Throw ArgumentError if f has a negative exponent. Convert G to rational signomials explicitly to compose such an f.

comp(f::Signomial, G::AbstractVector{<:RationalSignomial}; quicksum=false)

Substitute G[i] for variable i in f. Set quicksum=true to batch the intermediate tropical sums.

comp(f::RationalSignomial, G::AbstractVector{<:RationalSignomial}; quicksum=false)

Substitute G[i] for variable i in f. Set quicksum=true to batch the intermediate tropical sums.

comp(F::AbstractVector{<:RationalSignomial}, G::AbstractVector{<:RationalSignomial}; quicksum=false)

Substitute G into each element of F. Set quicksum=true to batch the intermediate tropical sums.

single_to_trop(A, b, t)

Convert x -> max.(A * x + b, t) to tropical rational functions.

The lengths of b and t must equal size(A, 1). A can be any AbstractMatrix with a supported element type.

tropicalize(linear_maps, bias, thresholds;
            quicksum=false, prune=false, dedup=false,
            elim_mode=OscarMode(), workers=nothing)

Convert an MLP with an affine output layer to tropical rational functions. Each hidden layer applies max.(z, thresholds[i]). Omit thresholds to use ReLU. The keywords control batched sums and pruning. Set dedup=true to remove terms whose coefficient is tropical zero. linear_maps can be an AbstractVector of AbstractMatrix values. The bias and threshold collections can also be abstract vectors.

mlp_to_trop is a deprecated alias for this function.

tropicalize(layer::AbstractNeuralNetworkLayer;
            quicksum=false, prune=false, dedup=false,
            elim_mode=OscarMode(), workers=nothing)

Convert a neural-network layer or network to tropical rational functions. The keywords control batched sums and pruning. Set dedup=true to remove terms whose coefficient is tropical zero.

tropicalize_layers(layer::AbstractNeuralNetworkLayer)

Return the uncomposed tropical rational map for each atomic layer in layer. Each element is a vector-valued map. Nested networks are flattened.

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

Return random (weights, biases, thresholds) for architecture dims. If random_thresholds=false, all thresholds are zero. If symbolic=true, convert the generated values to Rational{BigInt}.

random_maxout_network(dims, pieces, [T=Float64])

Return a random maxout network with architecture dims. Each hidden width in dims specifies the number of maxout units in that layer. Each unit has pieces affine inputs. Sample each affine weight and bias from a normal distribution with standard deviation sqrt(2 / fan-in). Store the samples with element type T.

random_signomial(n_vars, n_mons)

Return a random Signomial with n_vars variables and n_mons terms. Sample coefficients and exponents from a normal distribution with standard deviation 1 / sqrt(2). Convert them to Rational{BigInt}.

prune(f::Signomial{T};
      parallel::Bool=true, workers=nothing,
      mode::LinearRegionsCalculationMode=OscarMode())

Return a copy of f without monomials whose dominance polyhedron is not full-dimensional. mode selects the polyhedral backend. If parallel=true and workers is an AbstractWorkerPool, the checks run on those processes.

prune(f::RationalSignomial{T};
      parallel::Bool=true, workers=nothing,
      mode::LinearRegionsCalculationMode=OscarMode())

Return a copy of f with its numerator and denominator pruned independently.

Arguments

• f::RationalSignomial{T}: Rational function to prune.
• parallel=true: Permit parallel checks.
• workers=nothing: Optional Julia worker pool.
• mode=OscarMode(): Backend for full-dimensionality checks.

prune(F::AbstractVector{<:RationalSignomial};
      parallel::Bool=true, workers=nothing,
      mode::LinearRegionsCalculationMode=OscarMode())

Prune each rational function in F.

Arguments

• F::AbstractVector{<:RationalSignomial}: Rational functions to prune.
• parallel=true: Permit parallel checks.
• workers=nothing: Optional Julia worker pool.
• mode=OscarMode(): Backend for full-dimensionality checks.

relu()
relu(T)

Return x -> max(0, x) as a RationalSignomial. Use exponent type T. The default type is Rational{BigInt}.

leaky_relu([slope=1 // 100])

Return x -> max(slope * x, x) as a RationalSignomial. The exponent type is typeof(slope). The slope must be in the closed interval [0, 1].

maxout(input_dimension)
maxout(T, input_dimension)

Return (x₁, ..., xₙ) -> max(x₁, ..., xₙ) as a RationalSignomial, where n is input_dimension. Use exponent type T. The default type is Rational{BigInt}. The input dimension must be positive.

identity_activation()
identity_activation(T)

Return x -> x as a RationalSignomial. Use exponent type T. The default type is Rational{BigInt}.

input_dimension(layer)

Return the number of inputs accepted by a neural-network layer or network.

output_dimension(layer)

Return the number of outputs produced by a neural-network layer or network.

OscarMode()

Use Oscar polyhedra and exact rational constraints.

HiGHSMode(; tol=HIGHS_DEFAULT_TOL, solver=HIGHS_DEFAULT_SOLVER, threads=nothing)

Use JuMP and HiGHS with Float64 constraints. tol is the distance tolerance for region checks, in input-space units. A region is full dimensional only if its Chebyshev inradius is greater than tol. threads sets the optional HiGHS thread count.

linear_regions(f::Signomial; mode, workers=nothing)

Return the linear regions of f.

linear_regions(f::AbstractVector{<:Signomial}; mode, workers=nothing)

Return the linear regions of f.

linear_regions(q::AbstractVector{<:RationalSignomial}; mode, workers=nothing)

Return the linear regions of q.

linear_regions(q::RationalSignomial; mode, workers=nothing)

Return the linear regions of scalar function q.

linear_regions(layers; mode, workers=nothing)

Return the linear regions for a sequence of rational signomial maps. Each vector in layers defines one map. The function applies the maps in order. It does not construct their complete composition.

linear_regions(network::NeuralNetwork; mode, workers=nothing)

Return the linear regions of network, computed layerwise.

linear_regions(linear_maps, biases, thresholds=nothing;
               mode, workers=nothing)

Return the linear regions of an MLP (given by arrays containing the weight matrices, the biases, and the thresholds for each layer), computed layerwise. This is a legacy method, and nowadays using the NeuralNetwork API is preferred.

interior_points(polys::Array)

Return the finite-vertex centroid of each polyhedron. Return nothing when a polyhedron has no vertices.

interior_points(linear_regions::Dict)

Return finite-vertex centroids for the polyhedra in linear_regions.

interior_points(f::Union{Signomial,RationalSignomial};
                mode::LinearRegionsCalculationMode=OscarMode())

Return finite-vertex centroids for the linear-region polyhedra of f.

bounds(polys::Array)

Check boundedness for each polyhedron in polys.

bounds(linear_regions::Dict)

Check boundedness for all polyhedra in linear_regions.

bounds(f::Union{Signomial,RationalSignomial};
       mode::LinearRegionsCalculationMode=OscarMode())

Check boundedness for the linear regions of f.

volumes(polys::Array)

Return each polyhedron's Float64 volume. Return Inf for an unbounded polyhedron.

volumes(linear_regions::Dict)

Return one volume for each linear region by summing the volumes of the (full-dimensional) polyhedra that it the union of.

volumes(f::Union{Signomial,RationalSignomial};
        mode::LinearRegionsCalculationMode=OscarMode())

Return the volumes of the linear regions of f.

polyhedron_counts(linear_regions::Dict)

Return the number of convex pieces in each linear region.

polyhedron_counts(f::Union{Signomial,RationalSignomial};
                  mode::LinearRegionsCalculationMode=OscarMode())

Return the number of convex pieces in each linear region of f.

edge_count(f::Union{Signomial,RationalSignomial};
           mode::LinearRegionsCalculationMode=OscarMode())

Return the number of adjacencies between the two-dimensional linear regions of f. This only supports bivariate expressions f.

edge_lengths(f::Union{Signomial,RationalSignomial};
             mode::LinearRegionsCalculationMode=OscarMode())

Return the finite boundary lengths between two-dimensional linear regions of f.

edge_directions(f::Union{Signomial,RationalSignomial};
                mode::LinearRegionsCalculationMode=OscarMode())

Return normalized boundary directions for the two-dimensional linear regions of f.

edge_gradients(f::Union{Signomial,RationalSignomial};
               mode::LinearRegionsCalculationMode=OscarMode())

Return the slopes of the boundaries between two-dimensional linear regions of f.

vertex_collection(f::Union{Signomial,RationalSignomial};
                  mode::LinearRegionsCalculationMode=OscarMode())

Return finite vertices and occurrence counts at linear-region adjacencies.

vertex_count(f::Union{Signomial,RationalSignomial};
             mode::LinearRegionsCalculationMode=OscarMode())

Return the number of distinct finite vertices found at region adjacencies.

hoffman_constant(A::AbstractMatrix; brute_force=false, tol=1e-10)

Compute the infinity-norm Hoffman constant of A. By default, use the Peña–Vera–Zuluaga algorithm. Set brute_force=true to test every nonempty row subset instead. Both algorithms solve floating-point LPs with GLPK. A can be any AbstractMatrix supported by the linear algebra operations.

hoffman_constant(f::Union{Signomial,RationalSignomial};
                 brute_force=false, mode=OscarMode(), tol=1e-10)

Compute the Hoffman constant of f. By default, use the Peña–Vera–Zuluaga algorithm. Set brute_force=true to use exhaustive subset enumeration. mode selects the cell-check backend.

upper_hoffman_constant(A::AbstractMatrix)

Return the largest sqrt(length(J)) / minimum(svdvals(A[J, :])) over nonempty row subsets J with length(J) <= min(m, n) and rank(A[J, :]) == length(J), where m, n = size(A). A can be any suitable AbstractMatrix.

upper_hoffman_constant(f::Union{Signomial,RationalSignomial}; mode=OscarMode())

Return an upper bound for hoffman_constant.

lower_hoffman_constant(A::AbstractMatrix, num_samples::Int=10; tol=1e-10)

Return a lower bound from num_samples random nonempty row subsets. If num_samples >= 2^m, compute the exact value with brute force. A can be any suitable AbstractMatrix.

lower_hoffman_constant(f::Union{Signomial,RationalSignomial},
                       num_samples::Int=10; mode=OscarMode(), tol=1e-10)

Return a sampled lower bound for hoffman_constant.

exact_er(f::Signomial; brute_force=false, mode=OscarMode())

Return an infinity-norm effective-radius bound using hoffman_constant.

exact_er(f::RationalSignomial; brute_force=false, mode=OscarMode())

Return an infinity-norm effective-radius bound using hoffman_constant.

upper_er(f::Signomial; mode=OscarMode())

Return an infinity-norm effective-radius bound using upper_hoffman_constant.

upper_er(f::RationalSignomial; mode=OscarMode())

Return an infinity-norm effective-radius bound using upper_hoffman_constant.