Setting up route accounts using the PIN Builder

Once you have built the correct route dataset (see the previous section the section called “Generating a Road Model”), two steps are required to define the road network model within Patchworks. This involves identifying the location of the core road data sets, and defining the accounts. Both of these tasks require modification of the PIN file, and both can be assisted with the PIN Builder.

[Note]Note

From the 'Optional PIN file elements' window you can chose Add Road Targets from the left hand side.

  1. In the "Road Network Data Folder" field select the folder that contains the four data model files (vertices, segments, destinations, linkages). These four data files were created using your road access file and the Build Road Segments tool (QuickTourIII/roads/).

  2. In the 'Road Shapefile' field select the road access shapefile that you used to create the four route data files (QuickTourIII/roads/access.shp).

  3. After validating your selections click "Next" to continue.

  4. Select the road label unique ID from the road access shapefile (ACCESS_). This will instruct Patchworks to link your shapefile segments to the data model files using this unique identifier.

  5. Click "Finish" to bring up the Road Accounts window that will allow you to specify product eligibility and additional transportation accounts.

Defining product eligibility by destination

If you recall from Quick Tour II (Quick Tour Part II: Transportation and Patches ) the C5 area has two destinations (MILL1 and MILL2) and two types of products being harvested from each block (Conifer and Deciduous volume). This is an example of a multiple product to multiple destination formulation. We will then select MILL1 from the list and send both the conifer and deciduous volume accounts here since the facility processes both. MILL2 however only processes conifer therefore only one summary account of conifer is sent to MILL2. It is then up to the model to figure out how much volume is sent to each mill based on the objectives you set for each scenario.

We can set up the above formulation by first defining the appropriate product eligibility:

[Note]Note

  1. Double click on the first destination name (destination.MILL1) to open the Destination Parameters window.

  2. Click the "+" button at the bottom of the window to define the "Products that go to this destination".

  3. An initial account will appear in the Input Account list. You may click on this account name to see a drop down list of all the account names defined in the "accounts.csv" file. Scroll through the list of choices and select the appropriate product accounts for this destination (product.Yield.managed.Decid and product.Yield.managed.Conif).

  4. We will duplicate these accounts to create new summary accounts that can be used to track mill quotas and set objectives in the model. Double click in the 'Duplicate Account' field next to the product.Yield.managed.Decid input account. Type the name of the new summary account that will track all the deciduous volume transported to MILL1 (product.Mill1.Yield.Decid). Likewise, create a duplicate account for the conifer volume (product.Mill1.Yield.Conif).

  5. Click 'Finish' when input and duplicate accounts have been defined for MILL1. You will return to the 'Road Accounts' window.

  6. Double click on 'destination.MILL2' to define product eligibility for this destination.

  7. Under the 'Products that go to this destination' window chose the 'Input Account' for MILL2 by clicking the '+' at the bottom of the window and scrolling to product.Yield.managed.Conif.

  8. Duplicate this account to create a new summary account to track the conifer volume transported to Mill2 by double clicking in the 'Duplicate Account' field (product.Mill2.Yield.Conif).

  9. Click 'Finish' to return to the 'Road Accounts' window.

Defining route account names

You may have noticed that in the 'Destination Parameters' window there were input parameters for the name of the accounts that track costs for their destination. These accounts identify the haul cost, build cost and maintenance cost for the destination.

[Tip]Tip

The build and maintain account names are filled in with 'total' account names by default. This means that all the building and maintenance for all destinations are summed into the same total account (i.e. the same name is defined for each destination). This is the default to avoid negative accounting that might occur when a road is shared by more than one destination.

The route haul account should have the destination as part of the name to identify that this is the account that summarizes the total hauling cost incurred to bring the specified products to the destination. This account is summing the cummulative volume of the products multiplied by the hauling cost of each segment used to bring the wood to the destination.

The route build account name should be a total and should be the same name for all destinations (see the note above). The route maintenance account name should also be a total and be the same for all destinations.

[Tip]Tip

The account names are filled in with default values when the window is opened however they can be changed by double clicking and editing the text. Keeping a similar nomenclature (ie. starting with the prefix 'route') will help organize your accounts and work with other Patchworks structures, such as reports and the account directory tree.

We will use the default account names for the route cost accounts:

  • Haul accounts: route.MILL1.haul and route.MILL2.haul

  • Build account: route.total.build

  • Maintenance account: route.total.maint

Adding an 'unutilized' route account

You may have noticed another button on the bottom of the Road Accounts wizard that says 'Add or remove unutilized...'. An unutilized account in a Patchworks route model is essentially a 'fake' destination that collects and summarizes products that the destinations in your model do not use.

Consider our sample forest with two mills: one takes only conifer and the other takes both conifer and deciduous. Conifer is in short supply, but there is a surplus of hardwood. If a block was harvested that was a mixed wood type, the conifer could be sent to either mill, and the hardwood could be sent to the hardwood mill, or left in the bush as surplus. We can implement the 'surplus' situation with an unutilized account, and let the model choose what wood to send to the hardwood mill and what to leave behind. Without the unutilized account, all hardwood would be force to go to the hardwood mill, perhaps causing a very unrealistic situation.

Defining an unutilized account is very similar to defining the other route accounts discussed above, however you must create the unutilized account and then direct certain products to that 'fake destination'.

Follow these steps to create an unutilized account for our model...

[Note]Note
  1. Click the 'Add or remove unutilized...' button at the bottom of Road Account wizard. This will open the 'Advanced destination parameters' window. On this screen you will be able to add an artifical destination to consume the excess wood.

  2. Click the '+' button at the bottom of the window to add an account.

  3. A default account name of 'product.unutilized.' appears in the account window. This is a product account since it will be summarizing the volume harvested from blocks that is not transported to a destination. Edit this account name by clicking the field and typing: product.Unutilized.Decid.

  4. Click 'Finish' when you have added the necessary account.

  5. You will notice that your unutilized product account appears in the 'Road Accounts' window list of destinations. Double click on your new account to open the 'Destination Parameters' window.

  6. The 'Destination Parameters' dialog box is different for an unutilized account since no transportation charges are necessary (it's not a really destination!). Simply click the '+' button at the bottom of the window to add an account. This activates the drop down list of accounts previously defined in the 'accounts.csv' file. Chose the summary account of products that will be eligible for this unutilized product account (product.Yield.managed.Decid). No duplicate account is required.

  7. Click 'Finish' when all the necessary products have been directed to this account.

  8. Click 'Finish' in the Road Accounts window to return the 'Optional PIN file elements' window and complete the road account definitions.

Your route accounts are now complete. You will notice that 'Road accounts' are listed in the Optional PIN file elements window. All harvested products have been directed to the correct destinations (real or fake!) and all transportation costs will be accounted for according to your definitions. The required PIN file code will be generated according to these definitions when all elements required have been added.

Creating patch account definitions using the PIN Builder

Patch targets are defined to the model in the PIN file like the route accounts. The required PIN file code can be generated easily and error free using the PIN Builder.

Adding the topology file

Patch accounts require explicit definition of topological relationships. The topological adjacency relationships required can be defined using either the raster or vector Proximal Topology (Proximal Topology (raster)) tool. Once this file has been created it can be referred to in the PIN Builder.

We have already created our topology file in the section called “Creating Block Topology” of this Quick Tour. We will use this topology file to define the block relationships required for the patch accounts (better go back if you skipped that step!).

[Note]Note
  1. From the 'Optional PIN File Elements' window in the PIN Builder chose the 'Add Topology' button from the left hand side. This will open the 'Topology File' dialog (see Figure 173, “PIN Builder 'Add topology' dialog”).

  2. In the 'Toplogy File' dialog navigate to the previously defined proximal topology file (QuickTourIII/tracks/blocks_topology_200.csv).

  3. Adjust the threshold search distance in meters. The threshold search distance can be filtered from the original threshold search distance that was used to create the topology file (less than or equal to the original search distance). For example, if a distance of 500m was used to search for neighbour relationships in the topology file a threshold of 200m could be used in the model to search for disturbance patch members.

    We will use the original search distance of 200m.

  4. Click 'Finish' when a valid topology file has been selected.

[Tip]Tip

The PIN Builder only allows definition of a single topology file. Once a topology file has been added in the PIN Builder the 'Add Topology' button will be inactive. Multiple topology files can be used (to allow different definitions of proximal distance for different patch accounts), but these need to be defined manually using PIN file commands.

Figure 173. PIN Builder 'Add topology' dialog


Define patch account name and size classes

Patch accounts are created by specifying the criteria account and the upper and lower limits of the size range. When you define a patch account the model will create a set of six sub-accounts (see the section called “Patch Sub-Account Types”). The names for these accounts will be created using a user specified prefix, and a user specified size class label, and a system specified sub-account name. All patch accounts using the same criteria must be given the same prefix. The size labels are arbitrary but should meaningfully describe the account.

[Note]Note
  1. Click 'Add patch target' from the 'Optional PIN Elements' window of the PIN Builder to open the 'Patch Account' dialog.

  2. From the drop down list select the predefined patch criteria summary account (the list will include all accounts in the accounts.csv file). Choose product.Treated.CC from the list.

  3. Define a name prefix in the 'Patch account name prefix' box. By default the string 'patch.' is displayed. Edit the prefix by clicking in the box and typing the remaining text. For example, if you are defining disturbance patches you may wish to add 'patch.disturbance.' or if you are defining harvest patches you may add 'patch.harvest.'. Patchworks will create account names by appending the size class label and the sub account type to the prefix.

    Since we are using a harvest criteria we will define our patch account prefix as patch.harvest.

Figure 174. PIN Builder 'Patch account' dialog


[Note]Note
  1. Create patch size categories by editing the 'Low' and 'High' size class ranges and providing a label for each range defined. The range label will be appended to the patch prefix for each category defined.

  2. Add new categories by using the '+' button at the bottom of the dialog and edit the range and label as required.

  3. To remove a category select the row and use the '-' button at the bottom of the window.

  4. We will define the following size classes:

    • Low: 0 High: 10 Label: 0_10

    • Low: 10 High: 50 Label: 10_50

    • Low: 50 High: 999999 Label: 50+

Add patch account code to the PIN file

The PIN Builder will translate the patch account size class categories into the properly formatted Beanshell code that can be copied and pasted into the PIN file. After the patch account definitions are added to the PIN file, these accounts will be created everytime the model loads.

[Tip]Tip

The PIN Builder will automatically generate commands for other patch related features:

  • map layers displaying patch locations

  • area and frequency reports by patch size class

These other features are optional, and this section concentrates on the patch account code. You can refer to the section called “The PIN file” for more general PIN file information or the section called “Patch Report” for more information on patch reports.

[Note]Note
  1. Click the 'Show Code' button in the Patch Account dialog to translate the patch account definitions into Beanshell code.

  2. A seperate window will appear with the required code. This code can be cut and pasted into an existing PIN file in the appropriate places.

  3. If you click 'Finish' in the 'Patch Account' dialog to return to the 'Optional PIN Elements' window you can also click 'Show Code' from the left-hand side. This will generate a complete PIN file with the elements you have defined thus far, including the patch accounts, topology, maps and reports.

We can look at an example of the code that would be generated by the PIN Builder and added to the PIN file in the Target Initialization section of the PIN file (reference PIN file section image).


int Patchworks_TargetInit() {                                1

control.inputTopology(new File("topology.csv"), 50d);        2

   if (usePatching) {                                        3 

      /*
       * Create the patch accounts
       */
      control.addPatchTarget("patch.disturbance.young",      4
                             "patch.disturbance.0_50",       5
                             0.0f, 50.0f);                   6
      control.addPatchTarget("patch.disturbance.young", 
                             "patch.disturbance.50_150", 
                             50.0f, 150.0f);
      control.addPatchTarget("patch.disturbance.young", 
                             "patch.disturbance.150_250", 
                             150.0f, 250.0f);
      control.addPatchTarget("patch.disturbance.young", 
                             "patch.disturbance.250_2500", 
                             250.0f, 2500.0f);
      control.addPatchTarget("patch.disturbance.young", 
                             "patch.disturbance.2500+", 
                             2500.0f, 50000000.0f);
   }                                                       
   return 1;
}

   

1

This is the start of the Target Initialization section of the PIN file. Paste the patch account and topology references within this section.

2

Reference to the location of the topology file and the threshold distance that was specified in the PIN Builder.

3

This is a reference to the boolean flag created at the beginning of the PIN file that can easily turn on (true) or off (false) the patching accounts. The variable is typically defined at the beginning of the PIN file:

   boolean usePatching = true;
   

Enclosing patch specific code in the PIN file in this type of 'if' statement allows you turn on/off the patches by changing the flag in one place at the beginning of the file. This saves you from hunting through the PIN file to comment out or remove patch account references if you do not wish to use patching in some scenarios.

4

The first argument is the reference to the patch criteria summary account.

5

The second argument is the account name for the specific size class category. The PIN Builder has concatenated the patch account prefix and the patch size categories labels.

6

The third argument is the lower range limit and the fourth argument is the upper range limit for the category. The 'f' signifies that this value is a floating point.

[Important]Important

Inclusion in the patch size class is determined by the sum of the patch criteria value being:

  • Greater than the lower range limit and

  • Less than or equal to the upper range limit

Note that this is the opposite for other ranges in Patchworks (e.g. numeric map ranges, ranges for category reports). Inclusion in these types of ranges is greater than or equal to the lower limit and less than the upper limit.

The reason for the difference is to exclude zero values from patch size category starting at 0 ha. if zero values were included, then all non-patch polygons would also be included in this category.

Add route account code to the PIN file
[Tip]Tip

If you are not familiar with the PIN file thus far, read the section called “The PIN file” to get a basic understanding or explore the sample PIN file that was included with your software in a text editor.

Once all the destinations have been assigned the necessary products and the transportation cost accounts have been edited to summarize information specific to your model you are ready to add this information to the PIN file. There are three main sections of the PIN file which we will be referring to in this section (xref the Basic PIN sections diagram or add the diagram again):

  • Global variables - defines file locations

  • Target initialization - customize targets/accounts

  • Model Setup - adjust initial targets and scheduler parameters, add map layers and reports

Use the 'Show Code' button on the bottom of the 'Road Accounts' wizard in the PIN Builder. This will translate all of your route account definitions into the correct PIN file code (written in Beanshell). This code can then be copied and pasted into the appropriate sections of your current PIN file.

There are three sections of code generated from the Road Accounts PIN Builder:

  • Route accounts for each destination

  • Route map layers for each destination

  • Route cost report for each destination

This section deals primarily with Route Account explanations however more information is available in the section called “The PIN file” regarding pasting the map and report definitions in the appropriate sections.

The following is an example of the beanshell code generated to define route accounts for the sample dataset using the PIN Builder.

/*
 * Add the following to the TargetInit() function
 */
      /*
       * Add road account for destination.Kapuskasing
       */
      control.addExclusiveAccount("product.Yield.managed.SpeciesGroup.SPF", "destination.Kapuskasing");
      control.addRouteHaulAccount("destination.Kapuskasing", "route.Kapuskasing.haul");
      control.addRouteBuildAccount("destination.Kapuskasing", "route.total.build");
      control.addRouteRepairAccount("destination.Kapuskasing", "route.total.maint");
      control.addRouteProductAccount("destination.Kapuskasing", "route.Kapuskasing.product");


     /*
       * Add road account for destination.Timmins
       */
      control.addExclusiveAccount("product.Yield.managed.SpeciesGroup.IntHdwd", "destination.Timmins");
      control.addRouteHaulAccount("destination.Timmins", "route.Timmins.haul");
      control.addRouteBuildAccount("destination.Timmins", "route.total.build");
      control.addRouteRepairAccount("destination.Timmins", "route.total.maint");
      control.addRouteProductAccount("destination.Timmins", "route.Timmins.product");

      /*
       * Add road account for product.unutilized.birch
       */
      control.addExclusiveAccount("product.Yield.managed.Species.Bw", "product.unutilized.birch");

	

This code should be copied and pasted into the TargetInit() section of the PIN file so that these definitions are loaded each time you start your model.