desmoj.core.dist

Class Distribution

java.lang.Object

desmoj.core.simulator.NamedObject

desmoj.core.simulator.ModelComponent

desmoj.core.simulator.Reportable

desmoj.core.dist.Distribution

Direct Known Subclasses:

BoolDist, EntityDist, NumericalDist, Series

public abstract class Distribution
extends Reportable

Base class for all pseudo random number distributions used in this package. Defines a set of methods usefull for all kinds of random distributions that can be based upon a stream of uniform distributed pseudo random numbers. Prefabricated distributions implemented in this package can handle uniform, normal (gaussian), bernoulli, poisson and heuristic distributions with return values of the primitive data types double (floating point), long (integer) and boolean (true or false). Inherit from this class if you want to implement new types of distributions handing back values of other types than those listed above. Basic idea is to use a pseudo random generator which produces a uniformly distributed stream of double numbers between 0 and 1 use inverse transformation to generate the desired distribution. See also [Page91, p. 107] Note that although this class implements all methods, it is set to be abstract, since instantiating this class would not produce any meaningfull distribution to be used by a client.

Version:

DESMO-J, Ver. 2.5.1c copyright (c) 2015

Author:

Tim Lechler Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

See Also:

UniformRandomGenerator, LinearCongruentialRandomGenerator

Constructor Summary

Constructors

Constructor and Description
Distribution(Model owner, java.lang.String name, boolean showInReport, boolean showInTrace) Creates a RandomDistribution object which gets its initial seed from the experiment's seedgenerator.

Method Summary

Modifier and Type	Method and Description
void	changeRandomGenerator(UniformRandomGenerator randomGenerator) Changes the underlying random generator to the one given as a parameter.
Reporter	createDefaultReporter() Creates the default reporter associated with this distribution.
long	getInitialSeed() Returns the seed value since last reset.
boolean	getNonNegative() Tells if this distribution can return negative samples.
long	getNumSamples() Returns the number of Samples given by this distribution.
boolean	isAntithetic() Returns the current status for antithetic random number generation in this distribution.
void	reset() Resets the pseudo random generator's seed and the number of samples given to zero.
void	reset(long newSeed) Resets the pseudo random generator's seed to the value passed, the number of samples given to zero and sets antithetic to false for this distribution.
abstract java.lang.Object	sampleObject() Convenience method to return the distribution's sample as Object.
void	setAntithetic(boolean newAntiStatus) Switches this distribution to produce antithetic samples.
void	setNonNegative(boolean newValue) Sets the nonNegative switch to the given value.
void	setSeed(long newSeed) Sets the underlying pseudo random number generator's seed to the value given.

Methods inherited from class desmoj.core.simulator.Reportable

getCorrespondingSchedulable, getDescription, getObservations, getReporter, incrementObservations, incrementObservations, reportIsOn, reportOff, reportOn, resetAt, setCorrespondingSchedulable, setDescription, setReporter

Methods inherited from class desmoj.core.simulator.ModelComponent

current, currentEntity, currentEntityAll, currentEvent, currentModel, currentSimProcess, debugIsOn, debugOff, debugOn, getModel, isExperimentCompatible, isModelCompatible, presentTime, sendDebugNote, sendMessage, sendTraceNote, sendWarning, skipTraceNote, skipTraceNote, traceIsOn, traceOff, traceOn

Methods inherited from class desmoj.core.simulator.NamedObject

getName, getQuotedName, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

Distribution

public Distribution(Model owner,
                    java.lang.String name,
                    boolean showInReport,
                    boolean showInTrace)

Creates a RandomDistribution object which gets its initial seed from the experiment's seedgenerator. The LinearCongruentialRandomGenerator is used as the underlying uniform pseudo random number generator for all pseudo random distribution .

Parameters:

owner - Model : The distribution's owner

name - java.lang.String : The distribution's name

showInReport - boolean : Flag to show distribution in report

showInTrace - boolean : Flag to show distribution in trace

Method Detail

changeRandomGenerator

public void changeRandomGenerator(UniformRandomGenerator randomGenerator)

Changes the underlying random generator to the one given as a parameter. Custom random generators have to implement the desmoj.dist.UniormRandomGenerator interface. Note that changing the underlying random generator forces a reset, since a new generator might produce a completely different stream of pseudo random numbers that won't enable us to reproduce the stream of numbers probably delivered by the previously used generator.

Parameters:

randomGenerator - java.util.Random : the random generator used for creating distributions

createDefaultReporter

public Reporter createDefaultReporter()

Creates the default reporter associated with this distribution. The basic DistributionReporter returned as a default implementation of this method simply reports the distribution's name, number of observations (samples given), seed and point of simulation time of the last reset.

Returns:

Reportable : The reporter associated with this distribution

See Also:

DistributionReporter

getInitialSeed

public long getInitialSeed()

Returns the seed value since last reset.

Returns:

long : The initial seed value

getNonNegative

public boolean getNonNegative()

Tells if this distribution can return negative samples.

Returns:

boolean : If true it returns positive samples only

getNumSamples

public long getNumSamples()

Returns the number of Samples given by this distribution. The number of samples is increased whenever the sample() method is called. It is based on the random numbers of the distribution, not on the number of random numbers produced by the underlying random generator, since some distributions use algorithms consuming more than one uniformly distributed random number to produce one sample following the desired distribution.

Returns:

long : the number of samples given to clients

isAntithetic

public boolean isAntithetic()

Returns the current status for antithetic random number generation in this distribution.

Returns:

boolean : The status of antithetic pseudo random number generation

See Also:

setAntithetic(boolean)

reset

public void reset()

Resets the pseudo random generator's seed and the number of samples given to zero. The field antithetic keeps the value it has had before the reset.

Overrides:

reset in class Reportable

reset

public void reset(long newSeed)

Resets the pseudo random generator's seed to the value passed, the number of samples given to zero and sets antithetic to false for this distribution. Acts the same as a call of method reset() and a consecutive call to setSeed(long).

Parameters:

newSeed - long : new seed to be used by underlying random number generator after reset

sampleObject

public abstract java.lang.Object sampleObject()

Convenience method to return the distribution's sample as Object. For type safety, method sample() should be preferred. However, this method is useful for environments requiring a non-genetic access point to obtain samples from any distribution.

Returns:

Object : A sample from this this distribution wrapped as Object.

setAntithetic

public void setAntithetic(boolean newAntiStatus)

Switches this distribution to produce antithetic samples. To obtain antithetic random numbers, call this method with the parameter true. Antithetic random numbers are used to minimize the standard deviation of a series of simulation runs. The results of a run with normal random numbers has to be standardized with the results of a run using antithetic random numbers, thus doubling the number of samples needed, but also lowering the standard deviation of the results of that simulation. See [Page91, p.139].

Parameters:

newAntiStatus - boolean : Parameter true switches antithetic mode on, false switches antithetic mode off

setNonNegative

public void setNonNegative(boolean newValue)

Sets the nonNegative switch to the given value. If nonNegative is set to true the distribution returns positive samples only, otherwise it also produces negative samples, if possible.

Parameters:

newValue - boolean : If true the distribution is set to return positive samples only, otherwise it also produces negative samples, if possible.

setSeed

public void setSeed(long newSeed)

Sets the underlying pseudo random number generator's seed to the value given. The seed controls the starting value of the random generators and all following generated pseudo random numbers. Resetting the seed between two simulation runs will let you use identical streams of random numbers. That will enable you to compare different strategies within your model based on the same random number stream produced by the random generator.

Parameters:

newSeed - long : new seed used by underlying pseudo random number generator