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.
std::vector< std::string >	missingRoutes () const
	Names the routes this client calls that the service does not serve.
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
	Rewrites expressions into a normal form.
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
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) override
	Jacobian, LaTeX form and equilibria of a fluid vector field.
Public Member Functions inherited from line::sym::SymEngine
virtual	~SymEngine ()

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 201 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 209 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

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 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 370 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 405 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 437 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 466 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 475 of file sage_rest_engine.h.

◆ fluidODEs()

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

inlineoverridevirtual

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

Implements line::sym::SymEngine.

Definition at line 496 of file sage_rest_engine.h.

References line::sym::FluidODEs::equilibria, line::sym::FluidODEs::hasEquilibria, line::sym::FluidODEs::hasJacobian, line::sym::FluidODEs::hasLatex, line::sym::FluidODEs::jacobian, and line::sym::FluidODEs::latex.

◆ getBaseUrl()

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

inline

Returns: the base URL this engine posts to

Definition at line 235 of file sage_rest_engine.h.

◆ getTimeoutSeconds()

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

inline

Returns: the per-request timeout in seconds

Definition at line 232 of file sage_rest_engine.h.

◆ 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 311 of file sage_rest_engine.h.

Referenced by missingRoutes().

◆ isAvailable()

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

inlineoverridevirtual

True if the engine answers a health probe.

Implements line::sym::SymEngine.

Definition at line 239 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 264 of file sage_rest_engine.h.

References line::http::post_json().

◆ missingRoutes()

std::vector< std::string > line::sym::SageRestEngine::missingRoutes ( ) 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

Definition at line 330 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 237 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 226 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

Implements line::sym::SymEngine.

Definition at line 458 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 352 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 204 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()

◆ getBaseUrl()

◆ getTimeoutSeconds()

◆ info()

◆ isAvailable()

◆ isUsable()

◆ missingRoutes()

◆ name()

◆ setTimeoutSeconds()

◆ simplify()

◆ solveCTMC()

Member Data Documentation

◆ DEFAULT_TIMEOUT_SECONDS