gldcore

Loading Models

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 TODO - link - link to appropriate page for more info.

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

STZhh[: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.

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

\[\phi(x) = \begin{cases} a \le x < b : \frac{1}{b-a} \\ x < a \lor 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 \land 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 < 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\)≥\(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 - EMPTY - Triangle distribution [Dchassin] 00:07, 7 March 2009 (UTC)

Weibull distribution

TODO - EMPTY - Weibull distribution [Dchassin] 00:07, 7 March 2009 (UTC)

Rayleigh distribution

TODO - EMPTY - Rayleigh distribution [Dchassin] 00:07, 7 March 2009 (UTC)

Beta distribution

The probability density function for the beta distribution is

\[\varphi(x;a,b) = \frac{\Gamma(a+b)}{\Gamma(a)\Gamma(b)}x^{a-1}(1-x)^{b-1}\]

where \(a\) and \(b\) are the parameters of the distribution and \(\Gamma(z)\) is the gamma function.

Gamma distribution

TODO - EMPTY - Gamma distribution [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

Data Transforms

Mainloop state

The global variable mainloop_state is used to control the main time synchronization loop in GridLAB-D™'s core. The main loop state can take the follow values:

INIT

This state indicates that the main loop has not yet completed initialization. Sometimes, initialization can take a long time, particularly if the GLM file contains complex schedules that need to be compiled. While in this state, the clock is typically set to INIT also.

RUNNING

This state indicates that the main loop is running. The clock should be expected to change as it advanced.

PAUSED

This state indicates that the main loop is paused. This should only occur if a) server mode is active, b) the pauseat time has been specified, and c) the clock has reached the pauseat time. The simulation can only be resumed by setting a new pauseat value using either the appropriate control message or directly setting the pauseat value to a future date/time.

DONE

This state indicates that the main loop has completed. This occur when the simulation is either at steady state or the stoptime has been reached.

LOCKED

This state indicates that the main loop is stuck because of a lock. This should never happen. If it does, then it is more than likely caused by an error that results in a deadlock