Package jline.solvers.fluid

Class SolverFluid

java.lang.Object
jline.solvers.Solver
jline.solvers.NetworkSolver
jline.solvers.fluid.SolverFluid
Direct Known Subclasses:
FLD, Fluid, SolverFLD
public class SolverFluid extends NetworkSolver
FLD - Fluid/Mean-Field Approximation solver. SolverFluid is based on fluid and mean-field approximation methods. It provides fluid-based analysis for queueing networks, particularly useful for large-scale systems where discrete-event simulation would be computationally expensive.

  • Constructor Details

    • SolverFluid

      public SolverFluid(Network model)
      Creates a new SolverFluid instance with default options.
      Parameters:
      model - The network model to analyze

    • SolverFluid

      public SolverFluid(Network model, Object... varargin)
      Creates a new SolverFluid instance with variable arguments for options.
      Parameters:
      model - The network model to analyze
      varargin - Variable arguments for solver options

    • SolverFluid

      public SolverFluid(Network model, NetworkSolver initSolver, Object... varargin)
      Creates a new SolverFluid that warm-starts the ODE integration from the steady-state solution of an auxiliary solver (see NetworkSolver.initFromSolver(jline.solvers.NetworkSolver)).
      Parameters:
      model - The network model to analyze
      initSolver - auxiliary solver used to compute the steady-state distribution
      varargin - Variable arguments for solver options

    • SolverFluid

      public SolverFluid(Network model, String method)
      Creates a new SolverFluid instance with a specific method.
      Parameters:
      model - The network model to analyze
      method - The fluid analysis method to use

    • SolverFluid

      public SolverFluid(Network model, SolverOptions options)
      Creates a new SolverFluid instance with specific options.
      Parameters:
      model - The network model to analyze
      options - The solver options to use

  • Method Details

    • defaultOptions

      public static SolverOptions defaultOptions()
      Returns the default solver options for the Fluid solver.
      Returns:
      Default solver options with SolverType.FLUID

    • getFeatureSet

      public static FeatureSet getFeatureSet()
      Returns the feature set supported by the Fluid solver
      Returns:
      - the feature set supported by the Fluid solver

    • getMethodFeatureSet

      public FeatureSet getMethodFeatureSet(String method)
      Per-method feature envelope, mirroring the MATLAB SolverFLD.getMethodFeatureSet.

      Defining this is what lets the solver gate name the offending features: with no method feature set the check falls back to the coarse supports(model), which returns an empty reason, so a rejection could only say "features not supported" without saying which ones.

      Overrides:
      getMethodFeatureSet in class Solver
      Parameters:
      method - the concrete method name
      Returns:
      the features that method accepts

    • supportsModelMethod

      public String supportsModelMethod(String method)
      The structural finite-capacity gate runAnalyzer enforces at solve time, stated here so that a CALLER can see it before running.

      Nothing in the fluid tree reads sn.cap or sn.classcap, so every method but two integrates a capped station as an unbounded one. "dae" carries the buffer as an algebraic constraint on the drift, and "mol" is stated for the Mt/G/s/0 LOSS system, where the server count IS the buffer. There is no registry feature name for plain capacity, hence the structural test; SolverNC and SolverMVA gate the same way. The exemption list is the one runAnalyzer applies, so the two cannot disagree.

      Left only in runAnalyzer the rule was invisible to every gate above it, and SolverAUTO.listValidMethods offered every fluid method on the BAS-blocking model of cqn_bas_blocking, each of which then threw when asked to run.

      Overrides:
      supportsModelMethod in class Solver
      Parameters:
      method - the concrete method name
      Returns:
      empty string if supported, else the offending reason

    • blockedResolvesToDae

      public static boolean blockedResolvesToDae(Network model, NetworkStruct sn, SolverOptions options)
      Does options.method = "default" stand for "dae" on this model? True exactly when a buffer or a capacity region BINDS and the DAE route accepts the model.

      A BINDING BUFFER OR A REGION HAS ONE FLUID ROUTE, for the same reason a Petri net does: nothing else in the fluid tree reads sn.cap, sn.classcap or the region limit, so every other method integrates the capped station as an unbounded one -- which is why runAnalyzer refuses them. Resolving "default" to one of those turned a model this solver CAN answer into an error whose advice was to type the very method the resolution should have picked.

      The capacity test is the gate's own, so the two cannot disagree. Where the DAE route declines, this returns false and the gate speaks, naming the blocking feature. Mirrors the MATLAB fluid_resolve_default_method.

      Parameters:
      model - the network
      sn - its struct
      options - the solver options, for the dae applicability limits
      Returns:
      true when "default" must resolve to "dae"

    • fluidUnqualify

      public static String fluidUnqualify(String method)
      The method name without its fluid. prefix, which names the same method, with butools and aoi folded onto mfq: they name the MFQ branch's backend and its age-of-information reading rather than methods of their own, which is how native python spells them and how getAvgAoI reaches it (it requires method='mfq').
      Parameters:
      method - the requested method name
      Returns:
      the canonical spelling

    • forkJoinAdmitsReason

      public static String forkJoinAdmitsReason(NetworkStruct sn, String method)
      Can method run the fluid fork-join fixed point on this model?

      A fork-join model is not integrated as one drift: the MMT transform replaces the fork by auxiliary classes and the answer is the fixed point of solving that transformed model repeatedly. On a CLOSED model the transform stays closed and every fluid method takes it. On an OPEN one the auxiliary classes arrive at a Source, and the DAE form has no unknowns for them: the inner solve fails on the class count rather than returning a drift, so the method is refused by name instead.

      "refined" is NOT listed here even though it fails the same way, because it is already refused on every open model, fork-join or not, by its own closed-model restriction (see getMethodFeatureSet(java.lang.String)).

      Called by runAnalyzer, so the run stops on it, and by supportsModelMethod(java.lang.String), so a caller sees the same verdict before paying for the fixed point. One predicate, two callers.

      Parameters:
      sn - the network structure
      method - the concrete method name
      Returns:
      empty string when the method may run the fixed point here, else the refusal

    • canonicalMethod

      public static String canonicalMethod(String method)
      The one spelling of a fluid method that every gate tests against.

      Three families of alias reach this solver and they used to be expanded by hand at each branch, which is why the four codebases drifted apart: a fluid. qualifier the dispatch accepts on every name, the MFQ backend aliases butools and aoi, and the short spellings ggisgi and tga of the two single-station limits. Canonicalizing once is what makes an alias carry the same feature envelope as the name it resolves to; MATLAB SolverFLD.canonicalMethod, native python and C++ apply the same three rules in the same order.

      Parameters:
      method - the method name as the caller spelled it
      Returns:
      the canonical spelling

    • getTranAvg

      public void getTranAvg()
      Computes transient average station metrics, tracking any non-homogeneous (NHPP) arrival intensity over the timespan.

      The NHPP schedules of the Source stations are injected into options.config.nhpp_sched, so that the closing ODE follows lambda(t) rather than the baked-in time-average rate. Steady-state getAvg is unaffected (no schedule is injected there), consistent with defining the NHPP steady state as its time average; the injected schedule is removed again on return. Mirrors MATLAB SolverFLD/getTranAvg.m.

      Overrides:
      getTranAvg in class NetworkSolver

    • getCdfRespT

      public Ret.DistributionResult getCdfRespT()
      Description copied from class: NetworkSolver
      Returns cumulative distribution functions of response times at steady-state. Uses default response time handles.
      Overrides:
      getCdfRespT in class NetworkSolver
      Returns:
      result containing CDFs for response times [stations x classes]

    • getCdfRespT

      public Ret.DistributionResult getCdfRespT(AvgHandle R)
      Get cumulative distribution function of response times, handle form.

      The handle only names which metrics the caller wants; the passage-time solve computes every (station, class) anyway, exactly as the reference @SolverFLD/getCdfRespT.m, so it is accepted for signature compatibility and not read. Without this override a caller holding a NetworkSolver reference would silently fall through to the base class exponential fit.

      Overrides:
      getCdfRespT in class NetworkSolver
      Parameters:
      R - the response time handles, accepted for signature compatibility
      Returns:
      DistributionResult containing the response time CDF data

    • getProbAggr

      public Ret.ProbabilityResult getProbAggr(int ist)
      Description copied from class: NetworkSolver
      Probability of a SPECIFIC per-class job distribution at a station (current state). Returns P(n1 jobs of class 1, n2 jobs of class 2, ...).

      Compare with NetworkSolver.getProbMarg(int, int, jline.util.matrix.Matrix): returns queue-length distribution for a single class, i.e., P(n jobs of class r) for n=0,1,...,N(r).

      Overrides:
      getProbAggr in class NetworkSolver
      Parameters:
      ist - the node index for which to compute probabilities
      Returns:
      scalar probability in [0,1]

    • getProbAggr

      public Ret.ProbabilityResult getProbAggr(int ist, Matrix state_a)
      Probability of a given per-class job distribution at a station. A null state_a reads the model's own state, as the one-argument form does.

      The explicit form exists for the delegating callers: the model interchange carries no initial state, so a caller that set one with initFromMarginal has to name the cell it is asking about, or every query would be answered at the default initialization.

      Overrides:
      getProbAggr in class NetworkSolver
      Parameters:
      ist - station index
      state_a - per-class job counts, or null to read the model state
      Returns:
      scalar probability in [0,1]

    • getTranCdfPassT

      public Ret.DistributionResult getTranCdfPassT()
      Description copied from class: NetworkSolver
      Returns cumulative distribution functions of passage times during transient analysis. Uses default response time handles.
      Overrides:
      getTranCdfPassT in class NetworkSolver
      Returns:
      result containing transient CDFs for passage times

    • initSol

      public void initSol()
      Initializes the solution vector for the fluid analysis. This method sets up the initial state representation for the fluid solver.

    • supportsTransientAnalysis

      public boolean supportsTransientAnalysis()
      Description copied from class: Solver
      Does this solver produce transient averages, i.e. does getTranAvg return trajectories on a finite options.timespan? Declared false here and overridden by the solvers that populate result.Tran (Fluid, CTMC, LDES, JMT). It is a capability claim, not a state test: it must answer before any run has taken place, because the MAP/MMPP random-environment fallback uses it to decide whether the environment stages can be coupled by the mean-field analyzer (which needs getTranAvg) or only by the two steady-state limits.
      Overrides:
      supportsTransientAnalysis in class Solver
      Returns:
      true if the solver can return transient averages

    • runAnalyzer

      public void runAnalyzer()
      Runs the fluid analyzer to solve the queueing network. This method executes the fluid approximation algorithm and stores the results in the solver's result object.
      Specified by:
      runAnalyzer in class Solver

    • runMethodSpecificAnalyzer

      public SolverResult runMethodSpecificAnalyzer()

    • supports

      public boolean supports(Network model)
      Checks whether the given model is supported by the Fluid solver. This method compares the features used by the model against the features supported by the Fluid solver.
      Overrides:
      supports in class Solver
      Parameters:
      model - The network model to check
      Returns:
      true if the model is supported, false otherwise

    • getStruct

      public NetworkStruct getStruct()
      Get model structure data structure summarizing the network
      Returns:
      NetworkStruct containing the model structure

    • exportODEs

      public String exportODEs()
      Export the mean-field ODE system to LaTeX in scalar notation.
      Returns:
      LaTeX source of the exported ODE system

    • exportODEs

      public String exportODEs(String fileName)
      Export the mean-field ODE system to a LaTeX file in scalar notation.
      Parameters:
      fileName - path of the .tex file to write; empty returns the source only
      Returns:
      LaTeX source of the exported ODE system

    • exportODEs

      public String exportODEs(String fileName, String notation)
      Export the system of ODEs integrated by the mean-field methods of this solver (default/matrix, pnorm, closing, statedep, softmin) as a standalone LaTeX document, in a symbolic form that is both human and machine readable. Mirrors the MATLAB SolverFLD.exportODEs method.
      Parameters:
      fileName - path of the .tex file to write; empty or null returns the source only
      notation - "scalar" for one expanded ODE per state variable, or "matrix" for the compact matrix notation
      Returns:
      LaTeX source of the exported ODE system

    • getSymbolicDrift

      public List<String> getSymbolicDrift()
      Right-hand side of the mean-field ODE system as expression strings, one per state variable, in the format the symbolic backend parses.

      Only smooth drifts are exported; see FluidODEsExporter.symbolicDrift(jline.solvers.fluid.FluidODEsExporter.SymODEs).

      Returns:
      one expression per state variable

    • getJacobian

      public String[][] getJacobian()
      Jacobian of the mean-field drift, d f_i / d x_j, computed exactly by the computer algebra backend.

      The Jacobian is what tells a fixed point apart from a limit cycle and gives the local convergence rate of the fluid approximation, neither of which a numerical integration reports. Only smooth drifts have one: the min-scaled methods are refused by name rather than answered with a one-sided derivative, see FluidODEsExporter.symbolicDrift(jline.solvers.fluid.FluidODEsExporter.SymODEs).

      Returns:
      the Jacobian entries, row major
      Throws:
      RuntimeException - if no symbolic backend is available or the drift is not differentiable

    • getTranAvgVar

      public Matrix[][] getTranAvgVar()
      Transient queue-length VARIANCE per station and class, [stations][classes].

      Only the "kp" method computes a second moment: it integrates the covariance of the Ko-Pender diffusion limit alongside the fluid mean. The full state covariance, which keeps cross-station and cross-class terms, is on result.Sigmat.

      Throws:
      RuntimeException - if the solver is not configured with options.method = "kp"

    • listValidMethods

      public String[] listValidMethods()

    • runAnalyzerChecks

      public void runAnalyzerChecks(SolverOptions options)
      Description copied from class: NetworkSolver
      Validates model compatibility and method support before analysis.
      Overrides:
      runAnalyzerChecks in class NetworkSolver
      Parameters:
      options - solver options containing method specification

    • initFluidHandles

      protected void initFluidHandles()
      Initialize performance metric handles from the model. This method ensures all handles are properly configured for fluid analysis.

    • setFluidTranAvgResults

      public void setFluidTranAvgResults(Matrix[][] Qt, Matrix[][] Ut, Matrix[][] Rt, Matrix[][] Tt, Matrix[][] Ct, Matrix[][] Xt, double runtimet)
      Set transient average results with proper validation
      Parameters:
      Qt - transient queue length matrices [time][stations x classes]
      Ut - transient utilization matrices [time][stations x classes]
      Rt - transient response time matrices [time][stations x classes]
      Tt - transient throughput matrices [time][stations x classes]
      Ct - transient system response time matrices [time][chains]
      Xt - transient system throughput matrices [time][chains]
      runtimet - computation time for transient analysis

    • setFluidDistribResults

      public void setFluidDistribResults(Matrix RD, double runtime)
      Set distribution results with enhanced metadata for fluid solver
      Parameters:
      RD - distribution data [stations x classes] containing CDFs
      runtime - computation time for distribution analysis

    • getAvgHandles

      public SolverAvgHandles getAvgHandles()
      Enhanced method to get average handles with validation
      Overrides:
      getAvgHandles in class NetworkSolver
      Returns:
      SolverAvgHandles with all handles properly initialized

    • setAvgHandles

      public void setAvgHandles(SolverAvgHandles handles)
      Enhanced method to set average handles with validation
      Overrides:
      setAvgHandles in class NetworkSolver
      Parameters:
      handles - the average handles to set

    • getTranHandles

      public SolverTranHandles getTranHandles()
      Enhanced method to get transient handles with validation
      Overrides:
      getTranHandles in class NetworkSolver
      Returns:
      SolverTranHandles with all handles properly initialized

    • setTranHandles

      public void setTranHandles(SolverTranHandles handles)
      Enhanced method to set transient handles with validation
      Overrides:
      setTranHandles in class NetworkSolver
      Parameters:
      handles - the transient handles to set

    • getAvgQLenHandles

      public AvgHandle getAvgQLenHandles()
      Get queue length handles with fluid-specific validation
      Overrides:
      getAvgQLenHandles in class NetworkSolver
      Returns:
      AvgHandle for queue length metrics

    • getAvgUtilHandles

      public AvgHandle getAvgUtilHandles()
      Get utilization handles with fluid-specific validation
      Overrides:
      getAvgUtilHandles in class NetworkSolver
      Returns:
      AvgHandle for utilization metrics

    • getAvgRespTHandles

      public AvgHandle getAvgRespTHandles()
      Get response time handles with fluid-specific validation
      Overrides:
      getAvgRespTHandles in class NetworkSolver
      Returns:
      AvgHandle for response time metrics

    • getAvgTputHandles

      public AvgHandle getAvgTputHandles()
      Get throughput handles with fluid-specific validation
      Overrides:
      getAvgTputHandles in class NetworkSolver
      Returns:
      AvgHandle for throughput metrics

    • getAvgArvRHandles

      public AvgHandle getAvgArvRHandles()
      Get arrival rate handles with fluid-specific validation
      Overrides:
      getAvgArvRHandles in class NetworkSolver
      Returns:
      AvgHandle for arrival rate metrics

    • getAvgResidTHandles

      public AvgHandle getAvgResidTHandles()
      Get residence time handles with fluid-specific validation
      Overrides:
      getAvgResidTHandles in class NetworkSolver
      Returns:
      AvgHandle for residence time metrics

    • getCdfPassT

      public Ret.DistributionResult getCdfPassT()
      Get cumulative distribution function for passage time.

      Delegates verbatim to getCdfRespT(), as the reference @SolverFLD/getCdfPassT.m does: for the fluid solver the passage time and the response time are the same second ODE solve from the steady-state fixed point.

      Overrides:
      getCdfPassT in class NetworkSolver
      Returns:
      DistributionResult containing the passage time CDF data

    • getCdfPassT

      public Ret.DistributionResult getCdfPassT(AvgHandle R)
      Get cumulative distribution function for passage time with specific response time handles.

      The handle only names which metrics the caller wants; the passage-time solve computes every (station, class) anyway, exactly as the reference, so it is accepted for signature compatibility and not read.

      Overrides:
      getCdfPassT in class NetworkSolver
      Parameters:
      R - the response time handles, accepted for signature compatibility
      Returns:
      DistributionResult containing the passage time CDF data

    • getCdfPT

      public Ret.DistributionResult getCdfPT()
      Backward-compatible name for getCdfPassT(), to which this delegates -- the @SolverFLD/getCdfPT.m twin.
      Returns:
      DistributionResult containing the passage time CDF data

    • getCdfPT

      public Ret.DistributionResult getCdfPT(AvgHandle R)
      Backward-compatible name for getCdfPassT(AvgHandle).

    • getAvgAoI

      public Map<String,Object> getAvgAoI()
      Get average Age of Information metrics.

      Returns AoI and Peak AoI statistics computed by the Fluid solver. Requires the model to have a valid AoI topology (single open class, Source-Queue-Sink, capacity 1 or 2, single server, FCFS/LCFS/LCFSPR).

      Returns:
      Map with keys "AoI" and "PAoI", each mapping to a Map with "mean", "var", "std" entries. Also includes "systemType" and "preemption" at the top level. Returns null if no AoI results are available.

    • getCdfAoI

      public Matrix[] getCdfAoI(Matrix tValues)
      Get CDF of Age of Information.

      Computes the cumulative distribution function of AoI and Peak AoI using matrix exponential representations: F(t) = 1 + g * expm(A*t) * inv(A) * h

      Parameters:
      tValues - Time values at which to evaluate CDF. If null, uses automatic range based on mean AoI (0 to 5*mean, 200 points).
      Returns:
      Array of two Matrix objects: [AoI_cdf, PAoI_cdf]. Each is an n x 2 matrix with columns [CDF_values, t_values]. Returns null if no AoI results are available.

    • getCdfAoI

      public Matrix[] getCdfAoI()
      Get CDF of Age of Information with automatic time range.
      Returns:
      Array of two Matrix objects: [AoI_cdf, PAoI_cdf]

    • getSjrnT

      public Ret.DistributionResult getSjrnT()
      Get sojourn time CDF. Alias for getCdfRespT().
      Returns:
      DistributionResult containing response time CDFs

    • sjrnT

      public Ret.DistributionResult sjrnT()
      Get sojourn time CDF. Lowercase alias for getSjrnT.
      Returns:
      DistributionResult containing response time CDFs

    • getLibrariesUsed

      public List<String> getLibrariesUsed(NetworkStruct sn, SolverOptions options)
      Bundled third-party libraries used by the fluid solver: rmf_tool backs the refined mean-field methods. Mirrors SolverFLD.getLibrariesUsed in MATLAB.
      Overrides:
      getLibrariesUsed in class NetworkSolver
      Parameters:
      sn - the model structure, may be null
      options - the solver options, may be null
      Returns:
      the library names, possibly empty