Package jline.solvers

Class Solver

java.lang.Object
jline.solvers.Solver
Direct Known Subclasses:
EnsembleSolver, NetworkSolver
public abstract class Solver extends Object
Abstract base class for model solution algorithms and analysis tools.

Provides the fundamental infrastructure for solving queueing models using various analytical and simulation algorithms. It manages solver configuration, result storage, random number generation, and validation of solver options.

Concrete implementations must provide the runAnalyzer() method to perform the actual model solution.

See Also:

  • Field Details

    • model

      public Model model
      The model to be solved

    • name

      public String name
      Name identifier for this solver instance

    • options

      public SolverOptions options
      Configuration options for the solver

    • result

      public SolverResult result
      Results from the most recent solver execution

    • enableChecks

      public boolean enableChecks
      Flag controlling whether to perform validation checks

    • random

      public Random random
      Random number generator for stochastic algorithms

  • Constructor Details

    • Solver

      protected Solver(String name, SolverOptions options)
      Constructs a solver with the specified name and options.
      Parameters:
      name - the solver name identifier
      options - configuration options for the solver

    • Solver

      protected Solver(Model model, String name, SolverOptions options)
      Constructs a solver with the specified model, name, and options.
      Parameters:
      model - the model to be solved
      name - the solver name identifier
      options - configuration options for the solver

    • Solver

      protected Solver(String name)
      Constructs a solver with the specified name using default options.
      Parameters:
      name - the solver name identifier

  • Method Details

    • defaultOptions

      public static SolverOptions defaultOptions()
      Returns a new SolverOptions instance with default settings.
      Returns:
      default solver options

    • listValidOptions

      public static Map<String,List<String>> listValidOptions()
      Returns lists of valid options and methods supported by solvers.
      Returns:
      map containing "allOptions" and "allMethods" lists

    • parseOptions

      public static SolverOptions parseOptions(Object... varargin) throws IllegalArgumentException
      Parses option parameters into a SolverOptions data structure.
      Parameters:
      varargin - variable arguments in key-value pairs
      Returns:
      parsed solver options
      Throws:
      IllegalArgumentException - if arguments are invalid

    • parseOptions

      public static SolverOptions parseOptions(SolverOptions options, Object... varargin) throws IllegalArgumentException
      Parses option parameters into an existing SolverOptions instance.
      Parameters:
      options - existing options object to modify
      varargin - variable arguments in key-value pairs
      Returns:
      modified solver options
      Throws:
      IllegalArgumentException - if arguments are invalid

    • getName

      public String getName()
      Returns the name identifier of this solver.
      Returns:
      the solver name

    • getOptions

      public SolverOptions getOptions()
      Returns the current solver options.
      Returns:
      the solver options

    • setOptions

      public void setOptions(SolverOptions options)
      Sets new solver options.
      Parameters:
      options - the new solver options to set

    • getResults

      public SolverResult getResults()
      Returns the results from the most recent solver execution.
      Returns:
      the solver results

    • hasResults

      public boolean hasResults()
      Checks if the solver has computed results.
      Returns:
      true if results are available, false otherwise

    • isStochastic

      public boolean isStochastic()
      Checks whether the solver, with its currently configured method, returns stochastic estimates, i.e. results that depend on the random seed, as in simulation or Monte Carlo integration.

      A solver run with method "default" may resolve the actual method only at runtime; once results are available the classification therefore uses the method recorded in result.method (e.g. "default/imci" when the NC default path resolved to Monte Carlo integration).

      Returns:
      true if the solver returns stochastic estimates

    • isStochasticMethod

      public boolean isStochasticMethod(String method)
      Classifies a (possibly runtime-resolved) method name of this solver as stochastic. Deterministic by default; subclasses with simulation-based or sampling-based methods override this.
      Parameters:
      method - the method name to classify
      Returns:
      true if the method returns stochastic estimates

    • isJavaAvailable

      public boolean isJavaAvailable()
      Checks if Java runtime is available for solver execution. Always returns true in this Java implementation.
      Returns:
      true indicating Java is available

    • isValidOption

      public boolean isValidOption(String optName)
      Checks if the specified option name is valid for this solver.
      Parameters:
      optName - the option name to validate
      Returns:
      true if the option is valid, false otherwise

    • reset

      public void reset()
      Clears previously stored results and resets the random number generator.

    • resetRandomGeneratorSeed

      public void resetRandomGeneratorSeed(long seed)
      Assigns a new seed to the random number generator. This sets the master seed for all random number generation in the system.
      Parameters:
      seed - the seed value for random number generation

    • runAnalyzer

      public abstract void runAnalyzer() throws IllegalAccessException, ParserConfigurationException, IOException
      Executes the solver algorithm to analyze the model. This abstract method must be implemented by concrete solver classes.
      Throws:
      IllegalAccessException - if access to required resources is denied
      ParserConfigurationException - if XML parsing configuration fails
      IOException - if I/O operations fail

    • timeExceeded

      public static boolean timeExceeded(long startNanos, double timeoutSeconds)
      Tests whether a wall-clock time budget has been exceeded. Used as a cooperative checkpoint inside iterative solver loops.
      Parameters:
      startNanos - value of System.nanoTime() captured at solver launch
      timeoutSeconds - wall-clock budget in seconds (Double.POSITIVE_INFINITY = no budget)
      Returns:
      true if (now - startNanos) exceeds timeoutSeconds

    • armTimeout

      protected LineTimeout.Scope armTimeout()
      Arms this solve's wall-clock budget (options.timeout) on the per-thread deadline stack of LineTimeout. A solve nested in an armed one draws on the enclosing budget instead of restarting it. Close the returned scope (try-with-resources) when the solve ends, then call flagTimeout(jline.util.LineTimeout.Scope).
      Returns:
      the scope to close at the end of the solve

    • flagTimeout

      protected boolean flagTimeout(LineTimeout.Scope scope)
      Closing check of the wall-clock budget (port of MATLAB flagTimeout.m): sets result.timedOut from the TRIPPED LATCH of the scope, which also resets a flag left over from an earlier run, and warns once when a checkpoint of this solve (or of one nested in it) stopped it early. The decision never reads the elapsed time: a run that completed its loop and then overran the budget while post-processing is a complete result.
      Parameters:
      scope - the scope returned by armTimeout()
      Returns:
      true when the solve stopped early on the budget

    • runAnalyzerChecks

      public void runAnalyzerChecks(SolverOptions options)
      Performs validation checks before running the analyzer. Verifies model compatibility and method validity.
      Parameters:
      options - the solver options to validate
      Throws:
      RuntimeException - if validation fails

    • supportsResolvedMethod

      public Solver.ResolvedVerdict supportsResolvedMethod(SolverOptions options)
      The gate runAnalyzerChecks(jline.solvers.SolverOptions) applies, as one call: METHOD is the concrete method options.method runs as (resolveMethod(jline.solvers.SolverOptions) turns "default" into "rqna" on a bursty open model in SolverMVA, into "jsim" in SolverJMT, into the fluid method the model selects in SolverFluid), and the verdict is supportsModelMethod(java.lang.String) asked about THAT name.

      ONE PREDICATE, TWO CALLERS: SolverAUTO.findSolver asks this of every declared name, so a row it calls runnable is a run this gate admits and a row it refuses is a run this gate refuses. Mirrors MATLAB NetworkSolver.supportsResolvedMethod.

      Parameters:
      options - the solver options, whose method is the requested name
      Returns:
      the verdict on the resolved method

    • unsupportedRefusalId

      public ErrorId unsupportedRefusalId(String method, String reason)
      The id the feature gate throws when the model is refused for METHOD: LINE:unsupported:<first unsupported feature> in FeatureSet declaration order, or LINE:unsupported:Structure for a structural refusal that names no feature (see FeatureSet.refusalId(jline.lang.FeatureSet, jline.lang.FeatureSet, java.lang.String)).
      Parameters:
      method - the concrete method name
      reason - the gate's refusal sentence, or null
      Returns:
      the refusal id

    • resolveMethod

      public String resolveMethod(SolverOptions options)
      Resolve the concrete method that will run. Base behavior returns options.method unchanged; solvers that perform feature-driven selection for options.method='default' override this (typically via selectMethod).
      Parameters:
      options - the solver options
      Returns:
      the concrete method name

    • getMethodFeatureSet

      public FeatureSet getMethodFeatureSet(String method)
      Per-method feature set, or null to signal "this solver does not diverge per method" (the coarse supports(model) is then used, preserving any structural checks it carries). Divergent solvers (e.g. MVA, MAM, NC) override this to return the base envelope with per-method deltas applied.
      Parameters:
      method - the concrete method name
      Returns:
      the per-method FeatureSet, or null

    • supportsTransientAnalysis

      public boolean supportsTransientAnalysis()
      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.
      Returns:
      true if the solver can return transient averages

    • supportsTransientVariance

      public boolean supportsTransientVariance()
      Does this solver produce a transient COVARIANCE alongside the transient means, i.e. does getTranAvgVar return one? Declared false here and overridden by SolverFluid, the only family that integrates a second moment along the trajectory, and there only for the methods that do ("kp", "dae"). Like supportsTransientAnalysis it is a capability claim that must answer before any run: SolverENV's "meancov" coupling reads it to decide whether a stage contributes a within-stage covariance or only the timing variance of its sojourn.
      Returns:
      true if the solver can return a transient covariance

    • supportsModelMethod

      public String supportsModelMethod(String method)
      Fine, method-aware gate. Returns an empty string when the model fits the concrete METHOD, else a human-readable reason. Base behavior derives the answer from getMethodFeatureSet(method); when that is null the solver's own supports(model) is used. Solvers with non-feature-set structural per-method rules override this.
      Parameters:
      method - the concrete method name
      Returns:
      empty string if supported, else the offending reason

    • selectMethod

      public String selectMethod(List<String> preferenceList)
      Feature-driven method selection: returns the first method in preferenceList whose per-method feature set covers the model, or the last entry when none fully covers (the gate then reports the precise features).
      Parameters:
      preferenceList - ordered candidate methods
      Returns:
      the selected method name

    • setChecks

      public void setChecks(boolean bool)
      Enables or disables validation checks during solver execution.
      Parameters:
      bool - true to enable checks, false to disable

    • supports

      public boolean supports(Network model)
      Checks if this solver supports the given network model. Default implementation returns true; subclasses should override to provide specific feature validation.
      Parameters:
      model - the network model to check
      Returns:
      true if the model is supported, false otherwise