Commit 0671606a authored by Benedikt Zoennchen's avatar Benedikt Zoennchen
Browse files

add some more comments to AttributesOSM.

parent 0c8c948c
Pipeline #87130 passed with stages
in 100 minutes and 54 seconds
......@@ -14,105 +14,118 @@ import org.vadere.state.types.UpdateType;
* <p>
* This class contains all parameters for the Optimal Steps Model with the exception of parameters for the three different
* potential functions (pedestrian-, target- and obstacle-potential) and without any submodel paraemters
* such as the Centroid Group Model {@link AttributesCGM}.
* such as the Centroid Group Model which have their own attributes class such as {@link AttributesCGM}.
* Most of the parameters are used to configure the algorithm which computes the next position of an agent.
* </p>
*
* <p>
* There exist different versions of the Optimal Steps Model which use different parameters such that not every parameter
* is used for every version and some parameters are only used if some other parameter has a specific value. The default version
* of the Optimal Steps Model is the one using the optimization on the disc and potential functions representing the personal
* spaces (see sivers-2016b). We deviate from sivers-2016b only in the concept of a minimal step length: In this implementation
* an agent will not move if its next position is closer than its minimal step length ({@link AttributesOSM#minStepLength}).
* There exist different versions of the Optimal Steps Model which use different parameters such that not every parameter
* is used for every version and some parameters are only used if some other parameter has a specific value. These different
* versions can be found in the PhD thesis of Isabella von Sivers [4] and Michael Seitz [2].
* </p>
*
* Each version of the OSM searches for the optimal next step by using different search algorithms / optimizers:
* <ul>
* <li>Discrete search on a circle: this is the original OSM formulation introduced in [1]. The step length is determined by the agents' speed (Eq. 6).
* The optimizer searches for the next best position on the circle at finite and equidistant points.
* </li>
* <li>Discrete search on a disc / cone: The above concept was extended to use multiple circles and, in addition, to use only points inside a cone
* which is defined by the speed of an agent such that agents avoid rapid directional changes.
* </li>
* <li>Continues search on a disc: Instead of evaluating a finite number of fixed points this optimizer searches on the whole disc such that agents
* use arbitrary
* </li>
* </ul>
* <p>
* Parameters for the configuring the optimization method are:
* <ul>
* <li>{@link AttributesOSM#stepCircleResolution}</li>
* <li>{@link AttributesOSM#numberOfCircles}</li>
* <li>{@link AttributesOSM#optimizationType}</li>
* <li>{@link AttributesOSM#varyStepDirection}</li>
* </ul>
* Dependent on the used combination, they have different meanings!
* The default version of the Optimal Steps Model is the one using the optimization on the disc and potential functions representing the personal
* spaces see [1] or [5]. We deviate from [4] only in the concept of a minimal step length: In this implementation
* an agent will not move if its next position is closer than its minimal step length ({@link AttributesOSM#minStepLength}).
* </p>
*
* Parameters for the configuring the optimization method are:
* <ul>
* <li>{@link AttributesOSM#stepCircleResolution}</li>
* <li>{@link AttributesOSM#numberOfCircles}</li>
* <li>{@link AttributesOSM#optimizationType}</li>
* <li>{@link AttributesOSM#varyStepDirection}</li>
* </ul>
* Dependent on the used combination, they have different meanings! The step length velocity correlation
* <p>
* The step length velocity correlation s(v) = a + b * v discussed in (seitz-2012) is realized via
* <ul>
* <li>{@link AttributesOSM#stepLengthIntercept}: a</li>
* <li>{@link AttributesOSM#stepLengthSlopeSpeed}: b</li>
* </ul>
* s(v) = {@link AttributesOSM#stepLengthIntercept} + {@link AttributesOSM#stepLengthSlopeSpeed} * v + error (Eq. 6)
* </p>
* discussed in [1].<br><br>
* <b>Related publications:</b>
* <ol>
* <li><a href="https://doi.org/10.1103/PhysRevE.86.046108">Natural discretization of pedestrian movement in continuous space</a></li>
* <li><a href="https://mediatum.ub.tum.de/?id=1293050">Simulating pedestrian dynamics: Towards natural locomotion and psychological decision making</a></li>
* <li><a href="https://doi.org/10.1088/1742-5468/2014/07/P07002">How update schemes influence crowd simulations</a></li>
* <li><a href="https://mediatum.ub.tum.de/doc/1303742/1303742.pdf">Modellierung sozialpsychologischer Faktoren in Personenstromsimulationen - Interpersonale Distanz und soziale Identit&auml;ten</a></li>
* <li><a href="https://doi.org/10.1016/j.trb.2015.01.009">Dynamic Stride Length Adaptation According to Utility And Personal Space</a></li>
* </ol>
*/
@ModelAttributeClass
public class AttributesOSM extends Attributes {
/**
* <p>
* Parameter of the optimization method: the number of points on the most outer circle.
* These points will be used in different ways which depends on the {@link OptimizationType}.
* <ul>
* <li>OptimizationType.NELDER_MEAD (default): each neighbouring pair of points and the agent position is used as a starting simplex</li>
* <li>OptimizationType.PSO: each point and the position of the agent is used as a starting position of a particle</li>
* <li>OptimizationType.DISCRETE: each point is and the position of the agent is used to directly evaluate the evaluation function</li>
* </ul>
* </p>
* Parameter of the optimization solver method: the number of points on the most outer circle. The number of points on any other circle will be
* chosen based on the angle between two successive points on the most outer circle such that any angle between two successive points
* on any circle will be almost equal. Therefore the number of points on a circle decreases with its radius.
* The positioned points will be used in different ways which depends on the {@link OptimizationType}.
* <ul>
* <li><tt>OptimizationType.NELDER_MEAD</tt> (default): each neighbouring pair of points and the agent position is used as a starting simplex</li>
* <li><tt>OptimizationType.PSO</tt>: each point and the position of the agent is used as a starting position of a particle</li>
* <li><tt>OptimizationType.DISCRETE</tt>: each point and the position of the agent is used to directly evaluate the evaluation function (brute force)</li>
* </ul>
*/
private int stepCircleResolution = 4;
/**
* <p>
* Parameter of the optimization method: the number of circles. Together with the {@link AttributesOSM#stepCircleResolution}
* this gives the number of points used by the optimization solver.
* </p>
* Parameter of the optimization solver method: the number of circles. Together with the {@link AttributesOSM#stepCircleResolution}
* this gives the number of points used by the optimization solver. If r is the radius of the most outer circle and k is the number
* of circles the radii of the circles are r/k, 2 * r/k, ... (k-1) * r/k, r.
*/
private int numberOfCircles = 1;
/**
* <p>
* Parameter of the optimization method: Specifies the concrete optimization solver.
* </p>
* Parameter of the optimization method: Specifies the concrete optimization solver.
*/
private OptimizationType optimizationType = OptimizationType.NELDER_MEAD;
/**
* If true, introduced for every optimization process a random offset by which points will be shifted (on their circle).
* If false, there will be no random offset. In case {@link AttributesOSM#movementType} is not directional
* and the first point of each circle will at (r * cos(0), r * sin(0)). This might solve some odd behaviour e.g.
* agents get stuck due to a local minimum of the overall potential.
* If <tt>true</tt>, introduced for every optimization process a noise term by which points will be shifted (on their circle). See Eq. 4 in [1].
* If <tt>false</tt>, there will be no noise term which might lead to artifacts, especially in case of <tt>OptimizationType.DISCRETE</tt>.
* In that case and with {@link AttributesOSM#movementType} not <tt>DIRECTIONAL</tt>, the first point of each circle will at (r * cos(0), r * sin(0)).
*/
private boolean varyStepDirection = true;
/**
* This should only be used if {@link OptimizationType} is equal <tt>DISCRETE</tt> or <tt>PSO</tt>, since all other optimization (on the disc) do not
* use this parameter. Reduces the circles of the optimization to a segments lying inside a cone (see seitz-2016 page 76).
* This does not effect the number of used points. The shape of the cone is computed by the formula in seitz-2016 which
* This has only an effect if {@link OptimizationType} is equal <tt>DISCRETE</tt> or <tt>PSO</tt>, since all other optimization (on the disc) do not
* use this parameter. Reduces the circles of the optimization to a segments lying inside a cone (see [2], page 76).
* This does not effect the number of used points. The shape of the cone is computed by Eq. 4.6, 4.7 which
* depends on the current velocity of the agent.
*/
private MovementType movementType = MovementType.ARBITRARY;
/**
* Used to compute the desired step length which is {@link AttributesOSM#stepLengthIntercept} + {@link AttributesOSM#stepLengthSlopeSpeed} * speed.
* (see seitz-2016 page 71 or seitz-2012).
* Used to compute the desired step length which is {@link AttributesOSM#stepLengthIntercept} + {@link AttributesOSM#stepLengthSlopeSpeed} * speed, i.e.
* Eq. 6 in [1].
*/
private double stepLengthIntercept = 0.4625;
/**
* Used to compute the desired step length which is {@link AttributesOSM#stepLengthIntercept} + {@link AttributesOSM#stepLengthSlopeSpeed} * speed + error
* (see seitz-2016 page 71 or seitz-2012).
* Used to compute the desired step length which is {@link AttributesOSM#stepLengthIntercept} + {@link AttributesOSM#stepLengthSlopeSpeed} * speed + error, i.e.
* Eq. 6 in [1].
*/
private double stepLengthSlopeSpeed = 0.2345;
/**
* Used to compute the error term of the desired step length i.e. the standard deviation of the normal
* distribution which is the distribution of the error variable.
* (see seitz-2016 page 71 or seitz-2012).
* distribution which is the distribution of the error variable (see Eq. 6 in [1]).
*/
private double stepLengthSD = 0.036;
/**
* Only used if {@link OptimizationType} is equal <tt>DISCRETE</tt> or <tt>PSO</tt>. If the potential does not improve by this
* movementThreshold, the agent will not move. This is in some sense similar to the effect of {@link AttributesOSM#minStepLength}.
* threshold, the agent will not move. This is in some sense similar to the effect of {@link AttributesOSM#minStepLength}.
*/
private double movementThreshold = 0;
......@@ -124,7 +137,7 @@ public class AttributesOSM extends Attributes {
private double minStepLength = 0.10;
/**
* If true enables the use of {@link AttributesOSM#minStepLength}. This attribute could be removed.
* If <tt>true</tt> enables the use of {@link AttributesOSM#minStepLength}. This attribute could be removed.
*/
private boolean minimumStepLength = true;
......@@ -135,19 +148,18 @@ public class AttributesOSM extends Attributes {
private double maxStepDuration = Double.MAX_VALUE;
/**
* SpeedAdjusters will only be active if this is <tt>true</tt>. For example this has to be true if the group model is
* <tt>SpeedAdjusters</tt> will only be active if this is <tt>true</tt>. For example this has to be true if the group model is
* active.
*/
private boolean dynamicStepLength = true;
/**
* Specifies which update schema is used. The OSM should use the event driven update schema
* (see seitz-2014b)
* Specifies which update schema is used. The OSM should use the event driven update schema, see [3].
*/
private UpdateType updateType = UpdateType.EVENT_DRIVEN;
/**
* If true this avoids agent jumping over small walls. However, this does not fix the problem that
* If <tt>true</tt> this avoids agent jumping over small walls. However, this does not fix the problem that
* the target potential computation fails due to small obstacles. Since this is a quick fix and the
* test is very expensive the default should be false!
*/
......@@ -230,7 +242,11 @@ public class AttributesOSM extends Attributes {
return obstaclePotentialModel;
}
/** Return a copy of the submodel class names. */
/**
* Return a copy of the submodel class names.
*
* @return a copy of the submodel class names
*/
public List<String> getSubmodels() {
return new ArrayList<>(submodels);
}
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment