Core Guide

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

=Random numbers=

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

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 < b : \frac{1}{b-a} \\ x < 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:

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 < 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 > x \right ) = \left ( \frac{x}{x_m} \right )^{-k} $$

when $$x$$&ge;$$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.,  in GLM, versus   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
 * 1) c=2.997925e8 ; speed of light (m/s)
 * 2) e=1.602189246e-19 ; electron charge (C)
 * 3) h=6.62617636e-24 ; Plank's constant (kg.m.m/s)
 * 4) k=1.38066244e-13 ; Boltzman's constant (kg.m.m/s.s.K)
 * 5) m=9.10953447e-31 ; electron rest mass (kg)
 * 6) s=1.233270e4 ; average price of gold in 1990 ($/kg - 383.59$/oz)

unit=0,0,0,0,0,0,1,0,16
 * unit

ratio=1 unit %=0.01 unit pu=1/unit /%=1/%
 * dimensionless

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
 * Basic SI

pi=3.1415926536 rad=0.159155 unit deg=0.0027777778 unit grad=0.0025 unit quad=0.25 unit sr=0.5 rad
 * Angular measures

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
 * Derived SI

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 $
 * Currency

min=60 s h=60 min day=24 h wk=7 day yr=365 day syr=365.24 day
 * Time

cm=0.01 m mm=0.001 m km=1000 m in=2.54 cm ft=12 in yd=3 ft mile=5280 ft
 * Length

sf=ft^2 sy=yd^2
 * Area

cf=ft^3 cy=yd^3 gal=0.0037854118 m^3 l=0.001 m^3
 * Volume

lb=0.453592909436 kg tonne=1000 kg
 * Mass

mph=1 mile/h fps=1 ft/s fpm=1 ft/min
 * Velocity

gps=1 gal/s gpm=1 gal/min gph=1 gal/h cfm=1 ft^3/min ach=1/h
 * Flow rates

Hz=1/s
 * Frequency

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
 * EM units

EER=Btu/Wh ccf=1000 Btu therm=100000 Btu 
 * Custom

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