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.

# 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

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

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

## Bernoulli distribution

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

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

where $p$ is the probability that the value $1$ 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

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

where $\mu$ is the mean of the distribution and $\sigma$ 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

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

where $\mu$ the geometric mean, $\sigma$ the geometric standard deviation.

## Exponential distribution

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

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

where $\lambda$ 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 $x$ is proportional to $x^{-k}$ where $k$ is a positive number. The probability density function of the Pareto distribution is

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

when $x$$m$, $m$ the minimum value, and $k$ 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

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

where $n$ the number of samples in the list and $k$ 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
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