The core implements all the major inter-module communication and coordination, as well as all the support functions required to operate GridLAB-D modules.

Synchronization

The main execution loop sets up the main simulation, initializes the objects, and runs the simulation until it either settles to equilibrium or runs into a problem. It also manages multicore/multiprocessor parallelism when possible. Objects of the same rank will be synchronized simultaneously, resources permitting.

The main processing loop passes each object a timestamp indicating the desired synchronization time. Each object’s synchronization function attempts to advance its internal clock to the time indicated. If successful, it returns the time of the next expected change in the object's state. An object state change is one which requires the equilibrium equations of the object to be updated. When an object's state changes, all the other objects in the simulator are given an opportunity to consider the change and possibly alter the time of their next state change. The core continues calling objects this way, advancing the global clock when necessary, until all objects indicate that no further state changes are expected. This is the equilibrium condition and the simulation consequently ends.

For more information see Theory of operation.

Clocks

The core handles all time calculations and daylight saving time (DST). DST rules are specified for a given simulation in a file that is loaded when necessary. All internal timestamp are recorded in Greenwich Mean Time (GMT) but displayed in objects’ local time according to the time zone setting for the simulation.

DST rules are recorded in the Posix-compliant format for the TZ environment variable, i.e.,

STZ[hh[:mm][DTZ][,M#[#].#.#/hh:mm,M#[#].#.#/hh:mm]]

Random numbers

Note: the random number generation technique is being revised in version 3.0. See page on Multithreaded Random Number Generation.

Template:NEW30 As of Version 3.0 a built-in property type random is available. These properties will change during the course of a simulation following the specified random distribution. The specification is given as

 random "type:distribution(a,b); min:low; max:high; refresh:rate unit; state:number";

where distribution is the random function to use, a and b are the distribution's parameters, low and high are the truncation limits, rate is the refresh rate specified in units, and number is the random number generator's initial state. When low and high are not specified there is not truncation, otherwise numbers generated outside the range are not used and the random number is generated again (be careful not to specified an improbable range because it will very adversely affect performance). When rate is not specified, the number is regenerated every time the core iterates on time. If units are not specified, seconds are used. When the state is not specified, a random initial state is used.

The core supports a number of random number generators required for generation properties according to user-specified distributions. The following distributions are supported:

Uniform distribution

This distribution generates a uniformly distributed random number. The probability density function for the uniform distribution is

<math>

\phi(x) = \begin{cases} a \le x < b : \frac{1}{b-a} \\ x < a \or x \ge b : 0 \end{cases}

</math>

where <math>a</math> is the lower bound, and <math>b</math> is upper bound. Note that this uniform distribution includes <math>a</math> but does not include <math>b</math>.

Bernoulli distribution

This distribution generates a Bernoulli distributed random number. The probability density function for the Bernoulli distribution is

<math>

\phi(x) = \begin{cases} x = 1 : 1 - p \\ x = 0 : p \\ x \ne 0 \and x \ne 1 : 0 \end{cases}

</math>

where <math>p</math> is the probability that the value <math>1</math> is returned. Note that the Bernoulli distribution is a discrete distribution.

Normal distribution

This distribution generates a Gaussian distributed random number. The probability density function for the Gaussian (normal) distribution is

<math>

\phi(x) = \frac{1}{\sqrt{2 \pi \sigma^2}} e^{\frac{(x-\mu)^2}{2 \sigma^2}}

</math>

where <math>\mu</math> is the mean of the distribution and <math>\sigma</math> the standard deviation of the distribution. Normally distributed random numbers are generated using the Box-Muller method:

   double random_normal(double m, double s)
   {
       double r, a, b;
       do { 
           a = 2*randunit()-1;
           b = 2*randunit()-1;
           r = a*a+b*b;
       } while (r>=1);
       return sqrt(-2*log(r)/r)*a*r*s+m;
   }

Lognormal distribution

This distribution generate a log Gaussian distributed random number. The log-normal probability density function is

<math>

\phi(x) = \frac{1}{\sqrt{2 \pi \sigma^2}} e^{\frac{(\log x-\mu)^2}{2 \sigma^2}}

</math>

where <math>\mu</math> the geometric mean, <math>\sigma</math> the geometric standard deviation.

Exponential distribution

The exponential distribution generates an exponentially distributed random number with probability density function

<math>

\phi(x) = \begin{cases} x \ge 0 : \lambda e^{-\lambda x} \\ x < 0 : 0 \end{cases}

</math>

where <math>\lambda</math> is the rate parameter of the distribution.

Pareto distribution

This distribution generates a Pareto distributed random number. The Pareto distribution is one in which the probability of drawing a number less than <math>x</math> is proportional to <math>x^{-k}</math> where <math>k</math> is a positive number. The probability density function of the Pareto distribution is

<math>

Pr \left ( X > x \right ) = \left ( \frac{x}{x_m} \right )^{-k}

</math>

when <math>x</math>≥<math>m</math>, <math>m</math> the minimum value, and <math>k</math> is the Pareto index value.

Sampled distribution

This distribution generates a number randomly sample uniformly from a list. The probability that the value a is drawn from the sample is

<math>

Pr \left ( a_k \right ) = \frac{1}{n}

</math>

where <math>n</math> the number of samples in the list and <math>k</math> spans the sample list. Note that the sampled distribution is a discrete distribution.

Note: The random distribution syntax in the GLM file omits the number of terms, but in C/C++ the number of terms must be included, e.g., random.sampled(1,2,3,4); in GLM, versus random_sampled(4,1.0,2.0,3.0,4.0); in C/C++.