OSM
Version History
Fixed major snag bug
· Snag compression was causing a new internal snag list to be initialized with a broken link to the main snag read-only public list. This was causing snags to be lost when snag compression ran, which occurs when snag records exceed 100. This has been corrected.
· Fixed height model error for dead standing snag height prediction. BAL for snags in cycle 0 was not calculated before the height prediction occurred, so max species height was returned. Also added error trapping code to prevent future issues like this.
Fixed issue with user-command code interpretation that was causing a simulation to be run twice. This bug was introduced in an earlier non-release build.
Newfoundland
& Labrador Variant
· Updated volume model (HonerVolume_N_X_242_122.cs)
o Fatal error fixed for tree volume model when an unknown species was present in the tree list.
o If the species is not recognized in the NL variant, birch volume models are used.
· Added a trap in the height model predictions to detect null predictions and throw an exception if encountered.
New Features
Improved database reading support
· Added SQLite database connection support for loading stand tree lists. See INPUTS.
· Introduced Ole database connection as the default over ODBC when connecting to Access databases.
· Added code to automatically insert a table index on SurveyID in the OSM_TreeList table to considerably speedup reading data into OSM. This has always been recommended to do manually, but often not done by users. OSM now manages this index.
Added X and Y properties to OSM stand class (Stand.cs)
· X and Y represent longitude and latitude coordinates. No coordinate system is implied - any can be used - depends on Variant. WGS 1984 should be used whenever possible, but not required.
· Updated stand input table documentation.
Added Treelist reporting capabilities (TextReport_TreeList.cs)
· Added SurveyAge, SurveyYear, Plots, and Stockable base properties as tree list reporting options. These properties can be set via the OSM_StandList table and can now be carried through into OSM outputs.
· Added support for reporting Variant-defined stand properties into the OSM tree list report. Any properties defined by Variants that are tagged by the Variant developer as ‘data bindable’ (e.g., BGI) can now be reported by setting OUTPUTS.TreeList.SetVariantStandColumns.
· With these changes, all properties that can be loaded to OSM before simulation can now be output to this tree list report.
Source Code and Application Management
· Implemented Git Versioning in GitHub Repository.
o Added AppSettings class to programmatically retrieve the Git version properties.
· Added a release build for 64-bit.
· Added solution publish profiles to streamline release builds. Four different release versions will now be built on each release:
o Framework-dependent (.Net 6.0 required on local machine)
§ 32-bit
§ 64-bit
o Self-contained (.Net not needed, larger application file package)
§ 32-bit
§ 64-bit
· Moved all test projects (variants, common models, webAPI) into a new common test project called OSM.Tests. Added folder namespaces for each project for test to reside under and updated namespaces in each test file. Deleted old test projects.
· Removed OSM.Acadian.dll as it has been replaced by OSM.ConsoleApp.dll
· Added GitHub operating system compile tests for Linux (ubuntu-latest). OSM should be able to be compiled and run on Linux now; however, this has not been tested outside of GitHub.
· Updated WebAPI BindablePropertiesInfoTest to avoid requirement of no change in the count of bindable stand properties.
· Updated INPUTS documentation throughout.
·
Renamed
OSM dynamic linkable libraries (DLLs) names and namespaces to be more
understandable to new API users and developers.
o OSM.Core.dll ŕ OSM.Management.dll
o OSM.Model.dll ŕ OSM.CommonModels.dll
o OSM.Model.Acadian.dll ŕ OSM.AcadianModels.dll
·
Upgraded
all code libraries from using the Microsoft .Net Framework 4 to .Net Standard
6.0
o
Improved
speed for many operations.
o
OSM
code simplified with many new C# language features.
o
Updated
coding environment to Visual Studio 2022, Community Edition.
·
Moved
all OSM source code to GitHub under a GitHub organization called ‘OSM
Collaborators’ administered by Chris Hennigar.
o
The
OSM API repository is currently set to private, but source code is public, so
if you wish to contribute code or simply see the code, you can contact Chris
Hennigar and request an invitation to the OSM Collaborators GitHub group. You
will need to provide your GitHub username and a description of who you are and
why you want to access the code. This group is intentionally set to private for
1) fear of exponential increases in OSM branches and source code management
that may be difficult for part-time OSM developers to keep up with, 2) to
lessen the threat of hackers or spammers modifying the code, and 3) to ensure
some discussion takes place before a new developer starts to modify code that
others depend on.
o
Source
code was licensed under the GNU Lesser General Public License (L-GPL, version
3)
o
All
source code files were updated to include license terms as well as author,
copyright, and change logs.
o
There
are currently multiple branches of OSM code under development. While the model
can be downloaded via GitHub for use, if you are not developing the main API,
extensions, or Variants, and instead simply want to run OSM simulations, then
it is recommended to use the latest version posted on the FORUS Research
website, which also includes updated documentation for the version posted.
·
Added
a Web API, allowing OSM to be called via a Web Server
o
This
was developed by Mathieu Fortin and Jean-Francois Lavoie at the Canadian Wood Fibre Centre, Canadian Forest Service in in 2022-2023.
o
This
Web API is called from a new DLL: OSM.WebAPI.dll, with API unit tests
located in: OSM.WebAPITests.dll
o
There
is currently no HTML documentation for this API, however the source code
contains comments on all API public members.
o
As
of 2024, the WebAPI is limited to simple inputs (OSM
input tables) and predefined outputs.
o
Contact
Mathieu Fortin for more information and latest updates.
o
This
WebAPI is not included in the FORUS Research OSM
download package. It is only available from GitHub.
· A new stand-alone OSM Variant for Newfoundland and Labrador (OSM-NL) has been developed over the course of 2023/2024 in collaboration with the NL government and FORUS Research, including: OSM source code with tree diameter growth increment, height, volume, and mortality models specific to NL forests.
o The model currently is considered BETA and should only be used for testing.
o This Variant was adapted from the Acadian Variant originally. Though it is a stand-alone Variant, many tree models and species still rely on the Acadian Variant predictions, due to lack of data to fit NL specific models (e.g., few observations of red pine in NL) or lack of time to fit all models (e.g., ingrowth), to date.
o Help documentation for the Variant can be found here.
· Added a new Windows executable (OSM.ConsoleApp.exe) as the new default executable for OSM.
o This was done to support multiple OSM Variants, allowing users to select the Variant they want to use on application startup.
o The OSM.Acadian.exe Windows executable program has been depreciated but is still present in the project for backwards compatibility. OSM.Acadian.exe will eventually be deleted from the project, so developers and users are encouraged to switch to OSM.ConsoleApp.exe ASAP.
o Two arguments are required to be passed to OSM.ConsoleApp.exe: 1) Variant code name, 2) OSM command file path. See OSM.Execute help file.
· Updated and reorganized HTML help documentation throughout to reflect changes above.
· Added ability to append a ‘Cut’ List in the standard OSM Tree List projection report. This feature is useful for simplifying reporting both pre-cut and cut tree records in the same simulation cycle, to see more easily what was cut during harvest entries. This feature is also useful for developing Woodstock Regimes, as the output format when summarised at the stand-level matches closely with the ‘pre-cut’ and ‘cut’ Regime row format used by Woodstock.
· Added Command property Units to the Species Command group so tree stump and top size can be specified in either Metric or USA unit systems.
· Moved some tree species surrogate assignment methods used by the Acadian Variant into the main OSM API under the TreeSpecies class so other Variants can leverage them.
· Updated the OSM.CommonModels.Calibration.MatrixModel class to make it accommodate Variant-defined predictor variables, like regional-dependent management type and site index variables. This class is useful for looking up, interpolating, or extrapolating tree predictions from a large lookup table of pre-defined predictors and responses (tree predictions) populated by complex machine learning models, AI, or user-defined estimates that are difficult to represent as a succinct equation. See source code documentation for more details.
· Added Ingrowth model ‘commandable’ properties in the Newfoundland and Acadian Variant models to allow incrowth probability and abundance to be modified using a multiplier. Two new commands are:
o
Simulation.Model.IngrowthModel.IngrowthProbabilityMultiplier [value >= 0]
o
Simulation.Model.IngrowthModel.IngrowthAbundanceMultiplier [value >= 0]
o Where a value of 1.5 would result in a 150% increase in probability or abundance of ingrowth, and 0.5 would reduce them by half.
Also see Acadian Variant Version History
· Managed stand calibration changes
· Spruce Budworm impact extension
· Diameter growth model, new command: LockAnnualPredictions
· Actions containing height amendments and harvest were causing conflicts with proper timing of harvest in the OSM.Core API. Resolved in this release.
· Lorey’s height (LHT) boosting is set to occur only if > 5 height samples are present; however, tree heights with weights of zero were being counted toward sample size. Now fixed.
· Trees having zero weight were being counted as height observations during height calibration. When weights are user defined in OSM_TreeList, any weights = 0 or null will now be ignored during local height calibration.
· Updated documentation for OSM.Simulation.Model.HeightModel and other minor edits on other help pages.
· The stand-level metric ATV was not being calculated correctly – now fixed.
· Updated documentation for OSM.Simulation.Model.HeightModel and other minor edits on other help pages.
· Fixed errors in calculation of relative density for operability and retention statements.
· Clarified documentation for use of relative density in operability and retention statements.
· Restricted use of Lorey’s height (LHT) prediction boosting in tree height imputation models when LHT < 4 m or > 20 m, or when DBH < 5 cm & > 50 cm. LHT adjustment can result in very odd height predictions in most of these extreme cases, under some circumstances. These extremes are also at the upper and lower end of data used to fit the model.
· OSM was not taking into consideration the possibility that tree records may have been agitated when calculating number of user height observations in the tree list. The effect of this was that height calibration would occur with as few as one height sample/species because the one height sample after agitation was expended to 5. This has been fixed.
· Added/updated documentation for OSM.Simulation.Model.HeightModel and other minor edits on other help pages.
· If tree agitation occurred height samples could be artificially increased, and this was influencing calculation of Lorey’s height during height imputation. This issue is now fixed.
· See addition of new command for partitioning tree records that represent a large number of trees/ha, including randomly ‘agitating’ DBH in those partitions. This partitioning and DBH agitation is recommended to be used for all OSM simulations, and has therefore been set to occur by default in this version. See Simulation.Model.TreeAgitation commands and default settings.
· Presentation of some recent validation work.
· Revised mortality model implementation to operate stochastically when trees/ha are < 0.5 in each tree record.
·
See
more details in Acadian
Variant version history.
·
Removed previous adjustments to DBH growth
models (introduced in version 1.0.3.2 as a result of
previous validation work) for clearcut, PCT, and planted stands.
·
See
more details in Acadian
Variant version history.
‘ToCut’ attribute added to tree input table
· ‘ToCut’ column added to tell OSM_TREELIST input table to tell OSM how many stems/ha from the current tree record should be immediately cut in the first simulation cycle; useful for simulating imminent marked-tree harvests, exerting fine control over harvest, or comparing predicted to observed stand development in plots that have been cut and measured for growth repeatedly post-harvest.
·
Finalized mortality and height models for NS,
NB, Maine, and PEI.
·
Adjustments to self-thinning line and ingrowth
for certain management types/species.
·
Addition of ‘PoorSite’
(true/false) attribute in OSM_StandList inputs (specific to Acadian variant) to
reduce growth and survival on sites with severe growth restrictions.
·
Removed depreciated ‘NbManagement’
attribute from stand list. Use ‘Management’ instead.
·
See
Acadian
Variant version history.
Acadian Variant
·
See
Acadian
Variant version changes.
·
Depreciated
some stand column metrics for reporting DBH and height of tallest or thickest X
trees in stand.
·
See
new features for reporting these same stand measures with more control of
number of trees used in average.
·
Enhanced
functionality for reporting average DBH and height of tallest or thickest trees
in the stand.
Genetic Gain Modifier
Commands
·
Added
objects and methods to the OSM API to allow variant model developers to track
snags (standing dead trees), including custom decay and snag fall models.
Fixed issue
with failing to load OSM on French language computers
·
Added
objects and methods to the OSM API to allow variant model developers to track
snags (standing dead trees), including custom decay and snag fall models.
Acadian Variant
·
See
Acadian Variant for new snag
modelling capabilities.
· Some minor tweaks to Acadian NB calibration to correct bias in regenerating stand conditions.
· When a stand fails to load for any reason, a warning is issued rather than a fatal error. This avoids one or two problem stands causing a batch of simulations to fail. Check to make sure all stands were simulated by joining output to input.
Acadian Variant
· See Acadian Variant version history for major changes to species, required input columns, and new calibration.
OSM
· Removed ability to use USDA plant genus-only codes as pre-defined species groups (PICEA = all spruce) in commands because this was creating conflict with Variant tree species that are defined only at the genus level (e.g., Acadian Variant has many tree species defined at the genus and species level; QURCUS, QURU, etc.).
· Default breast height property in the underlying OSM stand model class changed from 1.37m to 1.3m. This property can still be overridden by the Variant.
Actions
·
Operability
of an action can now be further constrained to stands having no previous
treatment using OPERABLE History.
Species
· Variant developers can now pre-define species groups (e.g., Acadian Variant species groups), and those group names can be referenced in OSM commands. This simplifies species group definitions in commands considerably.
· If a species submitted by the user is not defined by the Variant, OSM will attempt to find a close matched surrogate by first examining available Variant genus-level tree species, then individual species within the same genus, and if a match can still not be found, then the species is classed as either other softwood (_TE), other hardwood (_TB), or if non-commercial, then unknown (_TREE). If the species code is unrecognizable, an error will be thrown and stand loading will fail.
Inputs
· OSM_TreeList: added optional ‘Weight’ column, which can be used for manually weighting tree observations for local plot-level height calibration. This field is recognized during local height calibration, but not (currently) by the Calibrator.
Reports
· Added more stand variables (average height or average DBH of top 100 or top 50 trees) that can be written to the OUPUTS.TreeList report.
Calibration
· Height model – plot local calibration weighting
·
Log tree observations and
predictions to a text file for analysis
Actions
· Fixed a couple problems with the LOCK statement that were preventing activation of scheduled activities including Cut, Recruit, and Amend statements.
Species
· Species top diameter and stump height can now be modified for calculation of gross merchantable volume. See new SPECIES commands: TOP and STUMP.
· Latin Genus codes can now be used in any commands that reference species (e.g., Action constraints and amend commands, species groups and ranks) to reference all species in that genus (e.g., Acer).
· API: reorganized management of species groups into the main OSM species list. Added extensive methods for querying species by key, code, and/or groups. See API: TreeSpeciesList.Groups.
Actions
· An absolute or relative amount of a stand attribute (e.g., trees, basal area, volume) can now be scheduled for removal during harvest. This complements existing harvest rules that permit an absolute or relative amount of the stand attributes to be retained during harvest. See new subtract (-) operator in RETENTION command statements and example C.
· Actions can now enforce LOCKs onto other actions. See the LOCK command.
Tree Grade classification
prediction and transition support
· Added extensive functionality for modeling tree grade classification systems (e.g., form | quality class) in terms of both grade prediction & and grade transitions over time.
· Grade classification models can be declared:
o Internally by the Variant (via API) or
o Externally by a user-defined grade specification file.
· Loading grade models and enabling grade predictions in OSM can be controlled through commands or the API.
· See SIMULATION.MODEL.GradeModels for complete details.
· Tree ‘Form’ property name changed to ‘Grade’ to reflect a broader conceptual use of this property for tracking tree form, quality, or other local tree grade classification systems. This change affects the tree list input table column ‘Form’ and commands that use the keyword ‘Form’ (e.g., Actions). All instances of ‘Form’ must be changed to ‘Grade’.
· Some minor changes to the way Variant models are initialized by OSM in the API.
· The API now enables tree records to be programmatically ‘split’ during simulation; useful for modeling tree classification prediction and change such as decay class and grade class.
· Fixed error in tree list report (extra line with ‘r’ character) which was introduced in version 1.0.2.3.
· Fixed volume calculation error for maple species. Honer’s red oak coefficients were being used for maple species instead of maple coefficients.
· Other minor fixes including some documentation updates.
·
Default
file format for StandSummary report changed to a table-style CSV
format so it can be more readily used. Original format (COMPUTER) used in
previous versions can still be set using the following command: OUTPUTS.StandSummary.Format COMPUTER.
· StandSummary report was missing carriage return when written to file.
· Many other minor fixes including some documentation updates.
·
Changed
height model property ‘MinSpeciesObservations’ to MinObservations’
·
Changed
meaning of HT variable in AMEND commands.
·
Model
CALIBRATOR added to Core
OSM API framework
o
Provides
statistical methods for model validation and simple calibration of Variant
predictions against local observations using multiple linear regression.
o
Accessible
through commands or directly through OSM.Model.dll.
o
These
new calibration objects replace and clean up a number of
experimental validation methods and related reports in the Core OSM framework.
·
Added
a new command (BLEND) to the AMEND
statement group to allow blending of modified predictions with Variant
predictions over time.
·
Added
ability to modify height predictions through AMEND statements.
·
Added
ability to modify predictions with simple linear equations through AMEND
statements.
·
Relative
density (RD) can now be used at an OPERABLE
constraint.
·
Tree
BAL (basal area of thicker trees), FORM, and RISK property variables can now be
used in addition to DBH and HT (height) to select a subset of trees in
OPERABLE, AMEND, and CUT.RETENTION statements.
·
Minor
improvements to OSM command documentation throughout.
· Windows XP compatibility issues resolved (Microsoft .Net 4.0 required).
· Fixed issue with parsing complex relative file paths from OSM commands
· Fixed a few issues with parsing and compiling SQL statements used in INPUT.STANDLIST and INPUT.TREELIST
· Improved a number of error and warning messages
· Many other minor fixes.
·
None.
· Added Risk and Form attributes to trees:
o Ability to prioritize trees for harvest as a function of these new attributes through OSM commands.
· Substantial improvements to tree cut priority methods available when developing harvest prescriptions with OSM commands:
o More tree variables can now be used in cut priority logic.
o Ability to apply pseudo-spatial limitations on optimistic crop tree selection to make harvest simulations more operationally realistic.
· Cycles reported can now be filtered by adjusting the new StartYear and YearInterval properties in most OSM reports. These properties are accessible through OSM commands or the OSM API.
· Model self-thinning can now be turned off or A-line relative density limit adjusted from the API or through OSM commands.
· New interface (OSM.ICommandable) available in the OSM API that can be used by third party developers to inject custom OSM commands and methods into the OSM Runtime. Types implementing OSM.ICommandable can be designed to implement:
o Complex or regional harvest prescriptions
o Natural disturbances (e.g., spruce budworm)
o Modified ingrowth, DBH and Height increment, mortality predictions (e.g., climate change)
o Merchantable log product volume calculations
o Custom tree list loading and reporting
o Graphical user interfaces
New methods accessible from the OSM Runtime or OSM commands allow users to load OSM.ICommandable type from a third-party assembly (DLL).
·
Residual
(validation) report still being redesigned.
·
None.
· All stands can now be simulated at once by calling SIMULATE.
· Manual regeneration commands added.
o Regeneration can now be scheduled using RECRUIT commands.
o Bare ground simulations are now permitted.
· Added ability to locally CASHE inventory data to improve performance loading tree records for large data sets or from servers.
· DOS messaging can now be shut off to improve performance.
· Now possible to design single-tree selection method harvest by using the ‘J’ command in retention statements.
· Now possible to harvest trails (non-spatial) in partial cut prescriptions with command TRAILS.
· OSM commands can now be called through R.
· Added / updated documentation
·
Residual
(validation) report still being redesigned.
·
Revised
tree list report to make it customizable.
·
Removed
residual report. This report is currently being redesigned.
·
Revised
height model object structure to enable variant models to easily implement local
tree height calibration.
· Tree record IDs can now be loaded tracked.