After the core model, the remainder of the model is the stochastic declarations section:

 

! *** STEP 2 *** - Define Random Variables;

 

!The random variables are period 2's demand and cost.;

@SPSTGRNDV( 1, COST_2);

@SPSTGRNDV( 1, DEMAND_2);

 

! *** STEP 3 *** - Define initial decision and recourse variables;

 

!The initial decision is how much to purchase in period 1;

@SPSTGVAR( 0, PURCHASE_1);

!Period 2 purchases are a recourse variable after

the weather reveals itself;

@SPSTGVAR( 1, PURCHASE_2);

 

! *** STEP 4 *** - Assign distributions to the random variables;

 

!Declare a discrete distribution called 'DST_DMD' with

three outcomes and two jointly distributed variables

(i.e., Demand and Cost);

@SPTABLESHAPE( 'DST_DMD', 3, 2);

 

!Load the three equally likely outcomes into 'DST_DMD';

!Dist Name  Probability Cost  Demand;

@SPTABLEOUTC( 'DST_DMD',       1/3,      5.0,      100);

@SPTABLEOUTC( 'DST_DMD',       1/3,      6.0,      150);

@SPTABLEOUTC( 'DST_DMD',       1/3,      7.5,      180);

 

!Declare a specific instance of the 'DST_DMD' distribution,

naming the instance 'DST_DMD_1';

@SPTABLEINST( 'DST_DMD', 'DST_DMD_1');

 

!Bind Period 2 Cost and Demand to the distribution instance;

@SPTABLERNDV( 'DST_DMD_1', COST_2, DEMAND_2);

Stochastic Declarations for Gas Buying Example

We use this section to identify all the random variables and their distributions.  A detailed breakdown of the stochastic declarations follows.

Step 2 - Identifying the Random Variables:

The next step in building our sample SP model is to identify the random variables.  The random variables are the variables that are stochastic by nature and whose values are not known before we must make our initial decisions. The @SPSTGRNDV function is used to identify random variables. @SPSTGRNDV accepts two arguments: the random variable's name and its stage.

In this example, there are two random variables, the second period cost and demand, and we identify them via @SPSTGRNDV in the following to statements:

!The random variables are period 2's demand and cost.;

@SPSTGRNDV( 1, COST_2);

@SPSTGRNDV( 1, DEMAND_2);

Note that we have indicated that the two variables are in stage 1.  This may seem somewhat odd, in that they are relevant to period 2.  However, you will recall that the first set of random variables to become known after our initial decision belong to stage 1.  If this was a multiperiod model, period 3's random variables would belong to stage 2, and so on.

Step 3 - Identifying the Initial Decision and Recourse Variables:

The next step is to identify the the initial decision variables and the recourse variables.  Unlike the random variables, which are under Mother Nature's control, the initial decision and recourse variables are under our control.  The initial decision variables occur at the very outset, before any of the random variables become known, and are always assigned to stage 0.  The recourse variables are the subsequent decisions we make after learning of the outcomes of the random variables.  Recourse variables that are decided after the stage N random variables become known are assigned to stage N as well.

The @SPSTGVAR function is used to identify initial decision and recourse variables. @SPSTGVAR accepts two arguments: the variable's stage and its name.

In our example, there is one initial decision, which is PURCHASE_1, the amount of gas to purchase in period 1.  The weather then reveals itself and our recourse variable is PURCHASE_2, the amount to purchase in period 2.  We identify this information with the two statements:

!The initial decision is how much to purchase in period 1;

@SPSTGVAR( 0, PURCHASE_1);

 

!Period 2 purchases are a recourse variable after

the weather reveals itself;

@SPSTGVAR( 1, PURCHASE_2);

It turns out that before an SP model can be passed to the SP solver engine, all variables and rows must be assigned stage values. You will note that we have not done this.  Specifically, we have not assigned stages to any of the rows nor to the variables: PURCHASE_COST, HOLD_COST, PURCHASE_2, INVENTORY_1 and INVENTORY_2. The reason we have not made these stage assignments is that LINGO can deduce the stages of the remaining rows and variables from the minimal stage information we've already supplied.  We will examine this stage deduction feature in more detail in the next section.  In the meantime, the following guidelines should suffice:

        •  All random variables must be assigned to a stage using @SPSTGRNDV.

        •  Any initial decision or recourse variable that belongs to stage N that does not depend either

            directly, or indirectly, on another variable  (random or otherwise) declared to be in stage N must

            be explicitly assigned to stage N using @SPSTGVAR.

        •  If you are uncertain whether a particular variable must be explicitly assigned to a stage, or

            not, then it doesn't hurt to assign it anyway using @SPSTGVAR.

        •  In general, stage assignment for rows should be left to LINGO.  Each row will be assigned

            to the stage equal to the maximum stage of the variables appearing in that row.  However,

            if you wish to explicitly specify a row's stage, you may always do so using @SPSTGROW.

Step 4 - Declare Distributions

Next, we need to declare the joint probability distribution for the random variables COST_2 and DEMAMD_2.  In this case, we will be using  an outcome table distribution, and in order to declare our distribution we will make use of the scalar-based functions: @SPTABLESHAPE and @SPTABLEOUTC, @SPTABLEINST and @SPTABLERNDV.

@SPTABLESHAPE initializes the distribution with a name, number of outcomes and number of jointly distributed variables, while @SPTABLEOUTC is called once for each outcome to load information relevant to each outcome:

!Declare a discrete distribution called 'DST_DMD' with

three outcomes and two jointly distributed variables

(i.e., Demand and Cost);

@SPTABLESHAPE( 'DST_DMD', 3, 2);

 

!Load the three equally likely outcomes into 'DST_DMD';

!            Dist Name  Probability     Cost     Demand;

@SPTABLEOUTC( 'DST_DMD',       1/3,      5.0,      100);

@SPTABLEOUTC( 'DST_DMD',       1/3,      6.0,      150);

@SPTABLEOUTC( 'DST_DMD',       1/3,      7.5,      180);

@SPTABLESHAPE accepts three arguments: a name for the distribution, the number of outcomes and the number of jointly distributed variables in the distribution.  In this case, we've titled the distribution 'DST_DMD', and it has three outcomes along with two jointly distributed variables.

Now, to be able to actually apply the distribution to random variables we need to declare an instance of the distribution.  By doing things this way, it's possible to reuse the same outcome table on more than one set of random variables.  We declare an instance of a particular distribution using the @SPTABLEINST function, which accepts two arguments - the name of the parent distribution and a new name for the instance of the distribution.  In the case of our example, we do the following:

!Declare a specific instance of the 'DST_DMD' distribution,

naming the instance 'DST_DMD_1';

@SPTABLEINST( 'DST_DMD', 'DST_DMD_1');

Or, in words, we create an instance of the DST_DMD distribution, which we name DST_DMD_1.

Our last step is to associate, or bind, the random variables to the instance of the distribution.  Specifically, we wish to bind the cost and demand random variables from period 2 to the DST_DMD_1 distribution instance.  We do this with the following expression:

!Bind Period 2 Cost and Demand to the distribution instance;

@SPTABLERNDV( 'DST_DMD_1', COST_2, DEMAND_2);

Our SP model has now been fully set up and we are now ready to have LINGO solve the model.