op_dist_load()
Abstract
Loads a distribution for use in generating streams of stochastic values.
Syntax
op_dist_load (dist_name, dist_arg0, dist_arg1)
| Argument | Type | Description |
|---|---|---|
dist_name |
const char* |
name of the distribution to be loaded [The value is usually a string constant, such as “poisson”.] |
dist_arg0 |
double |
optional argument #0 of the distribution |
dist_arg1 |
double |
optional argument #1 of the distribution [The values of dist_arg0 & dist_arg1 are ignored by this KP when loading distributions that do not require these values. However, to have proper calling syntax for this KP, valid double values must be passed as placeholders.] |
Return Type
Distribution*
Pointer to the loaded distribution. If a recoverable error occurs, the constant OPC_NIL is returned.
[The value returned by this KP is typically stored in a state variable declared with the Distribution* type, and later passed to the related KP op_dist_outcome().]
Example
Excerpt from: process model (jsd_gen); state (init); enter execs.
/* Load the distribution function for the packet interarrival times. */
next_dist = op_dist_load ("exponential", ia_time, 0.0);
if (next_dist == OPC_NIL)
jsd_gen_error ("Unable to load packet arrival distribution.");
/* Load the distribution function for the job types. */
job_type_dist = op_dist_load ("uniform_int", 1, job_type_range);
if (job_type_dist == OPC_NIL)
jsd_gen_error ("Unable to load job type distribution.");
Details
Distributions are specified by name, and can be either predefined analytical distributions, user-defined PDF models prepared using the PDF Editor, or EMA-specified PDF models. Predefined distributions (such as bernoulli and poisson) are implemented as algorithms that are parameterized by invoking this KP, via one or two numeric arguments. The other two types of distributions are tabular data files (with the filename suffix .pd.s) that are loaded into memory by invoking this KP. Note that even predefined distributions have corresponding .pd.s files in the models/std/base directory, but these zero-length files are only present so that the distributions appear in application menus, and they do not actually contain any distribution data. When used to load a user-defined PDF, dist_arg0 and dist_arg1 are ignored.
Purpose
Provides a mechanism to prepare a probability distribution for use as a stochastic number generator. The most common application of this is to load a distribution that will provide the stochastic interarrival times that occur between packets generated in a processor. However, any simulation parameter that should be stochastically distributed can be derived from the distribution facility. The actual stochastic values are obtained by calling the procedure op_dist_outcome(). The predefined distributions that can be passed for dist_name are discussed in Package Overview.
Errors
- Program Abort: Segmentation violation. (due to an invalid distribution name pointer)
- Program Abort: Allocation of memory failed.
- Recoverable Error: Distribution name (
<dist_name>) is unrecognized.
Reference
- Use the KPs op_dist_outcome() or op_dist_outcome_ext() to obtain a stochastic value from a loaded distribution
- Use the KP op_dist_uniform() to obtain a uniformly distributed random value
- Use the KP op_dist_unload() to free the memory used by a distribution