Client of the line-sage-rest service. More...

#include <line/api/sym/sage_rest_engine.h>

Inheritance diagram for line::sym::SageRestEngine:

Collaboration diagram for line::sym::SageRestEngine:

Public Member Functions
	SageRestEngine (const std::string &baseUrl)
SageRestEngine &	setTimeoutSeconds (int seconds)
	Sets the per-request timeout.
int	getTimeoutSeconds () const
const std::string &	getBaseUrl () const
std::string	name () const override
	Name of the backing engine, e.g.
bool	isAvailable () const override
	True if the engine answers a health probe.
bool	isUsable () const
	Checks that the service can actually EVALUATE, not merely that it answers.
detail::Json	info () const
	Reads the service identity, used to tell a line-sage-rest server apart from another line-*-rest service on the same conventional port.
bool	hasFeature (const std::string &feature) const
	Names the routes this client calls that the service does not serve.
std::vector< std::string >	missingRoutes () const
CtmcSolution	solveCTMC (const std::vector< std::vector< std::string > > &Q, const std::vector< std::string > &symbols) override
	Symbolic stationary distribution of a CTMC, pi Q = 0 with sum(pi) = 1.
CtmcMeasures	ctmcMeasures (const std::vector< std::vector< std::string > > &Q, const std::vector< std::string > &symbols, const std::vector< std::vector< std::string > > &weights, const std::vector< std::string > &names, const std::vector< RatioSpec > &ratios) override
	Stationary distribution and a set of weighted sums of it.
Passage	ctmcPassage (const std::vector< std::vector< std::string > > &S, const std::vector< std::string > &s0, const std::vector< std::string > &alpha, const std::string &atom, const std::vector< std::string > &symbols, const std::string &svar, const std::vector< std::string > &want, int nmax) override
	First passage time into a target set: the transform and the moments.
SymSensitivity	ctmcSensitivity (const std::vector< std::vector< std::string > > &Q, const std::vector< std::string > &symbols, const std::string &theta, const std::vector< std::string > &reward) override
	Exact parametric sensitivity of a steady-state reward.
std::vector< std::string >	simplify (const std::vector< std::string > &exprs, const std::string &form) override
	Rewrites expressions into a normal form.
std::vector< std::string >	diff (const std::vector< std::string > &exprs, const std::string &variable, int order) override
	Differentiates expressions.
std::vector< double >	eval (const std::vector< std::string > &exprs, const std::map< std::string, double > &assignment) override
	Substitutes values for symbols and evaluates.
FluidODEs	fluidODEs (const std::vector< std::string > &rhs, const std::vector< std::string > &vars, const std::vector< std::string > &want, const std::vector< std::string > &constraints, const std::string &domain) override
	The /api/v1/fluid/odes call, constraints and domain included.
FluidODEs	fluidODEs (const std::vector< std::string > &rhs, const std::vector< std::string > &vars, const std::vector< std::string > &want)
	Jacobian, LaTeX form and equilibria of a fluid vector field.
Public Member Functions inherited from line::sym::SymEngine
virtual	~SymEngine ()
FluidODEs	fluidODEs (const std::vector< std::string > &rhs, const std::vector< std::string > &vars, const std::vector< std::string > &want)
	Jacobian, LaTeX form and equilibria of a fluid vector field.

Static Public Attributes
static constexpr int	DEFAULT_TIMEOUT_SECONDS = 300
	Default per-request timeout, in seconds.

Detailed Description

Client of the line-sage-rest service.

Definition at line 202 of file sage_rest_engine.h.

Constructor & Destructor Documentation

◆ SageRestEngine()

line::sym::SageRestEngine::SageRestEngine ( const std::string & baseUrl )

inlineexplicit

Parameters

baseUrl base URL of the service, e.g. "http://localhost:8080"

Definition at line 210 of file sage_rest_engine.h.

References DEFAULT_TIMEOUT_SECONDS, and line::InputError::InputError().

Referenced by setTimeoutSeconds().

Member Function Documentation

◆ ctmcMeasures()

CtmcMeasures line::sym::SageRestEngine::ctmcMeasures	(	const std::vector< std::vector< std::string > > &	Q,
		const std::vector< std::string > &	symbols,
		const std::vector< std::vector< std::string > > &	weights,
		const std::vector< std::string > &	names,
		const std::vector< RatioSpec > &	ratios )

inlineoverridevirtual

Stationary distribution and a set of weighted sums of it.

Every mean SolverCTMC reports is a NUMERIC linear functional of pi, so the caller builds one weight vector per measure with no algebra at all and this one round trip returns each w . pi as a rational function: a throughput is pi . depRates, a queue length is pi . stateSpaceAggr, a marginal probability is pi . indicator and a mean reward is pi . r.

Parameters

Q	generator entries as expression strings, row major
symbols	the symbols appearing in Q
weights	one row per measure, each of length Q.size(); entries are parsed in the same field as Q, so an expression is admissible and not only a number
names	a name per weight row, or empty for w0, w1, ...
ratios	ratios of two measures, or empty for none

Implements line::sym::SymEngine.

Definition at line 390 of file sage_rest_engine.h.

References line::sym::CtmcMeasures::connComp, line::sym::CtmcMeasures::den, line::sym::CtmcMeasures::measures, line::sym::CtmcMeasures::nConnComp, line::sym::CtmcMeasures::num, line::sym::CtmcMeasures::pi, and line::sym::CtmcMeasures::ratios.

◆ ctmcPassage()

Passage line::sym::SageRestEngine::ctmcPassage	(	const std::vector< std::vector< std::string > > &	S,
		const std::vector< std::string > &	s0,
		const std::vector< std::string > &	alpha,
		const std::string &	atom,
		const std::vector< std::string > &	symbols,
		const std::string &	svar,
		const std::vector< std::string > &	want,
		int	nmax )

inlineoverridevirtual

First passage time into a target set: the transform and the moments.

With A the complement of the target, S = Q(A,A) the sub-generator, s0 = -S*1 the exit vector and alpha the initial law restricted to A, following Harrison and Knottenbelt (2002),

L(s) = alpha (sI - S)^-1 s0 + atom        Eqs. 1-2
(-S) M(n) = n M(n-1),  M(0) = 1           Eq. 3

THE MOMENTS COME FROM THE RECURSION, not from differentiating L: it carries no transform symbol, stays in the same fraction field and is nmax right solves against one matrix. Differentiating would leave the fraction field, and the evaluation at s = 0 can hit 0/0 where a factor of s failed to cancel.

Parameters

S	the sub-generator on the non-target states, row major
s0	the exit vector -S*1
alpha	the initial law restricted to the non-target states
atom	the initial mass already inside the target set
symbols	the rate symbols appearing in S
svar	the transform symbol; adjoined to the field only when a transform is asked for, and required to differ from every rate symbol
want	any of lst, lstall, moments, momall
nmax	highest moment order, at least 1

Implements line::sym::SymEngine.

Definition at line 425 of file sage_rest_engine.h.

References line::sym::Passage::lst, line::sym::Passage::lstAll, line::sym::Passage::lstDen, line::sym::Passage::lstNum, line::sym::Passage::momAll, line::sym::Passage::moments, and line::sym::Passage::unreachable.

◆ ctmcSensitivity()

SymSensitivity line::sym::SageRestEngine::ctmcSensitivity	(	const std::vector< std::vector< std::string > > &	Q,
		const std::vector< std::string > &	symbols,
		const std::string &	theta,
		const std::vector< std::string > &	reward )

inlineoverridevirtual

Exact parametric sensitivity of a steady-state reward.

Parameters

Q	generator entries as expression strings, row major
symbols	the symbols appearing in Q
theta	the symbol to differentiate with respect to
reward	reward rate per state, empty for the distribution alone

Returns: the sensitivity of the distribution and, if a reward is given, of its mean

Implements line::sym::SymEngine.

Definition at line 457 of file sage_rest_engine.h.

References line::sym::SymSensitivity::dpi, line::sym::SymSensitivity::Er, line::sym::SymSensitivity::hasReward, line::sym::SymSensitivity::pi, line::sym::SymSensitivity::S, and line::sym::SymSensitivity::SS.

◆ diff()

std::vector< std::string > line::sym::SageRestEngine::diff	(	const std::vector< std::string > &	exprs,
		const std::string &	variable,
		int	order )

inlineoverridevirtual

Differentiates expressions.

Parameters

exprs	the expressions
variable	the differentiation variable
order	the order of the derivative, at least 1

Returns: the derivatives, in the input order

Implements line::sym::SymEngine.

Definition at line 486 of file sage_rest_engine.h.

◆ eval()

std::vector< double > line::sym::SageRestEngine::eval	(	const std::vector< std::string > &	exprs,
		const std::map< std::string, double > &	assignment )

inlineoverridevirtual

Substitutes values for symbols and evaluates.

Parameters

exprs	the expressions
assignment	value of each symbol

Returns: the numeric values, NaN where a free symbol remains

Implements line::sym::SymEngine.

Definition at line 495 of file sage_rest_engine.h.

◆ fluidODEs() [1/2]

FluidODEs line::sym::SymEngine::fluidODEs	(	const std::vector< std::string > &	rhs,
		const std::vector< std::string > &	vars,
		const std::vector< std::string > &	want )

inline

Jacobian, LaTeX form and equilibria of a fluid vector field.

Parameters

rhs	the right hand side of dx/dt, one expression per state variable
vars	the state variable names
want	any of jacobian, latex, equilibria

Returns: the requested items

Definition at line 262 of file sym_engine.h.

◆ fluidODEs() [2/2]

FluidODEs line::sym::SageRestEngine::fluidODEs	(	const std::vector< std::string > &	rhs,
		const std::vector< std::string > &	vars,
		const std::vector< std::string > &	want,
		const std::vector< std::string > &	constraints,
		const std::string &	domain )

inlineoverridevirtual

The /api/v1/fluid/odes call, constraints and domain included.

A SERVICE OLDER THAN 1.1.0 IGNORES constraints, and a closed model's equilibria then form a continuum that it never finishes solving: the call would reach the caller as a timeout. So constrained equilibria are asked for only of a service whose /api/v1/info lists fluid_odes_constraints, and an older image is refused by name, as the Python client does.

Implements line::sym::SymEngine.

Definition at line 527 of file sage_rest_engine.h.

References line::sym::FluidODEs::equilibria, line::sym::FluidODEs::hasEquilibria, hasFeature(), line::sym::FluidODEs::hasJacobian, line::sym::FluidODEs::hasLatex, line::sym::FluidODEs::jacobian, line::sym::FluidODEs::latex, and line::sym::SymEngineError::SymEngineError().

◆ getBaseUrl()

const std::string & line::sym::SageRestEngine::getBaseUrl ( ) const

inline

Returns: the base URL this engine posts to

Definition at line 236 of file sage_rest_engine.h.

◆ getTimeoutSeconds()

int line::sym::SageRestEngine::getTimeoutSeconds ( ) const

inline

Returns: the per-request timeout in seconds

Definition at line 233 of file sage_rest_engine.h.

◆ hasFeature()

bool line::sym::SageRestEngine::hasFeature ( const std::string & feature ) const

inline

Names the routes this client calls that the service does not serve.

A SERVICE CAN BE HEALTHY AND STILL TOO OLD, and that case used to reach the caller as a request failure rather than as a resolution failure. The roster ran a line-sage-rest image predating the ctmc/measures and ctmc/passage routes on 2026-09-11: it answered /api/v1/health, passed the isUsable arithmetic canary, and then failed every call to those routes with unknown endpoint /api/v1/ctmc/measures – an error that reads as a defect in the solver rather than as an out-of-date container. /api/v1/info lists what the running server actually routes, so asking it turns that into a named refusal at resolution time.

Returns: the missing routes; empty when the service serves them all, and empty when it is too old to report its route list at all, which leaves the request itself to fail as before True when /api/v1/info lists feature among the service's capabilities.

The route list cannot say this: a 1.0.0 image serves /api/v1/fluid/odes and silently drops the constraints field, so the capability is advertised by name in features, which an older service does not carry.

Parameters

feature a capability name, e.g. "fluid_odes_constraints"

Returns: false as well when the service reports no feature list at all

Definition at line 341 of file sage_rest_engine.h.

References info().

Referenced by fluidODEs().

◆ info()

detail::Json line::sym::SageRestEngine::info ( ) const

inline

Reads the service identity, used to tell a line-sage-rest server apart from another line-*-rest service on the same conventional port.

Returns: the /api/v1/info document

Definition at line 312 of file sage_rest_engine.h.

Referenced by hasFeature(), and missingRoutes().

◆ isAvailable()

bool line::sym::SageRestEngine::isAvailable ( ) const

inlineoverridevirtual

True if the engine answers a health probe.

Implements line::sym::SymEngine.

Definition at line 240 of file sage_rest_engine.h.

◆ isUsable()

bool line::sym::SageRestEngine::isUsable ( ) const

inline

Checks that the service can actually EVALUATE, not merely that it answers.

The line-sage-rest image ships a FLINT built for CPUs that have BMI2 and ADX. On an older host the first multi-limb exact operation raises SIGILL, the worker dies mid-request and the call returns no bytes at all; /api/v1/health is pure Python and keeps answering, so it cannot see this. The canary is the weighted-average softmin form, which is what the fluid export actually sends, and is the smallest expression observed to trigger it. Verdicts are cached per URL, so this costs one small request the first time a service is considered and nothing after. See _kb/11-conventions-and-gotchas.md.

Returns: true if the service returned the canary's value

Definition at line 265 of file sage_rest_engine.h.

References line::http::post_json().

◆ missingRoutes()

std::vector< std::string > line::sym::SageRestEngine::missingRoutes ( ) const

inline

Definition at line 350 of file sage_rest_engine.h.

References info().

◆ name()

std::string line::sym::SageRestEngine::name ( ) const

inlineoverridevirtual

Name of the backing engine, e.g.

"sage".

Implements line::sym::SymEngine.

Definition at line 238 of file sage_rest_engine.h.

◆ setTimeoutSeconds()

SageRestEngine & line::sym::SageRestEngine::setTimeoutSeconds ( int seconds )

inline

Sets the per-request timeout.

Parameters

seconds timeout in seconds; not positive disables it

Returns: this engine

Definition at line 227 of file sage_rest_engine.h.

References SageRestEngine().

Referenced by line::fluid::fluid_jacobian().

◆ simplify()

std::vector< std::string > line::sym::SageRestEngine::simplify	(	const std::vector< std::string > &	exprs,
		const std::string &	form )

inlineoverridevirtual

Rewrites expressions into a normal form.

Parameters

exprs	the expressions
form	one of simplify, factor, together, cancel, expand, latex

Returns: the rewritten expressions, in the input order

Implements line::sym::SymEngine.

Definition at line 478 of file sage_rest_engine.h.

◆ solveCTMC()

CtmcSolution line::sym::SageRestEngine::solveCTMC	(	const std::vector< std::vector< std::string > > &	Q,
		const std::vector< std::string > &	symbols )

inlineoverridevirtual

Symbolic stationary distribution of a CTMC, pi Q = 0 with sum(pi) = 1.

Parameters

Q	generator entries as expression strings, row major and square
symbols	the symbols appearing in Q, e.g. x1..xE

Returns: the solution, with pi also split over a common denominator

Implements line::sym::SymEngine.

Definition at line 372 of file sage_rest_engine.h.

References line::sym::CtmcSolution::connComp, line::sym::CtmcSolution::den, line::sym::CtmcSolution::nConnComp, line::sym::CtmcSolution::num, and line::sym::CtmcSolution::pi.

Member Data Documentation

◆ DEFAULT_TIMEOUT_SECONDS

int line::sym::SageRestEngine::DEFAULT_TIMEOUT_SECONDS = 300

staticconstexpr

Default per-request timeout, in seconds.

Definition at line 205 of file sage_rest_engine.h.

Referenced by SageRestEngine().

The documentation for this class was generated from the following file:

include/line/api/sym/sage_rest_engine.h

Public Member Functions

Static Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ SageRestEngine()

Member Function Documentation

◆ ctmcMeasures()

◆ ctmcPassage()

◆ ctmcSensitivity()

◆ diff()

◆ eval()

◆ fluidODEs() [1/2]

◆ fluidODEs() [2/2]

◆ getBaseUrl()

◆ getTimeoutSeconds()

◆ hasFeature()

◆ info()

◆ isAvailable()

◆ isUsable()

◆ missingRoutes()

◆ name()

◆ setTimeoutSeconds()

◆ simplify()

◆ solveCTMC()

Member Data Documentation

◆ DEFAULT_TIMEOUT_SECONDS