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

## Contents

- 1 Synchronization
- 2 Clocks
- 3 Random numbers
- 3.1 Uniform distribution
- 3.2 Bernoulli distribution
- 3.3 Normal distribution
- 3.4 Lognormal distribution
- 3.5 Exponential distribution
- 3.6 Pareto distribution
- 3.7 Sampled distribution
- 3.8 Triangle distribution
- 3.9 Weibull distribution
- 3.10 Rayleigh distribution
- 3.11 Beta distribution
- 3.12 Gamma distribution

- 4 Convergence
- 5 Geospatial information
- 6 Service schedules
- 7 Units

# 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:rateunit; 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 *unit*s, 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

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

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

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

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

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

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

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++.

## Triangle distribution

[**TODO** --Dchassin 00:07, 7 March 2009 (UTC)]

## Weibull distribution

[**TODO** --Dchassin 00:07, 7 March 2009 (UTC)]

## Rayleigh distribution

[**TODO** --Dchassin 00:07, 7 March 2009 (UTC)]

## Beta distribution

[**TODO** --Dchassin 00:07, 7 March 2009 (UTC)]

## Gamma distribution

[**TODO** --Dchassin 00:07, 7 March 2009 (UTC)]

# Convergence

Convergence is controlled by limiting the number of iterations that the core will retry to solve for the current state of the system. This convergence limit is stored in the global variable called **global_iteration_limit** which is by default 100 iterations.

# Geospatial information

Every object is given a **latitude** and **longitude** property that the user may specify. If both coordinates are given, then the object may be output to a KML file for display by Google Earth. All the object properties are tabulated in the description of the object so that when a user click on the object’s icon, they can review the properties.

# Service schedules

Every object can be assigned an in-service (**in_svc**) and out-of-service (**out_svc**)date. For any given clock time, only those objects that are in service are synchronized.

# Units

Many properties have engineering units associated. Models may only specify properties in units that are compatible with the assigned units. The following units are recognized:

; The basic SI units are defined as follows: ; unit=0,0,0,0,0,0,1,0,16 ; m=-1,0,1,0,-1,0,4.121487e01,0,7 ; kg=0,0,0,0,1,0,1.09775094e30,0,10 ; sec=-2,0,1,0,-1,0,1.235591e10,0,7 ; A=2,1,-1,0,1,0,5.051397e08,0,7 ; K=2,0,0,-1,1,0,1.686358e00,0,7 ; cd=4,0,-1,0,2,0,1.447328E+00,0,7 ; Physical and Financial Constants #c=2.997925e8 ; speed of light (m/s) #e=1.602189246e-19 ; electron charge (C) #h=6.62617636e-24 ; Plank's constant (kg.m.m/s) #k=1.38066244e-13 ; Boltzman's constant (kg.m.m/s.s.K) #m=9.10953447e-31 ; electron rest mass (kg) #s=1.233270e4 ; average price of gold in 1990 ($/kg - 383.59$/oz) ; unit unit=0,0,0,0,0,0,1,0,16 ; dimensionless ratio=1 unit %=0.01 unit pu=1/unit /%=1/% ; Basic SI m=-1,0,1,0,-1,0,4.121487e01,0,7 kg=0,0,0,0,1,0,1.09775094e30,0,10 s=-2,0,1,0,-1,0,1.235591e10,0,7 A=2,1,-1,0,1,0,5.051397e08,0,7 K=2,0,0,-1,1,0,1.686358e00,0,7 cd=4,0,-1,0,2,0,1.447328E+00,0,7 1990$=0,0,0,0,1,1,1.097751e30,0,7 ; Angular measures pi=3.1415926536 rad=0.159155 unit deg=0.0027777778 unit grad=0.0025 unit quad=0.25 unit sr=0.5 rad ; Derived SI R=0.55555556 K degC=K-273.14 degF=R-459.65 g=0.001 kg N=1 m*kg/s^2 Pa=N/m^2 J=N*m ; Currency 1975$=0.42 1990$ 1980$=1.60 1990$ 1985$=0.83 1990$ 1995$=1.00 1990$ 1996$=1.01 1990$ $=1.00 1996$ CA$=0.85 $ ; Time min=60 s h=60 min day=24 h wk=7 day yr=365 day syr=365.24 day ; Length cm=0.01 m mm=0.001 m km=1000 m in=2.54 cm ft=12 in yd=3 ft mile=5280 ft ; Area sf=ft^2 sy=yd^2 ; Volume cf=ft^3 cy=yd^3 gal=0.0037854118 m^3 l=0.001 m^3 ; Mass lb=0.453592909436 kg tonne=1000 kg ; Velocity mph=1 mile/h fps=1 ft/s fpm=1 ft/min ; Flow rates gps=1 gal/s gpm=1 gal/min gph=1 gal/h cfm=1 ft^3/min ach=1/h ; Frequency Hz=1/s ; EM units W=J/s kW=1000 W MW=1000 kW Wh=1 W*h kWh=1000 Wh MWh=1000 kWh Btu=0.293 W*h kBtu=1000 Btu MBtu=1000 kBtu ton=12000 Btu/h ; ton cooling tons=1 ton*s ; ton.second cooling tonh=1 ton*h ; ton.hour cooling hp=746 W ; horsepower V=W/A ; Volt C=A*s ; Coulomb F=C/V ; Farad ohm=V/A ; resistance H=ohm*s ; Henry VA=V*A kVA=1000 VA MVA=1000 kVA Wb=J/A ; Weber lm=cd*sr ; lumen lx=lm/m^2 ; lux Bq=1/s ; Becquerel Gy=J/kg ; Grey Sv=J/kg ; Sievert S=1/ohm ; Siemens ; Custom EER=Btu/Wh ccf=1000 Btu therm=100000 Btu

Author: David Chassin, Pacific Northwest National Laboratory, August 2008