Package jline.solvers.ldes

Class LDESOptions

java.lang.Object
jline.solvers.SolverOptions
jline.solvers.ldes.LDESOptions
public class LDESOptions extends SolverOptions
Configuration options for the LDES solver.

LDESOptions extends the base solver options to provide LDES-specific configuration parameters. LDES uses the SSJ library for discrete-event simulation that generates sample paths of the queueing network state evolution over time.

Key LDES characteristics:

  • Discrete event simulation approach using SSJ library
  • Handles multiclass Jackson queueing networks
  • Supports steady-state analysis
  • Provides statistical estimates with confidence intervals
  • Uses event-count based stopping (samples = max service completions)
  • Default: 200,000 service completion events

Default Configuration (based on benchmark analysis): 

 samples     = 200,000   (good accuracy/speed balance, ~5% mean error)
 tranfilter  = "mser5"   (adaptive warmup detection)
 warmupfrac  = 0.20      (20% warmup for fixed filter)
 cimethod    = "obm"     (overlapping batch means)
 obmoverlap  = 0.50      (50% overlap)
 cnvgon      = false     (fixed event count)
For heavy-tailed workloads (high SCV), consider increasing samples to 500,000+.

Since:
1.0
See Also:

  • Field Details

    • DEFAULT_SAMPLES

      public static final int DEFAULT_SAMPLES
      Default number of service completion events for LDES solver (200,000)
      See Also:

    • DEFAULT_CNVG_TOL

      public static final double DEFAULT_CNVG_TOL
      Default convergence tolerance (5% relative precision)
      See Also:

    • DEFAULT_CNVG_BATCH

      public static final int DEFAULT_CNVG_BATCH
      Default minimum number of batches before checking convergence
      See Also:

    • cnvgon

      public boolean cnvgon
      Enable convergence-based stopping. When enabled, simulation stops when confidence interval half-width relative to mean falls below the convergence tolerance for all metrics. Default: false (disabled to maintain backward compatibility with existing tests)

    • cnvgtol

      public double cnvgtol
      Convergence tolerance - stop when (CI half-width / mean) is below this threshold. A value of 0.05 means 5% relative precision. Default: 0.05

    • cnvgbatch

      public int cnvgbatch
      Minimum number of batches required before checking for convergence. More batches provide more reliable confidence interval estimates. Default: 20

    • cnvgchk

      public int cnvgchk
      Number of events between convergence checks. A value of 0 means auto-calculate (samples / 50). Default: 0 (auto)

    • DEFAULT_MSER_BATCH

      public static final int DEFAULT_MSER_BATCH
      Default MSER batch size (MSER-5 standard)
      See Also:

    • DEFAULT_WARMUP_FRAC

      public static final double DEFAULT_WARMUP_FRAC
      Default warmup fraction when using fixed method
      See Also:

    • tranfilter

      public String tranfilter
      Transient filter method for warmup detection and removal. Valid values: "mser5" (automatic MSER-5), "fixed" (fixed fraction), "none" (no filtering). Default: "mser5"

    • mserbatch

      public int mserbatch
      Batch size for MSER transient detection algorithm. Only used when tranfilter = "mser5". Default: 5 (standard MSER-5)

    • warmupfrac

      public double warmupfrac
      Warmup fraction when using fixed transient filter. Fraction of total events discarded as warmup (0.0 to 1.0). Only used when tranfilter = "fixed". Default: 0.2 (20% warmup)

    • DEFAULT_TRAN_OBS

      public static final int DEFAULT_TRAN_OBS
      Default number of transient observation points (see tranobs).
      See Also:

    • tranobs

      public int tranobs
      Number of equally spaced observation points of a transient trajectory (analysis over options.timespan). The horizon is split into tranobs intervals of equal length and the state is recorded at each boundary. It fixes the time grid only: the simulated event budget is unaffected. Default: 1000, the native C++ engine's value

    • DEFAULT_OBM_OVERLAP

      public static final double DEFAULT_OBM_OVERLAP
      Default OBM overlap fraction (50% overlap)
      See Also:

    • DEFAULT_CI_MIN_BATCH

      public static final int DEFAULT_CI_MIN_BATCH
      Default minimum batch size for CI computation
      See Also:

    • DEFAULT_CI_MIN_OBS

      public static final int DEFAULT_CI_MIN_OBS
      Default minimum observations required for CI computation
      See Also:

    • cimethod

      public String cimethod
      Confidence interval computation method. Valid values: "obm" (overlapping batch means), "bm" (batch means), "spectral" (Heidelberger-Welch spectral analysis), "none" (no CI). Default: "obm"

    • obmoverlap

      public double obmoverlap
      Overlap fraction for OBM confidence intervals (0.0 to 1.0). 0.5 = 50% overlap (standard), 0.0 = non-overlapping (same as bm). Only used when cimethod = "obm". Default: 0.5

    • ciminbatch

      public int ciminbatch
      Minimum batch size for confidence interval computation. Actual batch size is max(ciminbatch, sqrt(n)) where n is sample count. Default: 10

    • ciminobs

      public int ciminobs
      Minimum number of post-warmup observations required before computing CIs. If fewer observations available, CI is set to 0 (unavailable). Default: 100

    • DEFAULT_SPECTRAL_LOW_FREQ_FRAC

      public static final double DEFAULT_SPECTRAL_LOW_FREQ_FRAC
      Default fraction of lowest frequencies used for spectral regression
      See Also:

    • spectralLowFreqFrac

      public double spectralLowFreqFrac
      Fraction of lowest frequencies to use for log-periodogram regression in the Heidelberger-Welch spectral method. Only used when cimethod = "spectral". Default: 0.25 (lowest 25% of frequencies)

    • basTrace

      public boolean basTrace
      Enable detailed BAS (Blocking After Service) tracing for debugging. Default: false

    • exportStateHistogram

      public boolean exportStateHistogram
      When true, the simulator accumulates the exact joint-state residence-time histogram and exposes it via LDESResult. Host languages that cannot pass a Java reward function into the simulation (MATLAB, native Python) use it to evaluate arbitrary Markov rewards on the empirical state distribution. Default: false

    • samplePathEvents

      public int samplePathEvents
      Number of events of the exact sample path to record, 0 to record none. When positive the simulator runs a single replication without warmup removal and stops after this many path events, logging every arrival, service start, departure, drop and phase change with its time, node, class, job id and phase, together with the LINE state of every stateful node before each event. Recording consumes no random draw from any simulation stream, so the path is the one the run would take anyway. Default: 0

    • busyPeriodOrders

      public int busyPeriodOrders
      Highest busy period order measured along the sample path. A busy period of order n for a set of stations runs from the instant an arrival raises the jobs held by the set to n up to the instant the set falls back below n (H. Daduna, J. ACM 35(3), 1988). When positive, the simulator measures the orders 1..busyPeriodOrders for every station, for every station-class pair, and for every set declared in busyPeriodSubnets. Default: 0 (no busy period measurement)

    • busyPeriodSubnets

      public List<int[]> busyPeriodSubnets
      Station sets whose joint busy periods are measured, each given as station indexes. Empty unless the caller declares a subnetwork; the per-station and per-class busy periods are always measured when busyPeriodOrders is positive.

    • maxSimEvents

      public int maxSimEvents
      Maximum number of total simulation events (all types: arrivals, departures, routing, setup, etc.). When set to a positive value, the simulation stops when this limit is reached, regardless of service completion count. A value of -1 means no limit (only service completion count is used). Default: -1 (no limit)

    • maxTime

      public double maxTime
      Wall-clock time budget in seconds for the simulation. When set to a positive, finite value, the SSJ event loop stops early once the elapsed wall-clock time exceeds this budget (stopping_reason = "max_time"). A value of Double.POSITIVE_INFINITY (default) means no wall-clock limit.

    • DEFAULT_SLOT_LENGTH

      public static final double DEFAULT_SLOT_LENGTH
      Default slot length used when slotted mode is enabled without an explicit length.
      See Also:

    • slotted

      public boolean slotted
      Runs the simulation on a discrete time scale: every sampled interval must fall on the lattice {slotLength, 2*slotLength, ...}, events within one slot boundary are ordered by a fixed phase (completions, then internal routing, then external arrivals, then bookkeeping), and the warmup and time-horizon cuts are snapped to slot boundaries.

      The mode does not discretize a continuous model. A sample that is not a lattice point is an error, not something to round, because rounding would silently replace the modelled distribution with a different one.

      Default: false (continuous time).

    • slotLength

      public double slotLength
      Length of one slot in model time units. Only meaningful when slotted is true. Default: 1.0.

    • DEFAULT_REPLICATIONS

      public static final int DEFAULT_REPLICATIONS
      Default number of replications (1 = single run, backward compatible)
      See Also:

    • replications

      public int replications
      Number of independent replications to run. When > 1, enables parallel replication mode where each replication runs independently with its own RNG stream, and results are aggregated using cross-replication variance for confidence intervals. Default: 1 (single long run with batch means, backward compatible)

    • numThreads

      public int numThreads
      Number of parallel threads for replication execution. Default: Runtime.getRuntime().availableProcessors() / 2 Only used when replications > 1.

    • restUrl

      public String restUrl
      Base URL of an LDES REST server, e.g. "http://localhost:8080" (the imperialqore/ldes container). When set, the model is serialized to model.json and POSTed to <url>/api/v1/solve instead of being simulated in this JVM; the returned ldes-result document is deserialized into an LDESResult. Null or empty means solve locally.

  • Constructor Details

    • LDESOptions

      public LDESOptions()
      Constructs a new LDESOptions instance with default LDES solver configuration. Sets the maximum service completion events to 200,000 by default. Verbose output is disabled by default for LDES.

  • Method Details

    • busyPeriods

      public LDESOptions busyPeriods(int orders)
      Measures the busy periods of orders 1..orders.
      Parameters:
      orders - highest order measured, 0 disables the measurement
      Returns:
      this options object

    • busyPeriodSubnet

      public LDESOptions busyPeriodSubnet(int... stations)
      Adds a station set whose joint busy period is measured.
      Parameters:
      stations - station indexes forming the subnetwork
      Returns:
      this options object

    • setRestUrl

      public LDESOptions setRestUrl(String url)
      Sets the LDES REST server that will run the simulation.
      Parameters:
      url - base URL, e.g. "http://localhost:8080"; null or empty solves locally
      Returns:
      this options instance for method chaining

    • setCnvgon

      public LDESOptions setCnvgon(boolean enabled)
      Sets whether convergence-based stopping is enabled.
      Parameters:
      enabled - true to enable convergence checking
      Returns:
      this options instance for method chaining

    • setCnvgtol

      public LDESOptions setCnvgtol(double tolerance)
      Sets the convergence tolerance.
      Parameters:
      tolerance - the relative precision threshold (e.g., 0.05 for 5%)
      Returns:
      this options instance for method chaining

    • setCnvgbatch

      public LDESOptions setCnvgbatch(int minBatches)
      Sets the minimum number of batches before checking convergence.
      Parameters:
      minBatches - the minimum number of batches required
      Returns:
      this options instance for method chaining

    • setCnvgchk

      public LDESOptions setCnvgchk(int interval)
      Sets the number of events between convergence checks.
      Parameters:
      interval - the number of events (0 for auto-calculation)
      Returns:
      this options instance for method chaining

    • setTranfilter

      public LDESOptions setTranfilter(String method)
      Sets the transient filter method.
      Parameters:
      method - the transient filter method ("mser5", "fixed", or "none")
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if method is not valid

    • setTranobs

      public LDESOptions setTranobs(int n)
      Sets the number of equally spaced transient observation points.
      Parameters:
      n - the number of observation intervals over the timespan (positive)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if n is not positive

    • setMserbatch

      public LDESOptions setMserbatch(int batchSize)
      Sets the MSER batch size.
      Parameters:
      batchSize - the batch size for MSER algorithm (must be >= 1)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if batchSize is less than 1

    • setWarmupfrac

      public LDESOptions setWarmupfrac(double fraction)
      Sets the warmup fraction for fixed transient filter.
      Parameters:
      fraction - the warmup fraction (0.0 to 1.0, exclusive)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if fraction is not in [0, 1)

    • setCimethod

      public LDESOptions setCimethod(String method)
      Sets the confidence interval computation method.
      Parameters:
      method - the CI method ("obm", "bm", or "none")
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if method is not valid

    • setSpectralLowFreqFrac

      public LDESOptions setSpectralLowFreqFrac(double fraction)
      Sets the fraction of lowest frequencies for spectral log-periodogram regression.
      Parameters:
      fraction - the fraction (0.0 to 1.0, exclusive of 0)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if fraction is not in (0, 1]

    • setObmoverlap

      public LDESOptions setObmoverlap(double overlap)
      Sets the OBM overlap fraction.
      Parameters:
      overlap - the overlap fraction (0.0 to 1.0)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if overlap is not in [0, 1]

    • setCiminbatch

      public LDESOptions setCiminbatch(int minSize)
      Sets the minimum batch size for CI computation.
      Parameters:
      minSize - the minimum batch size (must be >= 2)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if minSize is less than 2

    • setCiminobs

      public LDESOptions setCiminobs(int minObs)
      Sets the minimum observations required for CI computation.
      Parameters:
      minObs - the minimum number of observations (must be >= 10)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if minObs is less than 10

    • setMaxSimEvents

      public LDESOptions setMaxSimEvents(int maxEvents)
      Sets the maximum number of total simulation events.
      Parameters:
      maxEvents - the maximum number of events (-1 for no limit, must be >= 1 or -1)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if maxEvents is less than 1 and not -1

    • setReplications

      public LDESOptions setReplications(int numReps)
      Sets the number of independent replications to run. When > 1, enables parallel replication mode with cross-replication CI.
      Parameters:
      numReps - number of replications (must be >= 1)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if numReps is less than 1

    • setNumThreads

      public LDESOptions setNumThreads(int threads)
      Sets the number of parallel threads for replication execution.
      Parameters:
      threads - number of threads (must be >= 1)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if threads is less than 1

    • setSlotted

      public LDESOptions setSlotted(boolean enabled)
      Enables or disables discrete-time (slotted) simulation.
      Parameters:
      enabled - true to run on a discrete time scale
      Returns:
      this options instance for method chaining

    • setSlotLength

      public LDESOptions setSlotLength(double length)
      Sets the slot length and enables slotted mode.
      Parameters:
      length - slot length in model time units (must be positive and finite)
      Returns:
      this options instance for method chaining
      Throws:
      IllegalArgumentException - if length is not positive and finite

    • copy

      public LDESOptions copy()
      Creates a deep copy of this LDESOptions object. Overrides the base class copy() to preserve LDES-specific fields.
      Overrides:
      copy in class SolverOptions
      Returns:
      a deep copy of this LDESOptions object