Materials

The potential application of using material primitives to define new custom units is an important usage of Material primitives and is discussed in the verification section of the reference. Material primitives, however, have a number of additional capabilities that we will now discuss. Many types of substances may be simulated with a simple number. For example, the quantity of deer in a forest or the number of dollars in a bank account can be determined with one value (45 deer; $345.38). More complex materials, however, cannot be defined in such a simple manner.

For instance, let us look at the case of water quality. Water may contain many different substances. When examining the quality of water, we need to look at how much oxygen, nitrogen, phosphorous, and other solids or minerals it contains. Fortunately, Simgua lets you define materials that contain sub-materials using a special syntax. The format for this syntax in your equations is as follows:

The type is the type of the material and is the name of a Material primitive which you have added to your model. The base level is the quantity of the containing substance. Both the base level and type are optional. The sub-quantities are the quantities of the sub-materials within the base.

So, if we wanted to model a sample of 100 m³ of water containing 7.2 grams of oxygen and 2.3 grams of nitrogen we define a material using the following:

Alternatively, if we had created a Material primitive in our model called “Water,” we could use the following:

When you add, subtract, or otherwise manipulate materials, Simgua will handle the combination of their different sub-materials. For example, when we carry out the following operation:

The resulting sample of water would be 112 m³ in volume with 9.2 grams of oxygen and 5.3 grams of nitrogen.

 You can access or set the sub-materials of a material using the following dot notation:

Thus we could have just as easily created our water sample using the following set of statements:

Often, it can become difficult to keep a handle on material details when defining complex materials. In this case, you may consider developing a component designed to allow you to easily declare these materials and their sub-materials. For instance, the wastewater treatment plant components included with Simgua include a Water Source component that allows you to specify the qualities of the water.

One other handy tool when using materials is the “amount” method. This can be used when you want to access a certain quantity of a parent material with the same qualities as the parent. So if you wanted to withdraw 100 liters of water from a primitive called “Bucket”, you could use the following in our outflow’s equation:

If you had just set the flow rate to be 100, the water flowing from the bucket would be completely pure and not contain any of the pollutants that were in the original water in the bucket. The pollutants would be left behind in the bucket and would steadily concentrate.

Although it is not strictly necessary, you can add a material primitive to your model which gives you additional control over the behavior of the material samples.  The material primitive allows you to define how different sub-materials are combined. Two combination methods are available: Summation and Average. Summation is a combination method suitable for counts of objects (like the number of fish in water). When combined, the sub-materials will simply be added. Averages are suitable for concentrations (like water temperature). When combined, the sub-materials will undergo a weighted average. If no combination method is specified for a sub-material, Simgua will default to the summation method.

You must explicitly tag a material as being an instance of a certain Material primitive. You can do this either when the material is created or later on by setting its Units property. So if you have a material called Water, you could set the material sample called myMaterial to become a “Water” sample by doing the following:

The material units will automatically be propagated for all offspring of the material (i.e. the result of multiplying it or adding it to another material). If two materials with different types are combined, one type will randomly be chosen for the resultant material.

The Material primitive also allows you to attach a block of Visual Basic code to the material that is executed each time period. This is the On Step property. For instance, in the water quality example you could attach a block of code that carried out bacterial consumption of oxygen and reaeration of the water at each stage of the simulation. Thus you could pass your water sample through a number of different treatment stages without having to worry about implementing reaeration at each stage. The On Step code will be wrapped within a Visual Basic subroutine within the material itself. The function will have access to any functions or classes you define in the same component container as the material primitive.

Thus, if you had a material containing fish that bread at a rate of two additional fish per time step, you could put the following in your material’s On Step property:

Finally, you can define a material helper method called get. The get method is a very flexible function call that you can use to implement material specific functions or properties. It can take a variable number of arguments of any type which are then available to your code in the Variant array args. The function returns a Variant (i.e. any type of data you desire). The get function could serve a wide range of purposes depending on your model. For instance in the Water material, we could implement a get method that returns the density of the water or other physical properties which are determined from the water’s temperature and a lookup table.

Back to the overview of all primitives.