Answers to Frequently Asked Questions
Chances are if you are wondering about something... someone else may have already wondered! This section provides some quick answers to frequently asked questions about the Patchworks software and provides links to more detailed info within the documentation. This is the best place to find answers to practical implementation problems, as well as solutions to data preparation and model formulation tasks. If it's not here contact us with your question!
A. Licensing
B. Installation and Product Activation
C. Performance
D. Technical Support
E. Modelling with Patchworks
F. Target Troubles
G. Customizing Patchworks
H. XML Questions
I. Matrix Builder Questions
J. Woodstock Conversion Questions
A. Licensing
A.1.
How many computers can I install the software on?
A.2.
Do you mind if I give copies of your software to my
friends?
A.3.
Can I lend my copy of Patchworks to a friend, consultant,
or another agency?
A.4.
Can I transfer the software on to another computer?
A.5.
Can I make copies of the installation CD?
A.6.
Do I need to purchase any other software?
A.1. How many computers can I install the software on?
A single workstation license for Patchworks permits you to use the software on a single workstation. You are only allowed to install the software on a single workstation at a time.
A.2. Do you mind if I give copies of your software to my friends?
No, you may not distribute copies of the Patchworks software to anyone. You are licensed to use a single copy of Patchworks on a single workstation. (We really have been asked this question!)
A.3. Can I lend my copy of Patchworks to a friend, consultant, or another agency?
The license agreement for Patchworks does not permit you to lend or provide the software to anyone who is not covered by your license agreement. If you need to let someone else use the software contact Spatial Planning Systems to make arrangements to extend your license agreement.
A.4. Can I transfer the software on to another computer?
Yes you may transfer the software to another workstation in your organization. To do so you must fully uninstall the software from the original workstation, and then install the software on the preferred machine. After transferring the software you will require a new product activation code. See the product activation FAQ for instructions on how to obtain a product activation code.
A.5. Can I make copies of the installation CD?
No, you are not allowed to make copies of the installation CD. You are not allowed to make any copies of the Patchworks software, except for routine backup copies of your entire workstation.
A.6. Do I need to purchase any other software?
You do not need to purchase any other software to operate Patchworks. Patchworks does require two additional software packages in order to be functional: the Java 2 Standard Edition runtime environment, and a modern web browser such as Firefox or Microsoft Internet Explorer. These packages can be downloaded off of the internet at no charge.
In addition, you may find that other software packages are useful to assist in advanced analytical operations. For example, in our consulting projects we often use ArcView and ArcView Spatial Analyst, or Arc/Info, and we often use Microsoft Excel and Microsoft Access.
B. Installation and Product Activation
B.1.
What are the minimum system requirements?
B.2.
How do I install the software?
B.3.
What is a product activation code, and how do I get one?
B.1. What are the minimum system requirements?
The minimum computer requirements to install and run the Patchworks model include:
-
32 or 64-bit Windows 7 or Windows 10. A 64-bit operating
system is highly recommended for best
performance.
- X86 or AMD64 compatible CPU
- Memory depends on the complexity of the model, but 2Gb RAM is generally the minimum for medium sized problems
- Minimum 1Gb available disk space (50Mb for software, 640Mb for the sample datasets, and the remainder for working space)
- A USB port for the hardware key if not using a floating license
- An up-to-date web browser such as Firefox or Chrome
B.2. How do I install the software?
Follow the procedure described in the Patchworks installation guide.
B.3. What is a product activation code, and how do I get one?
A product activation code is a special code word that Patchworks requires in order to validate your installation. Product activation codes are unique to individual workstations and are not transferable or reusable.
There are several circumstances when you will need to obtain a product activation code:
- when you first install the Patchworks software;
- when you transfer the Patchworks software to a different workstation;
- when you install a major upgrade to the Patchworks software.
The Patchworks software will prompt you when you require a product activation code. The software will present a dialog describing the steps to be followed. One of the steps is to print out a 'Product Activation Request Form', which must be signed and sent by mail or fax to Spatial Planning Systems.
Spatial Planning Systems will fill orders for product activation codes within 24 hours. There is no charge for product activation codes.
C. Performance
C.1.
Why does the model take 2 minutes to start up?
C.2.
Why does the model take half an hour to start up?
C.3.
Why doesn't the model start up?
C.4.
How can I make the model run faster?
C.5.
What minimum RAM and processing speed would you recommend
for our large coverages to run best?
C.6.
The ProximalTopology tool quit after lengthly processing. What's up?
C.7.
How do I add extra command options with the new
Application Launcher, like this extra java option:
-Dsun.java2d.d3d=false?
C.1. Why does the model take 2 minutes to start up?
The Patchworks model performs a substantial amount of work when it first starts up to read in data files and initialize program control structures. Five minutes is not an unusual amount of time for the start up process.
C.2. Why does the model take half an hour to start up?
Under normal circumstances Patchworks should not take more than 2 minutes to load and prepare for execution. There are several reasons why the model might take an unusually long time to load:
- Patchworks may take a long time to start up if the datasets are located on optical media or if they are stored on a remote file-server. To ensure best performance it is a good idea to store all of the data files on a local hard disk within your workstation.
- Patchworks may take an exceptionally long time to load and will perform very poorly if your workstation is equipped with insufficient RAM. In our experience small models require a minimum of 512Mb of RAM, and medium sized models require 2Gb or greater. Problem size is difficult to describe in simple terms, but is related to the number of block polygons, the complexity of the growth and yield database, and the type and number of spatial design objectives.
C.3. Why doesn't the model start up?
If you are having problems getting the software to operate try the following trouble-shooting checklist:
- Check the amount of available RAM. Open the 'System' icon in the control panel. The amount of installed RAM is listed under the heading of 'Computer'. Make sure that you have sufficient RAM for the problem that you are trying to load.
- Check the version of Java that you are using. To do this open a 'Command Prompt' window, and type in the command java -version. If Java is installed correctly it will report that it is running version 1.8 or higher.
- Check that the hardware security key is inserted in the USB port, or that you have correctly enabled the floating license option.
- If you have just installed Patchworks for the first time then you will need to reboot the computer.
C.4. How can I make the model run faster?
We have tuned the Patchworks model to achieve the best performance possible. The speed at which the model will converge on solutions depends on characteristics of the input datasets and objectives that you have set. Some features of the Patchworks model take more resources than others. You should be aware of the following issues:
- Patchworks uses CPU resources to update the mapview while the optimizer is running. If you disable the mapview (by unchecking the active themes) these resources will be available to solve the problem faster.
- Patchworks uses substantial memory and CPU resources to track patch constraints and to develop road access networks. You can speed up convergence by removing unnecessary patch and road modeling accounts. (You will need to restart the model to make these changes take effect.)
C.5. What minimum RAM and processing speed would you recommend for our large coverages to run best?
The single most demanding requirement of Patchworks is RAM. For large problems we use a 64-bit operating system (Windows 10 Pro 64-bit) and up to 32Gb of ram. Note that on a 32-bit operating system the Java environment cannot make use of more than 1.5Gb of ram.
However, your memory requirements will depend on your planning problem. Many planning problems that we have looked at fit in under 1Gb. What makes the problem size grow is
- lots of complicated succession rules and silvicultural treatments
- lots of habitat, seral stage, cover type etc attribute curves
- road network modelling
- patch size modelling
- a large number of polygons
If you plan on doing all of the above then 2Gb should be considered your lower limit.
The Patchworks algorithms run on multiple threads of execution, and will make use of multiple cores if available.
C.6. The ProximalTopology tool quit after lengthly processing. What's up?
The program probably ran out of memory. You will need to provide it with at least 200Mb of Virtual Memory, and possibly more depending on the dataset size and raster resolution.
Patchworks maintains a file named "patchworks.ini" in your default home directory (usually under c:\Documents and Settings\your_name\pathworks.ini), which contains settings that are remembered from one run to the next. Many of the lines in the file are the individual settings for the wizards that start the Patchworks programs.
The line having the keyword 'patchworks.javaflags' specifies additional java command lines arguments that are to be used for every command started from the Application Launcher. You can add or edit this line to include additional java arguments, such as
patchworks.javaflags=-Dsun.java2d.d3d\=false
D. Technical Support
D.1.
What kinds of problems will technical support help with?
D.2.
What kinds of problems are not eligible for technical
support?
D.3.
How should I report a problem to technical support?
D.1. What kinds of problems will technical support help with?
Technical support is available to help you with questions on how to operate the software. Technical support covers questions in the following areas:
- Where to find the information in the documentation.
- Clarification of documentation, or explanation of features where the documentation is inadequate.
- Resolution and correction of errors in the software.
D.2. What kinds of problems are not eligible for technical support?
Analysis of forest sustainability is a complicated subject, and technical support cannot help with all of your issues in this area. In general, technical support does not cover the development of input datasets (other than to explain their form and function), formulation of a problem (other than to explain the general capabilities of the Patchworks model to represent problems), or the interpretation of results.
We offer additional consulting services to assist with problem formulation, dataset development and customization of our software. Contact our office for details.
D.3. How should I report a problem to technical support?
Support will be provided during SPS's regular office hours (8:30 A.M. to 5:00 P.M. Eastern Time) and may be available at other times. In the event that a SPS technical support technician is unavailable at the time of your call, a technician will return your call at the earliest possible opportunity.
We provide telephone support, but usually the best way to report a problem is by email (support@spatial.ca). When reporting a problem please have all relevant details available. In the case of an error message, this includes the full text of the error. Most errors occur as a result of a misconfigured initialization file. If this is the case, it is easiest for us to diagnose these errors if you email us a copy of your initialization file along with the text of the error message.
Otherwise, try to provide enough information so that we can reproduce your problem. Problems related to specific datasets may require that you send us a copy of your input datasets.
E. Modelling with Patchworks
E.1.
Is Patchworks a simulation model or an optimization model?
E.2.
How do I control the simulation?
E.3.
How do I know when the simulation is finished?
E.4.
How can I double-check my input datasets and the numbers
that show up in the accounts?
E.5.
How do I calculate the area
that is currently eligible for harvest?
E.6.
I have blocks that have already been designated for
harvest, how do I ensure that
Patchworks will always harvest
them?
E.7.
Where do the initialTargetSummary, initialTargetStatus CSV files come from?
E.8.
What is the purpose of the message.csv
file that is created by the Matrix
Builder?
E.9.
Can the groups that are used to create accounts also be used in the Timing Constraint
Editor?
E.10.
What is the difference between using the control.calculateGroups method
and loading a group file?
E.11.
Can I have multiple records for one polygon in the
groups.csv, or do I need to create
multiple group files?
E.12.
Does Patchworks perform 'cut
and then grow' or 'grow and cut' calculations? Is the
reporting done at the end of the period after all actions
have occurred?
E.13.
How can I manually apply a number of treatments?
E.14.
What if I change some of the attributes of my shapefile?
Do I just have to rebuild the input files?
E.15.
How can I set up area deferrals, such as marten core area
reserves or caribou habitat mosaics that change location
over time?
E.1. Is Patchworks a simulation model or an optimization model?
Patchworks is a simulation model. The model is a forecasting tool that combines a description of existing forest conditions with predictions of future development patterns. The model also contains a numerical solver that generates high quality solutions to combinatorial problems. You can use the solver to generate harvest patterns that best meet a variety of user specified objectives.
E.2. How do I control the simulation?
Most of the simulation environment is controlled by the content of the input datasets that describe initial conditions, development patterns, eligible treatments and responses. In many cases you will have to change values in the input dataset in order to change the modelling formulation.
The Patchworks model is a real-time, interactive simulation model. Once the software is started and initialized you can use it to explore forecasts of future conditions. The indicators within the model will always be in a consistent state, no matter what changes you make to the objective function parameters.
There are several techniques that you can use to control the simulation. The simplest and most precise is to manually assign the management treatments that you would like to apply, either using a batch file or interactively using the mouse. As treatments are selected all of the indicators will update automatically.
You can also use the scheduler to build management allocations automatically. The "Start" and "Pause" buttons are used to control the execution of the scheduler. When the scheduler is running it will attempt to form treatment allocations that best achieve the active management targets. To view and adjust the targets click on the target names in the "Targets" panel.
E.3. How do I know when the simulation is finished?
Unlike other simulation and optimization models, Patchworks does not run through a series of steps and terminate with an 'optimal' outcome. Patchworks can be used to explore a range of treatment options, and remains active until you are finished.
As the scheduler executes it searches the solution space testing various treatment timing configurations. The quality of the solution gradually improves as the various objective function values are satisfied. The scheduler does not come to a stopping point however, it instead continues to search for marginal improvements to the schedule and the objective function. Over time the value of the solution will converge towards the optimum value (for a given set of targets). You can monitor the progress of the scheduler using the "Performance meter". This meter displays red when the scheduler is actively improving the solution, turns yellow when the solution begins to converge, and green when the scheduler can find no better solution. In general, there will be very little further improvement to the objective function once the performance meter has stopped showing red.
If you change the target values after the solution has converged, the scheduler will immediately begin to seek the new optimum solution by changing the treatment schedule. Typically the performance meter will once again turn red as solution starts to change.
The red/yellow/green strip chart indicates the number of performance improving changes that the model is making at each time step. When the number of improvements dwindles (there are fewer improvements to be found) the colour turns green.
There is also a 'Performance table' that shows the current target value, change in target value, average target value, average change in target value for each target, as well as the 'penalty' values that are assessed for each account that is not meeting its objective. You can use this table to see what targets are in deficit and what is the bottle neck in the solution.
E.4. How can I double-check my input datasets and the numbers that show up in the accounts?
The Patchworks input datasets are in a fully normalized relational layout stored in CSV format. You can browse these files and relate them back to the original input files.
An easier approach would be to start up Patchworks, and browse through the values in the block table (available from the 'Edit' pull-down menu). This table contains polygon, attribute and account values for every polygon in the block dataset. Like most tables, the block table has a slider-bar on the right hand side that lets you move through time periods. All attribute and account values will update as you move the slider through time. All the relationships from the input matrix are reflected in this table, all correctly joined together.
Another approach is to use the Inspect Tracks tool to browse through the growth and yield and treatment options for each block.
E.5. How do I calculate the area that is currently eligible for harvest?
This information is available from the block table. Open the block table and select the Query Tool. Select all records where CANDIDATETREATMENTS ne ''. These records list the blocks that are eligible for some kind of management treatment in the currently displayed planning period.
This is a simple three step process:
- Set up an 'initialSchedule.csv' file that contains three columns: the block label, the treatment name, and the year from present when the treatment is to be applied. Populate this file with records that describe the initial harvest sequence.
- When you start the model you can use a console command or the 'Load a saved scenario' under the File menu to load your 'initialSchedule.csv' file. This will apply the treatments that you have defined and ensure that you are starting from the right spot.
- Also make these planned blocks unavailable to the model by using the Timing Constraints Editor. Set the proposed harvest blocks to MANAGED and UNAVAILABLE (yellow). If you set the block green, the model is free to redo the scheduling decisions you have made. If you use red, it will make the block unavailable to the model and it will erase the treatments you have previously planned. For more information see the User Guide documentation on timing constraints.
E.7. Where do the initialTargetSummary, initialTargetStatus CSV files come from?
The initialTargetSummary and initialTargetStatus CSV files can be created by saving and renaming the target summary and target status reports.
To export these reports, select File > Save a Scenario from the menu and highlight only targetStatus and targetSummary from the 'Scenario data files' folder. These reports get exported as targetSummary.csv and targetStatus.csv, so you will have to rename them to initialTargetSummary.csv and initialTargetStatus.csv.
For more information see the Patchworks data model documentation relating to the input files, their structure and how they are related.
E.8. What is the purpose of the message.csv file that is created by the Matrix Builder?
This file is generated during the Matrix building process. It lists the stratification variables that failed to find matches to feature, product, treatment, retention and succession conditions. Ideally, this file should not contain any records. Note that the occurrence of a failing match does not necessarily indicate a dataset error. For example, blocks that do not match to any treatments will cause error messages, and these blocks will be treated as unmanaged. This may be acceptable if the blocks are supposed to be unmanged. You may suppress this type of error by including a matching track element that does not contain any treatments.
E.9. Can the groups that are used to create accounts also be used in the Timing Constraint Editor?
Yes.
Groups that have been defined using the calculateGroups method or loaded from group files can be used in expressions that define the units column. Group names are contained in the GROUPS column of the block table, and can be queried with an expression such as
indexOf(GROUPS, 'groupa') >= 0
Both perform the same function, but the best practice is to use the control.calculateGroups method to define group associations. Group files may become out of date when you make updates to the block file. The control.calculateGroups method always uses the up to date values in the block file and maintains referential integrity.
You may place all of your group definitions into a single file, or you may divide the group definitions in to multiple files. The choice is a matter of organizational convenience.
Patchworks uses 'grow then cut', but all harvest calculations are performed on an annual basis so there is not much difference from a 'cut then grow' type of approach. Harvest activities are scheduled with annual resolution within the model. Product values (e.g. harvests volumes) are computed at the value of the curve for the year of treatment. For example, if a stand is 80 years old at the beginning of the simulation, and was harvested in year 1, the harvest volume would be computed at year 81 on the yield curve. Feature values are computed at the final year of the planning period.
E.13. How can I manually apply a number of treatments?
You may use the Treatment Editor solution to apply treatments on an individual block level (right click on the block, select edit treatments, right click in the line chart to select and apply a treatment). This approach may be out of the question for large areas and numbers of Blocks.
Another solution is to create a 'start-up' schedule.csv file and load the file prior to running the scenario. A schedule file must contain the Block number, year from present it is to be treated (delta) and the treatment type.
You will need to take care that the treatments in the schedule.csv file that you wish to load do not conflict with and already scheduled treatments. For instance, if the model has already been running and has scheduled a treatment for Block 1 in Year 1, then it would not be possible to apply a new treatment for Block 1 in year 1, because it would not be an eligible treatment in an already treated stand. In this case you will need to cancel the treatment before applying the new schedule. The usual best practice is to load a treatment schedule file at the start of the simulation prior to running the model.
A block availability file should also accompany this initial schedule file to make the scheduled Blocks unavailable to the model in all periods prior to and including the period you have scheduled a treatment. Without making these blocks unavailable, the model could either schedule another treatment at that time, or an earlier treatment that would make your treatment invalid. The block availability file could also be constructed in an outside application and loaded when 'Loading a previously saved scenario' in Patchworks.
If you change the stratification variables of a polygon then you will have to rebuild the growth and yield matrix. If you are changing a column that is only used for assigning timing constraints then you only need to restart the Patchworks program.
There is a good chapter on this in the User Guide: Timing Constraints. Each polygon can have a status of 'available' or 'unavailable' in any time period. The Timing Constraints editor is a convenience feature that lets you toggle the status of many polygons simultaneously.
First select a column in the block attribute file that represents your classification (e.g. MARTEN). The tool will scan the attribute table for unique codes, and present a matrix of codes by period. You can then toggle the colour code of the cells in the matrix to make up your scheduling constraints by zone and planning period. When you are happy with the set of constraints you click on the 'apply' button. The polygons will then be set to the status that you have chosen.
Once you have the correct classification, you can add lines to the PIN file or the ScenarioSet's to automatically apply these timing constraints when Patchworks starts or when scenarios are run.
F. Target Troubles
F.1.
If I want to set a minimum conifer growing stock target to
7,000,000m3, should I set his
to 7,000,000 per period or per year (periodic or annual)?
F.2.
Does the target table calculate an average of the growing
stock for the 5-years that's within the period?
F.3.
If my Patchworks model has variable planning period widths, do I
need to adjust my target weightings to reflect this?
F.4.
How do I deal with greenup constraints in Patchworks?
'Feature' targets are the sum of the feature on the landscape at the end of the planning period (unlike 'products' targets which are what you produced or extracted over the planning period). If you wanted to set up a feature target that specified a minimum retention level of 7,000,000 m3 of conifer growing stock, it would not matter what the width of your planning period was. The target would always be 7,000,000, since the measurement is done at the end of the planning period, regardless of period width. A planning period is the individual reporting period. You can define the number and width of the planning periods that you want to use at the top of the PIN file.
When using the target chart you must be aware at all times whether the charts are in 'annual' or 'periodic' view (there is an icon to toggle between the two views). Annual mode divides the periodic value by the number of years in the interval. If your target is reporting growing stock, then it will be showing the total m3 present at the end of the reporting interval. If you click the button to show this as an annual average (divide by the period width) you will get growing stock divided by the number of years in the period (typically an incorrect value).
However, if the target is showing harvest volumes (for example, product.Yield), then the amount will represent the total harvested in all years of the planning period. Dividing by the number of years in the interval will result in the average amount harvested in any year. This makes sense and is very useful especially when you have reporting intervals of differing widths.
The target table should show the values in the final year of the interval for features. For products it should show the sum of the values in all years in the interval.
No. The model will adjust internally to compensate for a variable period width.
F.4. How do I deal with greenup constraints in Patchworks?
Create a curve that describes the greenup condition. Then create the patching targets in the PIN file. The sample dataset has an example that uses the Seral.young category to describe patch membership. There is also documentation in the User Guide dealing with Block Topology: Defining and using patch targets.
G. Customizing Patchworks
G.1.
What is the syntax for the PIN file?
G.2.
Can I use Python (or Ruby or Groovy or JavaScript) instead
of BeanShell?
G.3.
Do you have any examples of scripts that I can use to see
how things work?
G.4.
How do I create a PIN file for my project?
G.5.
Can Patchwork be run in 'batch' mode to control the simulation?
G.6.
What is the recommended way to use batch scripts to run scenarios?
G.7.
What is the best way to create complicated reports?
G.8.
How do I make my reports show up in
Patchworks the next time it starts?
G.9. How can I modify the styling of the reports?
G.10. How can I add my logo so that it shows up on the reports?
G.11.
How do I make my custom map layers show up in
Patchworks the next time it starts?
G.12.
Can I change the appearance of the
Patchworks user interface?
G.13.
How can I export data from the block table to an external application?
G.14.
What's the significance of the 'feature.' and
'product.'terminology on the targets tab?
G.15.
How should I name my attributes and accounts?
G.16.
How do I set up groups and accounts to track conifer
harvest in certain locations?
G.1. What is the syntax for the PIN file?
The PIN file (Patchworks INput file) contains instructions that direct the start up and initialization of the Patchworks model. These instructions are in a language named BeanShell that is similar to Java. There are numerous books and online materials that describe the Java language syntax.
Documentation about differences between the BeanShell language and Java can be found at the BeanShell web site.
G.2. Can I use Python (or Ruby or Groovy or JavaScript) instead of BeanShell?
Yes. There are a number of different shell languages available and they are easy to install in Patchworks. All you need to do is
- Copy the interpreter JAR file in to the Patchworks library folder.
- Invoke the interpreter from the Patchworks console.
G.3. Do you have any examples of scripts that I can use to see how things work?
Yes. The Patchworks Script Library contains a number of sample scripts. These are documented in the Patchworks Script Library section of the User Guide.
G.4. How do I create a PIN file for my project?
The easiest way to get started is to use the Pin Builder application. This program will quickly lead you through the steps to build a simple or complex PIN file.
G.5. Can Patchwork be run in 'batch' mode to control the simulation?
Batch scripts can be written in the BeanShell language and executed in Patchworks. The easiest way to execute BeanShell batch scripts is to type your code into a file, and then invoke the script from the Patchworks console. For example, the following code starts the scheduler, allows it to run for 1,000,000 iterations:
Batch execution
control.resume();
control.waitForIterations(1000000);
control.suspend();
reportWriter.saveStage("Trial1");
1. The control.resume() method causes the scheduler to unblock and continue execution.
2. The control.waitForIterations() method causes the current thread to wait for the specified number of iterations to be executed. After this has occurred the current thread will continue executing commands from the PIN file.
3. The control.suspend() method pauses the scheduler.
4. The reportWriter.saveStage() method will invoke the report writer to save all defined reports to the directory named Trial1.
G.6. What is the recommended way to use batch scripts to run scenarios?
The previous example showed a simple mechanism to automate scenarios. Patchworks has a more comprehensive mechanism for recording scenario parameters, automating execution, controlling stopping criteria, and recording results and meta-data. ScenarioSet's are self-documenting and provide a convenient way to set up complex, repeatable analysis. See the User Guide for more details.
G.7. What is the best way to create complicated reports?
The Add Report wizard simplifies the job of defining Complicated reports. To create a report you need to define the source of the data (usually the Block Table), and the format that you would like to see the data presented in. Choose a report template from the Add Report wizard list (see the User Guide for options), and then follow through the wizard to often fill in the required parameters.
The finished report will show up automatically in the Report tab.
G.8. How do I make my reports show up in Patchworks the next time it starts?
When you use the Add Report wizard it will add reports to the Reports tab. Once you quit out of Patchworks these reports will disappear. To have them available the next time you start Patchworks you need to copy the report constructors to the PIN file. Do this by right-clicking on the report name in the Report tab, and choosing the Show Contstructor option. Copy the resulting code to the appropriate location in the PIN file.
G.9. How can I modify the styling of the reports?
You can modify the appearance of reports by using a custom CSS file. Create a CSS file containing your style changes. Then use a command like the following to let the ReportWriter know to include the CSS file:
reportWriter.addSupportFile("my_custom.css", true);For
example, the following CSS file will set the default font to be Calibri (or
the default serif is Calibri is not
available):body {
font-family: Calibri, serif;
}
When you save a scenario the current contents of the custom CSS file will be copied in to the html folder of the scenario folder. Any subsequent changes to the original custom CSS file will not be reflected in the saved scenario.
G.10. How can I add my logo so that it shows up on the reports?
You can use the custom CSS file to add your logo to the reports. First you will need to tell the Report Writer to include your logo file so that it will get saved out in to the scenario folder. Add code similar to the following in to the Patchworks_Init section of your PIN file:
reportWriter.addSupportFile("C:/logos/mylogo.png", false);
In the above we add a support file to the Report Writer, and it will be placed it into the 'html' folder of the scenario. This support file can be accessed from the internal web server and will be saved out to the scenario, but it will not show up in the index or the report tree.
Next, prepare a custom CSS file as described in the previous question. Customize a style class that goes with on of the sections in the report. In this example we will add the logo to the main content section of the report, up against the right margin. Note that you will need to set the height attribute so that there is at least enough space to fit in the logo, and adjust the position so that the logo does not go off the edge of the screen:
.mainContent {
background: url("logo.png") no-repeat right;
background-position: calc(100% - 30px) 40px;
min-height: 64px; /* Enough space to that the logo fits */
background-position: fixed; /* logo does not scroll with the page */
}
In this example we copied the logo file in to the same ReportWriter folder as the previous CSS file, so we do not need to specify any additional file path information for the CSS file to find the logo.
G.11. How do I make my custom map layers show up in Patchworks the next time it starts?
Right-click on a custom map layer and choose the Show Contstructor option. Copy the resulting code to the appropriate location in the PIN file.
G.12. Can I change the appearance of the Patchworks user interface?
Yes, there are several ways to do this. You can add menu items that invoke your own custom commands by calling the gui.addMenuItem method from the Patchworks console or from within a script. See the Patchworks Script Library documentation for more information.
A more adventurous approach would be to install a completely different user interface. The code for the default interface is loaded from a file named startup.bsh that is located in the script library. The PIN file usually calls the classicGUI() method in this file to set up the GUI, but you can replace this call with one of your own. It is also possible to run Patchworks without a GUI, for example when run within a larger simulation ensemble.
G.13. How can I export data from the block table to an external application?
The 'point and click' procedure to extract this information would be
- Open the table viewer for the Block table and adjust the properties to show only the necessary columns of interest.
- Use the Query Tool to select the appropriate records.
- Slide the slider bar to the first period of interest and export as a csv file.
- Repeat for the necessary time periods and then open the files you generated in Access to make a 'pivot table report'.
If this is a procedure you anticipate using regularly, you might want to create an automated script to do the same work. Paste the snip of code similar to the following into a file and Open the 'Patchworks Console' to run the script using a command like: source("myfile.bsh");.
/*
* Select stand eligible for harvest in each of the
* first 10 planning periods. The data for each
* period is written to a unique file.
*/
for (int i=1; i<=10; i++) {
blockData.setPeriod(i);
blockData.select(null, "CURRENTTREAMENT ne ''");
blockData.exportCSV("harvest_"+i+".csv");
}
If you would like to capture this information with each scenario that you save, consider using a TableQuery report instead.
G.14. What's the significance of the 'feature.' and 'product.'terminology on the targets tab?
'features' and 'products' are the standard nomenclature used in Patchworks. We use the feature group to refer to extant features (growing stock, etc.) and the product group to refer to extractions (removals or costs of management actions).
The nomenclature for targets is entirely up to you. The Patchworks program will create an 'explorer'-style hierarchical classification based on your account names, so use your naming scheme to organize your targets into groups (each '.' will be a new branch of the hierarchy).
You can change these names to whatever you want, there is nothing 'hardcoded' about it. Just modify the appropriate lines to the 'accounts.csv' file or PIN file.
G.15. How should I name my attributes and accounts?
Patchworks supports a hierarchical nomenclature for account and attribute names, but you can use whatever names you want. Attribute and account names can have a number of parts, each part is separated by a '.' character. Our common convention is that the first part of the name indicates if the value represents an extant feature (e.g. growing stock ='feature') or an extraction (e.g. harvested volume ='product').
The remainder of the hierarchy is simply pigeon-holing. For example, we would name douglas fir growing stock something like: 'feature.Yield.DF', and douglas fir harvest volumes 'product.Yield.DF'. Product values might be 'product.Value' (possibly broken down into finer categories). Harvest costs might be 'product.Cost.harvest'. Silviculture costs might be product.Cost.silv, or might be broken down into finer categories reflecting treatment intensities or planting stock types. Cavity bearing properties might be feature.Habitat.cavity, since this is tracking an extant feature.
All of these values represent attributes that are tracked for each polygon. Several tools in Patchworks make use of the hierarchical name structure to sort and display attributes using an explorer style of tree-view control. Our report writer is also geared to summing up categories that fall under part of a hierarchy (e.g. sum up all cost categories). Many of the reportWriter reports can have a column or target prefix specified which will eliminate the redundant prefix and use the unique ends as row or column headings.
G.16. How do I set up groups and accounts to track conifer harvest in certain locations?
Add a column to the block dataset that identifies polygons by locations of interest, and then create a group according to the unique values in this field. For example, if the column that contains the group names is COMPART, then add a line to the Target Initialization section of the PIN file that looks like:
control.calculateGroups("COMPART");
The next step is to add accounts for the required groups. For example:
control.addAccount("Comp1", "product.Yield.managed.conifer", "Comp1.Yield.managed.conifer");
control.addAccount("Comp2", "product.Yield.managed.conifer", "Comp2.Yield.managed.conifer");
control.addAccount("Comp3", "product.Yield.managed.conifer", "Comp3.Yield.managed.conifer");
These lines state that conifer yield from the Comp1, Comp2 and Comp3 groups should be added into new accounts named Comp1.Yield.managed.conifer etc. Now that you have groups for each compartment other attributes can be summarized, such as area and treatments.
H. XML Questions
H.1.
What's the difference between the 'feature curves' and
'product curves' sections in the XML file? Why repeat them?
H.2.
How does Patchworks know to set the age of stands to 0
after clearcut?
H.3.
How does Patchworks determine
'managed' and 'unmanaged' areas?
H.4.
The Matrix Builder is listing lots of errors for no
treatment options, but the polygons are not part of the
timber harvesting land base. How can I suppress these messages?
H.5.
How do I eliminate blocks from the analysis?
H.6.
What does an 'Illegal character or entity reference
syntax' error message mean?
'Feature curves' represent the growing stock in a stand, or the habitat condition, or the seral stage, or the percent species composition, etc. 'Product curves' represent what will be extracted by a given treatment type. Extraction attributes might include things like harvest and renewal costs, crown dues, area by treatment type, volume by product type, or value ($) by product.
There is no requirement to harvest the entire amount of growing stock in a stand, so the product volume curves may be different than the feature curves. These curves can be specified for each treatment type, because each treatment might remove different amounts of volume, or have different cost characteristics. It is appropriate to represent costs as curves (rather than constants) because in many cases it is appropriate that they change in value with stand age (e.g. harvest costs are related to piece size and density, which are related to stand age).
If you know that the harvest curves are identical to the growing stock curves, you can enter the curves only once, and use an 'id reference' to reference the single curve from multiple locations.
H.2. How does Patchworks know to set the age of stands to 0 after clearcut?
You can specify the age after a treatment on the treatment record. For example, you can add an 'offset="-5"' parameter to add a 5-year regen delay to a given treatment type. The default offset is '0'.
H.3. How does Patchworks determine 'managed' and 'unmanaged' areas?
The Matrix Builder divides areas into managed and unmanaged according to the XML recipe. Blocks with no eligible treatments are classified as 'unmanaged'. It is also possible to apply aspatial reductions to managed stands using <retention> tags.
See the ForestModel XML reference section for more details.
We often add a <track> statement similar to the one below as the last rule in our XML recipe. In this example the 'statement' in the <select> tag catches every block that is of type 'NTHLB' (meaning not part of the timber harvesting land base). The code has an enclosing <track> specification, but no treatments. This section will prevent the warning message for records that match to it, but since there are no treatments available any stands that match up (i.e. did not get caught by a preceding track) will get classified as unmanaged.
<!--
Everything else is unmangaged
-->
<select statement="type='NTHLB'">
<track>
</track>
</select>
H.5. How do I eliminate blocks from the analysis?
The XML <input> tag has a clause that can be used to filter out records.
<!-- Exclude blocks that are outside the analysis --> <input exclude="not (COMPT_NUM = '1' or COMP_NUM = '2')"/>
This example would exclude any polygon that did not have a compartment number of '1' or '2'.
H.6. What does an 'Illegal character or entity reference syntax' error message mean?
An error message such as this would result if you tried to use an inappropriate XML character, such as
<define field="2&3" constant="'3,2'" />
The model would complain that '&' is a very special reserved XML character. In general, field names are restricted to simple alpha numerics (_, 0-9, a-z, A-Z), and must not start with a number. In this particular case '&' is an entity reference in XML syntax. To correct the error you must change the '&' character to something else (e.g. '2_and_3') in all places in either the original input or the XML recipe.
I. Matrix Builder Questions
Many of the errors you discover in this phase of the data preparation may lead you all the way back to your original inventory, the SFMM/WDSTK models or just the XML file. If build errors appear in the left hand window it is important to find where the mis-match occurred: either the inventory doesn’t match the ForestModel or the ForestModel doesn't match the inventory! Remember the XML file is most often derived from the SFMM or Woodstock models, so an incomplete model can lead to an incomplete XML file.
The Matrix Builder provides detailed error messages to help you track down the source of the mis-match. The errors are organized into build categories: features, succession, tracks and products. Within each folder is a list of Block labels representing the blocks that did not match any of the attributes provided in that particular section of the Forest Model.
When you choose a block from the list, stratification information will appear in the window on the right. This information will help you identify the original status of the fragments and which section of the XML file did not provide any attribute information for those stands.
As was mentioned earlier, causes of these errors could be caused by missing information in the XML file, incorrect conversion from the aspatial models, incorrect classification schemes in the original inventory, etc. You really have to just dive in and check it out!
Common blunders learned from experience!
- Misspelt field names in XML file
- Different upper and lower cases between database fields and variables
- Missing values in important inventory fields
- Miscoded records in the inventory
- Missing attribute curve information in the SFMM/Woodstock models
- Multiple path natural and post treatment succession rules
J. Woodstock Conversion Questions
J.1.
I don't see my "Woodstock Aggregates" or their groups in
the Timing Constraints Editor pick list. Should I? How?
J.2.
What happens to the DEATH action from Woodstock?
J.3.
And how does Patchworks keep track of the age of stands?
Is everything related to the start of the planning
horizon?
J.4.
How does Patchworks handle the
Woodstock _AGE qualifier?
J.5.
Does the Woodstock conversion routine understand _CP in
the reference to operabilty?
J.6.
How do the Woodstock variable names relate to the Patchworks
attribute names?
The Timing Constraints editor uses columns that are in the block shape file. You must make sure that the theme information is available in the block file.
Aggregates are not transfer automatically from Woodstock, but you can easily use the Timing Constraints editor to define 'Zones' that group similar units.
J.2. What happens to the DEATH action from Woodstock?
Patchworks will convert the LIFESPAN and DEATH features from Woodstock into <succession> elements. The growth and yield matrix will contain yield curves that descend and start over again after the death age. Also, the seral stage curves start over again with the younger classes after the death age. Try using 'Display growth and yield' or 'View and edit treatments' by selecting the block layer in the map legend, and then right-clicking on a polygon in the map viewer window.
Until a management action occurs the 'age' of a stand is relative to the initial age at the start of the simulation. We do not have passive _DEATH_ events that move stands from one age to another. Instead, the late successional phase is represented by curves that decline in value and then ascend later at an appropriate time. Treatments are allowed to occur multiple times, and may have responses that branch to different post-treatment conditions.
This is different from Woodstock, but we feel that it provides more flexibility to describe successional processes. For example, coarse woody debris and late seral stage habitat features will probably persist after the overstory has broken up. It also makes it easier to represent these transitions with smooth curves rather than with discrete sudden jumps.
Once a stand is treated with a management action then the 'offset age' is set to a new value (usually '0' for a clearcut, but maybe something else for regen delays or mid-rotation treatments). A good way to track stand 'oldness' is using seral stages. These curves will ascend and descend correctly even after death events (assuming that you have set them up correctly!). Summaries and maps of area by seral stage are easy to generate. You could expand upon this by refining the seral stages to represent age classes.
J.4. How does Patchworks handle the Woodstock _AGE qualifier?
Patchworks will use the value of the _AGE parameter to set the new offset after a treatment has been applied. The way this is set also depends on the value of the even age flag on the ACTION statement. Here is a general summary of the rules as we see it from Woodstock users! (this assumes a period width of 5 years). We have recently updated the XML converter to correspond with these rules.
Clearcut responses
| 'Y' specified on ACTION statement | ||||
|---|---|---|---|---|
| _AGE specified on TARGET statement | Age Set To | Age (at end of 5yr period) | ||
| none specified | harvest | 0 | THEN GROW | 5 |
| _AGE 0 | 0 | 5 | ||
| _AGE 1 | 1 | 10 | ||
| _AGE 2 | 10 | 15 |
Partial harvest responses
| 'N' specified on ACTION statement | ||||
|---|---|---|---|---|
| _AGE specified on TARGET statement | Age Set To | Age (at end of 5yr period) | ||
| none specified | harvest | no change | THEN GROW | age + 5 |
| _AGE 0 | 0 | 5 | ||
| _AGE 1 | 5 | 10 | ||
| _AGE 2 | 10 | 15 |
J.5. Does the Woodstock conversion routine understand _CP in the reference to operabilty?
No. The Woodstock to XML conversion tool ignores the _CP stuff due to the way we formulate our matrix. We have no way to restrict treatments by period as an input, although you can set targets to control the maximum level of application of any treatment in any period.
J.6. How do the Woodstock variable names relate to the Patchworks attribute names?
Patchworks works best with hierarchically organized attribute and account names. Woodstock uses a simple naming scheme for attributes, and does not work well with the long Patchworks names. The Woodstock to XML conversion program presents a menu that suggests hierarchical names for each input variable.
The Patchworks variable names have a couple of special symbols (%f and %m). These will be replaced by the matrix builder as follows:
- If the attribute is being used in a feature context to represent extant features then replace %f with 'feature',
- If the attribute is being used in an harvest context to represent values being generated as consequence of a management action then replace %f with 'product',
- If the attribute applies to an area that is eligible for management treatments then replace the %m with 'managed',
- If the attribute is being applied to an area that will never be eligible for management actions then replace the '%m' with 'unmanaged'.
See ForestModel XML Reference for complete syntax.