Package it.univr.di.cstnu.algorithms

Class PSTN

java.lang.Object
it.univr.di.cstnu.algorithms.PSTN
public class PSTN extends Object
Simple class to represent a Probabilistic Simple Temporal Constraint Networks (PSTN), where the edge weights are signed integers.

Beta Version From 2024-06-13, it is not clear whether this class will be developed to become a full-fledged model. Therefore, to this day, I do not extend the TNGraphML* classes to represent such a kind of network.

Inside this class, the log-normal parameters associated with each contingent link are represented as a hash map and are not saved to file.

The only experiment we are planning to do is to load STNU instances, transform them into PSTN, changing all contingent links into probabilistic contingent links, and find an STNU approximation that guarantees the dynamic controllability of the original PSTN with the maximum probability.

Version:
$Rev: 878 $
Author:
Roberto Posenato

  • Field Details

    • FILE_NAME_SUFFIX

      public static final String FILE_NAME_SUFFIX
      Suffix for file name
      See Also:

    • ZERO_NODE_NAME

      public static final String ZERO_NODE_NAME
      The name for the initial node.
      See Also:

    • VERSIONandDATE

      static final String VERSIONandDATE
      Version of the class
      See Also:

    • rangeFactor

      double rangeFactor
      Factor used to determine the bounds of a contingent link from location and the standard deviation of the log-normal distribution in buildApproxSTNU()

  • Constructor Details

    • PSTN

      public PSTN(TNGraph<STNUEdge> graph, int expanderFactor, double sigmaFactor, double rangeFactor, OptimizationEngine optimizationEngine)
      See PSTN(TNGraph, int, double, OptimizationEngine)
      Parameters:
      graph - TNGraph to check
      expanderFactor - factor to amplify each edge value
      sigmaFactor - factor to determine σ.
      rangeFactor - rangeFactor to use for determining the first contingent ranges in the approximating STNU for the check
      optimizationEngine - Optimization engine for buildApproxSTNU will be used. It can be null.

    • PSTN

      public PSTN(TNGraph<STNUEdge> graph, int expanderFactor, double sigmaFactor, OptimizationEngine optimizationEngine)
      Given an STNU graph, it uses it as a base for it (does not make a copy).

      For each contingent link, it multiplies each edge value by expanderFactor to guarantee that the log-normal distribution built for each contingent link allows the determination of integer values.

      For each contingent link, it associates with its contingent node a pair (μ, σ) to represent the log-normal distribution associated with the contingent link. μ is the log-normal location, and σ is the standard deviation. They are determined as follows.

      Let x, y be the (updated) bounds of a contingent link. Let M = (x+y)/2, S= (y-x)/2 * #sigmaFactor. Then, μ = ln(M^2/(sqrt(M^2+S^2)) and σ = ln(1+ S^2/M^2).

      This method executes initAndCheck() on the input graph.

      Parameters:
      graph - TNGraph to check
      expanderFactor - factor to amplify each edge value
      sigmaFactor - factor to determine σ.
      optimizationEngine - Optimization engine for buildApproxSTNU will be used. It can be null.
      Throws:
      IllegalArgumentException - if any error occurs during initial initAndCheck().

    • PSTN

      public PSTN(@Nonnull TNGraph<STNUEdge> graph)
      Given a PSTN graph, it uses it as a network (does not make a copy). The contingent nodes must have a significant LabeledNode.getLogNormalDistribution().
      Parameters:
      graph - PSTN in TNGraph format

    • PSTN

      PSTN()
      Default constructor.

  • Method Details

    • getVersionAndDate

      public static String getVersionAndDate()
      Returns:
      the version

    • buildApproxSTNU

      public PSTN.PSTNCheckStatus buildApproxSTNU()
      Determines (Su, F), where Su = (T, C, L) is a dynamically controllable STNU where L = {(Ai, xi, yi, Ci) | i ∈ {1, ..., k}} and F is the value of the objective function (i.e., the joint probability mass of the probabilistic durations in this PSTN network captured by the contingent links in L).

      The STNU has the same time-points and ordinary constraints as the PSTN, together with contingent links over the same activation and contingent time-points. If unable to find such an STNU or the STNU contains an SRN made by only ordinary edges, it returns a null approximating STNU.

      Returns:
      The result (Su, F) is stored in PSTN.PSTNCheckStatus.approximatingSTNU and PSTN.PSTNCheckStatus.probabilityMass. If it is not possible to find an approximation because the optimization fails, PSTN.PSTNCheckStatus.exitFlag assumes negative values (see OptimizationEngine.OptimizationResult), approximatingSTNU = null and probabilityMass = -1.
      If it is not possible because the semi-reducible cycle is composed by only ordinary edges, then PSTN.PSTNCheckStatus.exitFlag is -10, approximatingSTNU = null and probabilityMass = -1.
      If the approximating STNU was found without resolving any minimization problem, PSTN.PSTNCheckStatus.exitFlag is 10.

      this.g is not modified.

      Throws:
      IllegalArgumentException - if g is null or g does not contain contingent links.

    • getActivationNodeMap

      @Nullable public final it.unimi.dsi.fastutil.objects.Object2ObjectMap<LabeledNode,LabeledNode> getActivationNodeMap()
      Returns:
      the activationNode map if the network has been initAndCheck(), null otherwise.

      The map is (contingentNode, activationNode).

    • getAvgContingentRangeWidth

      public int getAvgContingentRangeWidth()
      Returns:
      the avgContingentRangeWidth

    • getG

      public final TNGraph<STNUEdge> getG()
      Returns:
      the g

    • getLowerCaseEdgesMap

      @Nullable public final it.unimi.dsi.fastutil.objects.Object2ObjectMap<LabeledNode,STNUEdge> getLowerCaseEdgesMap()
      Returns a map containing the lower-case edges associated with the contingent link of the network if the network was initialized (initAndCheck() executed successfully); null otherwise. In particular, if the network contains the contingent link (A, 1, 3, C), the returned map contains the pair C --> (A, c(1), C).
      Returns:
      the lowerContingentEdge map

    • getHorizon

      public int getHorizon()
      Returns:
      the horizon of the network

    • getMaxWeight

      public int getMaxWeight()
      Returns:
      the absolute max weight of the network

    • getOptimizationEngine

      public OptimizationEngine getOptimizationEngine()
      Returns:
      the MATLAB Engine used by this class.

    • setOptimizationEngine

      public void setOptimizationEngine(OptimizationEngine optimizationEngine)
      Parameters:
      optimizationEngine - the new MATLAB Engine to use.

    • getUpperCaseEdgesMap

      @Nullable public it.unimi.dsi.fastutil.objects.Object2ObjectMap<LabeledNode,STNUEdge> getUpperCaseEdgesMap()
      Returns a map containing the upper-case edges associated with the contingent link of the network if the network was initialized (initAndCheck() executed successfully); null otherwise. In particular, if the network contains the contingent link (A, 1, 3, C), the returned map contains C --> (C, C:-3, A).
      Returns:
      the upper-case constraints map

    • getTimeOut

      public int getTimeOut()
      Returns:
      the time-out in seconds for the DC checking method.

    • getVersionAndCopyright

      public final String getVersionAndCopyright()
      Returns:
      version and copyright string

    • initAndCheck

      public final void initAndCheck() throws WellDefinitionException
      Makes the PSTN check and initialization. The PSTN instance is represented by graph g. If some constraints of the network do not observe well-defined properties AND they can be adjusted, then the method fixes them and logs such fixes in the log system at the WARNING level. If the method cannot fix such not-well-defined constraints, it raises a WellDefinitionException.
      Throws:
      WellDefinitionException - if any error about the format of the network occurs

    • getfInput

      public File getfInput()
      Returns:
      the fInput

    • getfOutput

      public File getfOutput()
      Returns:
      the fOutput

    • setfOutput

      public final void setfOutput(File fileOutput)
      Parameters:
      fileOutput - the file where to save the result.

    • isSave

      public boolean isSave()
      Returns:
      the saved

    • saveGraphToFile

      public final void saveGraphToFile()
      Stores the graph after a check of the file.

    • setSave

      public final void setSave(boolean s)
      Parameters:
      s - the save to set

    • isVersionReq

      public boolean isVersionReq()
      Returns:
      the versionReq

    • reset

      public final void reset()
      Resets all internal structures.

    • setG

      public final void setG(TNGraph<STNUEdge> graph)
      Considers the given graph as the graph to check (the graph will be modified). Clear all internal parameters.
      Parameters:
      graph - set internal TNGraph to g. It cannot be null.

    • updateContingentBounds

      public void updateContingentBounds(STNU approximatedSTNU)
      A PSTN maintains bounds of a contingent link as a lower / upper case-edge value. This is because, even though contingent link durations are described as distribution probability functions, the STRONG/DYNAMIC controllability of a PSTN is realized by approximating the network as an STNU.

      buildApproxSTNU() allows the determination of a Dynamic Controllable approximating STNU that maximizes the probability mass for each contingent link. Such a method returns a DC STNU (if it exists) and doesn't touch the current network. This method saves the contingent bounds determined in the approximating STNU in the current network.

      Parameters:
      approximatedSTNU - the approximating STNU. It has to have the same contingent links (name) and the same contingent node names to copy the bounds successfully.