Heureka Wiki - User contributions [en]

Treatment Program Generator Design

2010-05-24T07:33:48Z

Fkl: /* Creating Generation 2-n */

== Creating Treatment Programs for an analysis area ==

The class <tt>TreatmentProgramManager</tt> manages treatment program generation for an analysis area, as follows:

# <tt>ForestDomains</tt> are evaluated and each treatment unit is assigned to a domain.
# For each domain:
## Treatment units are set aside for nature conservation
## For treatment units that not has been set aside, the <tt>TreatmentProgramGenerator</tt> is called and treatment programs of the desired types (unmanaged, continuous management, or even aged management, given by the user) are generated
## For treatment units that has been set aside, unmanaged treatment programs are generated by the <tt>TreatmentProgramGenerator</tt>.

Treatment program generation requires is both performance and memory intensive. To get reasonable performance when reading from the database when treatment programs are generated, 20 treatment units are read at a time (or as many as there are left). Once treatment programs has been generated for a treatment unit, the memory allocated by that treatment unit is released (e.g. references are set to null allowing objects to be garbage collected).

== Creating Continous Management and Unmanaged Treatment Programs ==

Creating Continous Management and Unmanaged Treatment Programs is fairly trivial. Growth prognosis is done for the treatment unit until the planning horizon has been reached.

For continous management, it is evaluated in each period if selection felling is allowed or not. If allowed, selection felling is performed.

== Creating Even Aged Treatment Programs ==

Creating even aged treatment programs is more complex. A number of generations of the forest has to be created (a forest generation starts with regeneration and ends with final felling). An even aged treatment program must contain at least one complete generation, even if the planning horizon is shorter (net present value cannot be calculated if not a complete generation is present).

Even aged treatment programs are created based on treatment specifications (specifying when cleaning, first thinning, and final felling should be done) and fertilization policies (specifying if and how fertilization should be done). During the generation, a number of treatment specifications are evaluated, but the same fertilization policy is always applied for a given generation and control category. The latter also applies to regeneration.

Each forest domain contains one or more control categories. For each control category, it is specified if the control category is to be used in generation 1, generation 2 (and forward), or both. Treatment programs will be generated for each control category in the generation being in progress.

The diagram below illustrates the process for treatment program generation:

[[file:tpg.png]]

Each time regeneration is performed the treatment unit is grown until the regeneration has been activated on all prediction units (e.g. there are no waiting saplings).

Treatment specifications will be created each time a generation is to be completed. Then a treatment program is created for each treatment specification, up to and including a final felling treatment. Then a fertilization policy is applied if required (not shown in the figure).

Each treatment program is then checked, is the planning horizon reached and has at least one complete generation been created? If not a new generation is started. The figure above shows how new generations are simulated, there are also other (faster) possibilities to create new generations, described below.

=== Creating Treatment Specifications ===

A treatment specification contains a description on when cleaning, first thinning, and final felling can be done (cleaning and thinning can be omitted, final felling is always present in a treatment specification).

The purpose of treatment specifications is to generated all possible combinations of even aged management, based on user settings and of course the state of the treatment unit.

First it is determined when and if the treatments can be performed. For final felling lowest final felling age is calculated (according SVL, Skogsvårdslagen). For cleaning and thinning growth prognosis has to be made and in each period it is evaulated if the treatment is possible. Each treatment is then stored in a <tt>TreatmentSpecificationRange</tt>. It may look like this:

# Cleaning period 4-5
# Thinning period 8-10
# Final Felling period 10-14

Thereafter the ranges are sorted in reverse priority, so that the treatment with highest priority (which will be varied most) is last. If the priority order (set by the user) is thinning - final felling - cleaning then the list above will look like this after sorting:

# Cleaning period 4-5
# Final Felling period 10-14
# Thinning period 8-10

The last step is to, from the ranges, create a list of possible specifications. The class <tt>TreatmentSpecificationEnumerator</tt> creates an enumeration of all possible treatment specifications from the ranges and the class <tt>TreatmentSpecificationCollection</tt> filters the invalid permutations.

It might look like this:

{| border = "1"
|-
|Cleaning||Final Felling||Thinning||Comment
|-
|4||10||8||
|-
|4||10||9||
|-
|4||10||10||Filtered since cleaning and final felling not can occur in the same period
|-
|4||11||8||
|-
|4||11||9||
|-
|4||11||10||
|-
|5||10||8||
|-
|etc
|}

(From the table it is also obvious why the treatment with the highest priority is last, it is varied most.)

=== Creating Generation 2-n ===

First time a second generation is created it must be simulated, but as the treatment program generates more programs for a treatment unit, treatment specifications and results from a generation are reused whenever possible, to get better performance.

The treatment program generator tries to create as many alternatives as possible for generation 1 and 2. If more generations are needed, generation 2 is repeated, no new alternatives are created for generation 3-n.

When a generation is finished and if it is complete (from regeneration to final felling), the treatment specification for it is saved. The treatment specifications are saved per control category, and separeted for generations that started with trees from an earlier generation (seed trees or shelterwood). The specification are sorted, with highest net present value first.

Also, treatment programs are saved when they are complete.

So when a new generation is to be started, the following conditions are evaluated:

;LateGeneration: Is the generation before this generation complete? (Meaning is this generation 3 or later?)
;SameControlCat: Is the same control category used in the new generation as in the previous generation?
;SameStartState: Did the previous generation and this generation start with the same state regarding seed trees/shelterwood?
;SavedSpecs: Are there saved specifications for the control category to be used by the new generation, with the same state regarding seed trees/shelterwood?

The desired methods of creating a new generation are (fastest first, slowest last):

;CopyPreviousGeneration: Results are copied from the previous generation. No new simulation required. LateGeneration, SameControlCat, and SameStartState must be true
;RepeatPreviousGeneration: Specification from previous generation is used, new simulation is done. LateGeneration and SameControlCat must be true.
;CopyBestSaved: Several generations are created with result copied from saved treatment programs. No new simulation required. SameControlCat and SavedSpecs, and SameStartState must be true.
;RepeatBestSaved: Several generations are created from saved specifications. New simulations required. SameControlCat and SavedSpecs must be true.
;GenerateNew: Both new specifications and new simulation is done. Used when none of the methods above can be used.

A special case occurs when the treatment program generator is invoked from StandWise. In this case the copy methods above are not allowed. This is due to the fact the copied results not are stored in the treatment unit, and diagrams and tables in StandWise only shows results from the treatment unit.

A treatment program generation typically works like this:

# First alternative of generation 1 is simulated.
## First alternative of generation 2 is simulated, specification is saved (GenerateNew)
### Only alternative of generation 3 (CopyPreviousGeneration)
## Second alternative of generation 3 is simulated, specification is saved (GenerateNew)
### Only alternative of generation 3 (CopyPreviousGeneration)
## etc for generation 2-3
# Second alternative of generation 1 is simulated
## Alternatives 1-n for generation 2 are created by coping best alternatives 1-n from first alternative of generation 1 (CopyBestSaved)

The example above assumes that each generation either ends with retained trees, or that no generation ends with retained trees.

If more than one control category is used the scenario gets more complex. Say that two control categories are used, SeedTrees and NoSeedTrees. Generation will then be done like this:

{| border="1"
|-
|Generation 1||Generation 2||How is generation done?
|-
|SeedTrees||SeedTrees||As above
|-
|SeedTrees||NoSeedTrees||As above, but Repeat... instead of Copy...
|-
|NoSeedTrees||SeedTrees||As above, but Repeat... instead of Copy...
|-
|NoSeedTrees||NoSeedTrees||As above

|}

Treatment Program Generator Design

2010-05-21T13:54:49Z

Fkl: /* Creating Generation 2-n */

== Creating Treatment Programs for an analysis area ==

The class <tt>TreatmentProgramManager</tt> manages treatment program generation for an analysis area, as follows:

# <tt>ForestDomains</tt> are evaluated and each treatment unit is assigned to a domain.
# For each domain:
## Treatment units are set aside for nature conservation
## For treatment units that not has been set aside, the <tt>TreatmentProgramGenerator</tt> is called and treatment programs of the desired types (unmanaged, continuous management, or even aged management, given by the user) are generated
## For treatment units that has been set aside, unmanaged treatment programs are generated by the <tt>TreatmentProgramGenerator</tt>.

Treatment program generation requires is both performance and memory intensive. To get reasonable performance when reading from the database when treatment programs are generated, 20 treatment units are read at a time (or as many as there are left). Once treatment programs has been generated for a treatment unit, the memory allocated by that treatment unit is released (e.g. references are set to null allowing objects to be garbage collected).

== Creating Continous Management and Unmanaged Treatment Programs ==

Creating Continous Management and Unmanaged Treatment Programs is fairly trivial. Growth prognosis is done for the treatment unit until the planning horizon has been reached.

For continous management, it is evaluated in each period if selection felling is allowed or not. If allowed, selection felling is performed.

== Creating Even Aged Treatment Programs ==

Creating even aged treatment programs is more complex. A number of generations of the forest has to be created (a forest generation starts with regeneration and ends with final felling). An even aged treatment program must contain at least one complete generation, even if the planning horizon is shorter (net present value cannot be calculated if not a complete generation is present).

Even aged treatment programs are created based on treatment specifications (specifying when cleaning, first thinning, and final felling should be done) and fertilization policies (specifying if and how fertilization should be done). During the generation, a number of treatment specifications are evaluated, but the same fertilization policy is always applied for a given generation and control category. The latter also applies to regeneration.

Each forest domain contains one or more control categories. For each control category, it is specified if the control category is to be used in generation 1, generation 2 (and forward), or both. Treatment programs will be generated for each control category in the generation being in progress.

The diagram below illustrates the process for treatment program generation:

[[file:tpg.png]]

Each time regeneration is performed the treatment unit is grown until the regeneration has been activated on all prediction units (e.g. there are no waiting saplings).

Treatment specifications will be created each time a generation is to be completed. Then a treatment program is created for each treatment specification, up to and including a final felling treatment. Then a fertilization policy is applied if required (not shown in the figure).

Each treatment program is then checked, is the planning horizon reached and has at least one complete generation been created? If not a new generation is started. The figure above shows how new generations are simulated, there are also other (faster) possibilities to create new generations, described below.

=== Creating Treatment Specifications ===

A treatment specification contains a description on when cleaning, first thinning, and final felling can be done (cleaning and thinning can be omitted, final felling is always present in a treatment specification).

The purpose of treatment specifications is to generated all possible combinations of even aged management, based on user settings and of course the state of the treatment unit.

First it is determined when and if the treatments can be performed. For final felling lowest final felling age is calculated (according SVL, Skogsvårdslagen). For cleaning and thinning growth prognosis has to be made and in each period it is evaulated if the treatment is possible. Each treatment is then stored in a <tt>TreatmentSpecificationRange</tt>. It may look like this:

# Cleaning period 4-5
# Thinning period 8-10
# Final Felling period 10-14

Thereafter the ranges are sorted in reverse priority, so that the treatment with highest priority (which will be varied most) is last. If the priority order (set by the user) is thinning - final felling - cleaning then the list above will look like this after sorting:

# Cleaning period 4-5
# Final Felling period 10-14
# Thinning period 8-10

The last step is to, from the ranges, create a list of possible specifications. The class <tt>TreatmentSpecificationEnumerator</tt> creates an enumeration of all possible treatment specifications from the ranges and the class <tt>TreatmentSpecificationCollection</tt> filters the invalid permutations.

It might look like this:

{| border = "1"
|-
|Cleaning||Final Felling||Thinning||Comment
|-
|4||10||8||
|-
|4||10||9||
|-
|4||10||10||Filtered since cleaning and final felling not can occur in the same period
|-
|4||11||8||
|-
|4||11||9||
|-
|4||11||10||
|-
|5||10||8||
|-
|etc
|}

(From the table it is also obvious why the treatment with the highest priority is last, it is varied most.)

=== Creating Generation 2-n ===

First time a second generation is created it must be simulated, but as the treatment program generates more programs for a treatment unit, treatment specifications and results from a generation can be reused to get better performance.

When a generation is finished and if it is complete (from regeneration to final felling), the treatment specification for it is saved. The treatment specifications are saved per control category, and separeted for generations that started with trees from an earlier generation (seed trees or shelterwood). The specification are sorted, with highest net present value first.

Also, treatment programs are saved when they are complete.

So when a new generation is to be started, the following conditions are evaluated:

;LateGeneration: Is the generation before this generation complete? (Meaning is this generation 3 or later?)
;SameControlCat: Is the same control category used in the new generation as in the previous generation?
;SameStartState: Did the previous generation and this generation start with the same state regarding seed trees/shelterwood?
;SavedSpecs: Are there saved specifications for the control category to be used by the new generation, with the same state regarding seed trees/shelterwood?

The desired methods of creating a new generation are (fastest first, slowest last):

;CopyPreviousGeneration: Results are copied from the previous generation. No new simulation required. LateGeneration, SameControlCat, and SameStartState must be true
;RepeatPreviousGeneration: Specification from previous generation is used, new simulation is done. LateGeneration and SameControlCat must be true.
;CopyBestSaved: Several generations are created with result copied from saved treatment programs. No new simulation required. SameControlCat and SavedSpecs, and SameStartState must be true.
;RepeatBestSaved: Several generations are created from saved specifications. New simulations required. SameControlCat and SavedSpecs must be true.
;GenerateNew: Both new specifications and new simulation is done.

A special case occurs when the treatment program generator is invoked from StandWise. In this case the copy methods above are not allowed. This is due to the fact the copied results not are stored in the treatment unit, and diagrams and tables in StandWise only shows results from the treatment unit.

A treatment program generation typically works like this:

# First alternative of generation 1 is simulated.
## GenerateNew First alternative of generation 2 is simulated, specification is saved
### CopyPreviousGeneration

Treatment Program Generator Design

2010-05-21T13:32:09Z

Fkl: /* Creating Treatment Specifications */

Treatment Program Generator Design

2010-05-21T13:04:29Z

Fkl: /* Creating Even Aged Treatment Programs */

File:Tpg.png

2010-05-21T12:59:02Z

Fkl:

Treatment Program Generator Design

2010-05-21T12:44:33Z

Fkl: /* Creating Continous Management and Unmanaged Treatment Programs */

Treatment Program Generator Design

2010-05-21T12:41:59Z

Fkl: /* Creating Treatment Programs for an analysis area */

Treatment Program Generator Design

2010-05-21T12:34:54Z

Fkl:

Design of Treatment Models

2010-05-21T12:29:58Z

Fkl:

== Felling Treatments ==

Felling treatments, e.g. final felling, thinning, and selection felling are fairly simple once the intensity of the treatment has been determined per tree. All that has to be done is to adjust <tt>StemsResidual</tt> for each affected tree.

== Regeneration including soil preperation ==

The regeneration models are fairly complex, for more details about the models see [[Regeneration]].

Both the existing regeneration simulators (the <tt>ModelRegenerationSimulator</tt> and the <tt>DatabaseRegenerationSimulator</tt> produces a list of saplings that are to be activated in a future period. This is implemented as follows, per prediction unit:

# The saplings are added to the trees of the prediction unit, with the desired state of the sapling in the current period
# The activation period is determined
# The regeneration period is determined (this does not necessarily have to be the current period, depending on the fallow period, i.e. minimum number of years between final felling and regeneration)
# The expected state for each tree between from the regeneration period to (but not including) the activation period is calculated with interpolation
# The state of the current period for each tree is moved to the activation period
# The state of each period from period 0 to but not including the regeneration period is set (all values are 0 and all trees are invalid)
# Diameter and height growth for each period is set for each tree (as the state of each period is known growth can easily be calculated)

Calculation of growth

2010-05-21T12:05:17Z

Fkl: /* Growing for other period lengths */

== Introduction ==

Growth from one period to another period is done as follows (assuming 5-year periods)

# Make a growth prognosis based on the residual state (state after treatment, if any) of the treatment unit
# Calculate the state in the new period
# Assign height and volume to trees in the new period (based on the state before treatment in the new period)
# Make growth adjustments that are treatment related

== Make growth prognosis ==

Growth prognosis is done in the following steps, per prediction unit:

# Update tree values
## Determine Bal for each tree (basal area of all larger trees)
## Determine if each tree is an overstorey tree or not
## If any tree changed to/from overstorey, update aggregated values for the prediction unit (e.g. mean age, total volume, and mean diameter), since some of these values are per forest layer
# Assign diameter growth and mortality to trees
# Assign height growth and mortality to saplings
# Prognos ingrowth (only if stand is established)
# Adjust diameter growth due to stand growth model and thinning effect

== Calculate state in a new period ==

# Set the values for the new period:
## Update diameter (for trees) or height (for saplings), and stems (for both trees and saplings)
# If there are saplings but not waiting saplings, and mean height exceeds height limit for young stand, change saplings to trees:
## Change tree type of saplings with diameter < 4 cm to removed
## Change tree type of remaining saplings to trees
## Update aggregated values for each prediction unit where there was saplings
# If there are ingrown trees:
## Assign age, height, and growth to each ingrown tree
## Update aggregated values for each prediction unit where there was ingrown trees
# If aggregated values for any prediction unit has been changed, update aggregated values for the treatment unit
# Perform growth adjustment that is not treatment related

== Assigning height and volume ==

For each prediction unit:

# Height and volume is assigned to trees
# Volume is assigned to saplings
# If first period, dead trees is estimated
# Aggregated volume is updated

== Making growth adjustments ==

=== When are growth adjusters called and why? ===

Certain treatments and models may affect the forest state a long time after the treatment has occured or the model was activated. For instance, doing a final felling with seed trees also requires that the seed trees are removed after some time, extracting biofuel causes a growth reduction, intensive fertilization causes increased growth.

To solve this problem, it is possible to register a <tt>IGrowthAdjuster</tt> to a treatment unit.

Registered growth adjusters are called two times during growth prognosis:

;"BeforeTreatment": Just after the state in a new period has been calculated, but before height and volume has been calculated
;"AfterTreatment": After height and volume has been calculated

(The terms BeforeTreatment and AfterTreatment are not so descriptive, but will be explained more below.)

A <tt>IGrowthAdjuster</tt> must decide if it should be applied BeforeTreatment, or AfterTreatment.

BeforeTreatment is used if the adjustment is due to an expected growth change caused by the treatment. For instance, extraction of biofuel or intensive fertilization adjusts the growth and this will also affect volume, height, and the state before treatment for the new period. '''Growth adjusters that has BeforeTreatment set to true are those that affects the state ''before'' treatment for the new period'''

AfterTreatment is used if the adjustment is due to an extra treatment being automatically invoked in the new period. For instance, removal of overstorey trees. '''Growth adjusters that has BeforeTreatment set to false are those that affects the state after treatment for the new period'''

=== Implementing a growth adjuster ===

A growth adjuster typically stores a period or a period range internally to know when to do the adjustment. For example, the <tt>OverstoreyRemover</tt> class stores the removal period. When <tt>AdjustGrowth</tt> is called, it can then check if the current period is the removal period, and then remove the overstorey layer.

=== Implementation Remarks ===

Growth adjusters has proven to be powerful when implementing certain types of treatments, but also hard to understand. An alternative solution would be to define events on the <tt>TreatmentUnit</tt> class, and allow other classes register to those events. Suggested events are:

;GrowthCalculated:Occurs when growth prognosis has been made, but before a new period is entered. This allows classes like the <tt>BioFuelGrowthAdjuster</tt> to make further adjustments to the growth prognosis.
;NewPeriodEntered:Occurs when the state of a new period has been calculated, but before any other calculations (such as volume and height) in the new period. This allows classes like the <tt>IntensiveFertilizor</tt> to adjust variables like site index in the new period.
;GrowthComplete:Occurs when the growth calculcation is complete. This can be used by most existing growth adjusters, to perform additional treatments for instance.

== Growing for other period lengths ==

Growing for other period lengths than 5 years is done by first growing a normal 5-year period, and then interpolate the values to the desired length.

Calculation of growth

2010-05-21T12:04:15Z

Fkl: /* Making growth adjustments */

Calculation of growth

2010-05-21T11:24:58Z

Fkl: /* Assigning height and volume */

Calculation of growth

2010-05-21T11:17:45Z

Fkl: /* Introduction */

Calculation of growth

2010-05-21T11:17:00Z

Fkl: /* Calculate state in a new period */

Calculation of growth

2010-05-21T09:52:53Z

Fkl:

System Architecture

2010-05-21T09:29:02Z

Fkl: /* Forest model and Calculations */

== Architectural Goals and Quality ==

For Heureka, the two most important quality goals are modifiability and performance. The system should be flexible enough to allow maintenance and further development in a cost effective manner. At the same time performance should be good enough to allow simulation on large amounts of data. To a certain extent, these goals are contradictable.

In addition to this, testability is an important quality aspect. As many parts as possible should be possible to test automatically, e.g. with unit testing tools such as [http://www.nunit.org/ NUnit]. This sometimes means that sub functions must be made public so that they can be tested from external code. Over time, this goal has been proven more important than originally expected. This means that this goal has not always been met in the existing code, for instance many classes has a lot of dependencies on other classes making them harder to test.*

Other quality goals are less important:

* Security. There are no specific security requirements. The system will use security functions available in the database and operating system.
* Availability. The system is a single user application, so availability is not considered in the architecture.
* Portability. Portability is not required.

== Logical View ==

=== Forest model and Calculations ===
[[file:Forest_and_Calculations.png]]

The key entity in Heureka is the Treatment Unit, that represents a stand, i.e. an area restricted in space, with the same type of forest. A Treatment Unit is the smallest unit treatments are applied for. Each treatment unit contains one or more predictions units. A prediction unit represents a plot or a cell inside the treatment unit. Each prediction unit contains trees. Trees have [[Handling of tree states|different states]], identifying if the tree object represents a sapling, a tree, is dead and so forth. Each of these entities [[handle different time periods]].

Treatments are simulated in Heureka with different type of [[Design of Treatment Models|treatment models]] such as regeneration, fertilization, cleaning, thinning, and final felling.

Growth and yield models calculates tree related values such as volume, basal area growth, height, age, and bark thickness. With help of the growth models, a [[Calculation of growth|treatment unit can grow]], i.e. the state in a future time period can be calculated.

[[Result models]] are used to calculate different types on results. Based on the state of a treatment unit in a given time period, different types of results can be calculated, such as cost and revenue of treatments, amount of biomass in the living forest, or amount of litter added to the ground. A result model may also produce a result based on the results in other result models (e.g. the recreation model uses input from the dead wood model).

Simulation models or frameworks, allows treatment programs to be calculated for a treatment unit. A simulation model utilizes the growth and yield models, the treatment models, and sometimes also result models, to simulate different alternatives for managing a treatment unit. When growth prognosis and treatments has been simulated for a number of periods, the treatment unit (together with its prediction units and their trees and saplings) contains information about the forest state in all periods that were included in the simulation. The results can be saved in a treatment program, which contains results for all periods with the desired result models. Currently, three simulation models are implemented in Heureka: the (strategic) [[Treatment Program Generator Design|Treatment Program Generator]], the [[Tactical Treatment Program Generator Design|Tactical Treatment Program Generator]], and the [[Regional Framework Design|Regional Framework]].

An optimization model is used to create a plan. A plan consists of a selection of treatment programs (one for each treatment unit in the plan), that gives the best result according to the optimization model. An optimization model is defined using the results from the result models. Any variable produced by a result model can be used in an optimization model. Optimization models differs from other models in Heureka, these are the only models that are defined by the user (all other models are programmed into the system).

Treatment units may be classified in forest domains. A user may define a forest domain, based on variables from the result models. The forest domain is then used to configure a simulation model.

=== Data Import ===

[[file:Data_Import.png]]

A <tt>TreatmentUnit</tt> can be created from a NFI plot (Riksskogstaxeringen). In this case, a<tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each NFI plot (if the NFI plot is splitted a <tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each part of the plot).

Similarly FMPP data can be imported into Heureka (not shown in figure).

Another option is to import a stand register. From <tt>StandObject</tt>s in the stand register, <tt>TreatmentUnit</tt>s can be simulated. In this case, trees or saplings are created for the <tt>TreatmentUnit</tt>, based on stand level variables in the <tt>StandObject</tt>. The simulation process is stochastic, meaning that the result will be slightly different each time if repeated several times for the same <tt>StandObject</tt>.

It is also possible to get data to Heureka by making a sample design, choosing <tt>StandObject</tt>s to be inventoried, and then to make a field inventory using [[Ivent]], to get real plot data and inventoried trees and from that data create <tt>TreatmentUnit</tt>s.

The last option to get data into Heureka is to manually enter data using [[StandWise]] (not shown in figure).

All forest data is stored in a relational database.

=== Projects ===

[[file:Projects.png]]

A <tt>Project</tt> contains <tt>ControlCategories</tt> and <tt>ForestDomains</tt>. Each <tt>ForestDomain</tt> refers to a <tt>ControlCategory</tt>, and each <tt>ControlCategory</tt> contains a number of <tt>[[Design of Control Tables|ControlTables]]</tt>, each of which contains user settings for a model or a group of related models in the system.

Also, a <tt>Project</tt> contains the <tt>TreatmentUnits</tt> that the user is working with (the <tt>TreatmentUnits</tt> are actually kept in an <tt>AnalysisArea</tt>, not shown in the figure).

A <tt>Project</tt> may also contain other items, such as optimization models (not shown in the figure).

The project information is saved as files in the file system.

== Design Principles ==

=== Layering ===

[[file:layering.png]]

The system is built with a layered architecture (see for example [[ISBN 0321154959|Bass et al: Software Architecture in Practice]]. The layering is based on the system logic, where each layer adds functionality from a lower layer.

The three layers are:

;Application Layer: Each application is a separate subsystem. An application connects the domain specific subsystems into the functionality provided by the application.
;Domain Layer: A large number of subsystems with different types of domain specific functionality. Each subsystem has its own logic, and in many cases also presentation and persistence services. By having the presentation in the domain layer, UI functionality can be reused between applications.
;Base Layer: General purpose support functions.

The purpose of the layering is to achieve modifiability by isolation of changes. Changes in a higher layer does not affect a lower layer at all.

The layering is not strict, meaning that a higher layer can access any lower layer.

A similar layering is proposed in IBM Rational Unified Process, and in Domain Driven Design. The advantage of layering by generality as opposed to layering by type (as proposed by Microsoft) is lower coupling and higher cohesion.

Inside a subsystem, layering by type, i.e. UI -> Logic -> DB should be done (if a subsystem has a presentation and/or persistence service). A subsystem should be able to use the logic of another subsystem without refering to the presentation or persistence service of that subsystem. The persistence service should be encapsulated inside the subsystem and not be used directly by other subsystems. The presentation service of a subsystem should be available for composition of UI.

''Unfortunately the subsystem layering has not always been used, in many cases several subsystems access the same tables in the database directly. Some subsystems are also poorly layered, e.g. with database code inside the UI, or UI code inside the logic.''

=== MVC ===

Linking between user interface and the domain model is done with the architectural pattern Model-View-Controller (Reenskaug 1979).

The model is a domain entity. When the entity is changed, it signals that with an event so that all views rendering the entity can update themselves. The event <tt>PropertyChanged</tt> is used when a property is changed, the interface <tt>IBindingList</tt> is used when a list or collection is changed. In some cases other events are also used, in <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> there are a few more EventArgs that can be used. That namespace also contains the class <tt>ExtendedBindingList</tt> which is recommended for collections that can be bound.

The view is any kind of graphical control, such as a TextBox, a DataGrid, a TreeView, or a Map. The view can show and change some parts of the entity.

The controller is the object that reacts on user inputs, typically event handlers in a form.

When developing with MVC it is important not to short-circuit the view and the controller when they are implemented in the same class. The event handler should only update the model, and not trigger changes in the view directly.

=== Dependency inversion ===

To reduce dependencies between classes and subsystems, should the subsystems that need a particular service define an interface for that service. For example, the <tt>Forest</tt> subsystem needs biomass to be calculated. To avoid a direct (and circular) dependency from <tt>Forest</tt> to <tt>Biomass</tt>, the <tt>Forest</tt> subsystem declares an interface, <tt>IBiomassService</tt>, and the <tt>Biomass</tt> subsystem implements that interface.

With dependency inversation, a new problem arises, how does an object locate the needed services? There are two common approaches to solving this problem: either Dependency Injection is used, or a Service Locator is used. For Heureka, the latter approach has been used.

The subsystem <tt>Slu.Heureka.BaseLayer.Services</tt> implements a service locator. Key classes in interfaces in that subsystem are:

;IService:Interface that must be implemented by all services
;Service<T>:Generic class for accessing a service
;ServiceAttribute:Attribute that should be set on all services that should be auto loaded
;ServiceBase:Base class for implementing a service
;ServiceManager:The service locator

The <tt>ServiceManager</tt> is a Singleton. It supports auto loading of services (all services marked with the service attribute will be loaded at application startup) as well as explicit loading of services (very useful in unit tests).

The <tt>Services</tt> subsystem was introduced relatively late in the project but has proven to be very flexible and useful. In future development, it is recommended to use it more frequently to reduce dependencies in the system. The recommended approach is that when:

* A class needs to instantiate other classes (except .Net classes), a FactoryService should be implemented
* A class needs to use another subsystem, an interface to that subsystem should be implemented

Static classes and singletons should never be used, with the <tt>ServiceManager</tt> as the single exception to this rule.

=== Persisting Data ===

The system uses both the file system and RDBMS:s (SQL Server) to store data.

* Forest data (stand registers, inventory data, GIS data, treatment units etc) are stored in a RDBMS, the "ForestDb"
* Calculated results and optimization results (plans) are stored in another RDBMS, the "ResultDb"
* Project information and templates are stored in the file system (typically in the user's document folder)
* Application configuration is stored in the file system (typically in the user's application data folder)

Storgate to files are mainly done via serialization. However, a major drawback with serialization is that versioning can be a problem. Also, performance can be an issue. The subsystem <tt>Slu.Heureka.BaseLayer.SerializationManagement</tt> provides helper classes to resolve some of these issues. The classes <tt>SerializationReader</tt> and <tt>SerializationWriter</tt> improves performance drastically. A recommended practice is to always serialize a version number first. By doing this, deserialization of different versions can easily be implemented. A different problem is when a class changes its name or becomes obsolete. A solution for that problem has not been implemented in the Heureka system, but it should be possible to do it using the <tt>[[http://msdn.microsoft.com/en-US/library/system.runtime.serialization.serializationbinder |SerializationBinder]]</tt> class in the .Net framework.

For simple configuration data, the class <tt>ConfigurationStore</tt> should be used.

For control tables, a helper class that serializes control tables has been developed. Thus it is not necessary to implement serialization for control tables.

For interaction with RDBMS the following techniques are used:
;Data readers: For fast loading of objects, mainly used for forest data
;Typed data sets: Used when the user is updating data
;Custom OR-mappning: Used for the result database

Note that for the result database, custom OR-mapping is used. The result database are created automatically based on the [[Result Models]] in the system, and existing result databases will automatically be extended if new result variables and models are introduced in later versions of the system. Queries against the result database are created by SQL queries generated with reflection from the result models.

=== Error Handling ===

When an error is discovered an exception is thrown. Built-in exceptions can be used if appropriate, such as <tt>ArgumentException</tt>, <tt>ArgumentNullException</tt>, and <tt>InvalidOperationException</tt>. In other cases Heureka specific exceptions, inheriting from <tt>ApplicationException</tt>, are used.

Code that depends on exceptions in the normal flow should be avoided. For instance, if a string should be checked for a valid number it is better to use <tt>int.TryParse()</tt> than <tt>int.Parse()</tt> as the latter throws an exception of the string not is numeric. When designing classes, consider implementing similar methods allowing clients to determine beforehand if an operation is valid or not.

Exceptions should only be caught if they are to be handled, and only those exceptions that are relevant should be caught. Do not just catch and re-throw exceptions. This leads to poor performance and also destroys the call stack of the exception.

In the user interface there must be an exception handler for all code that might throw exceptions. That code should show an error message to the user if an exception is caught. Use <tt>Slu.Heureka.BaseLayer.HeurekaForms.ErrorDialog</tt> to show error messages.

The exception message should be brief. If a longer description is needed, set the <tt>HelpLink</tt> for the exception.

=== Kommandon ===

The Command design pattern is used to encapsulate actions that the user performs into separate objects. There are several benefits with this simple pattern, so it should be used frequently:

* Command makes it possible to implement Undo and Redo
* Command moves logic from forms into separate classes, and thus reduces the complexity of forms
* The logic in a Command can easily be used in separate forms and applications

Technically, commands belongs to the presentation services. Commands are allowed to launch dialogs and message boxes, guiding the user through a flow.

=== Reports ===

Standrd reports are developed in Visual Studio as Microsoft Client Report Definitions (rdlc). These are shown in the applications with the <tt>ReportViewer</tt> component.

=== Help ===

The applications should have support for online help.

== Technical Environment ==

Handling of tree states

2010-05-21T09:13:01Z

Fkl: /* Adding new Trees */

== Tree States ==

Each tree may have one of the following states:
;Tree: Establised tree
;IngrownTree: A tree that just has been ingrown.
;Sapling: Sapling
;WatingTree: Tree waiting to be activated. This means that the future state of the tree has been calculated, and growth for the tree should not be calculated in growth prognosis. Waiting trees might be felled.
;WaitingSapling: Sapling waiting to be activated. This is similar to waiting trees. However, waiting saplings cannot be cleaned.
;RemovedTree:Tree that is dead
;InvalidTree:Tree that is invalid. A tree can be removed if it is invalid in the current period.

Each <tt>Tree</tt> has a state before treatment, <tt>TreeCategory</tt>, and after treatment, <tt>TreeCategoryResidual</tt>.

== Sorting Trees ==

The <tt>TreeCollection</tt> class keeps trees sorted in the current period. This makes it easy and fast to iterate over trees with a certain state, since all those trees are kept together.

== Adding new Trees ==

Both the ingrowth model and the regeneration models creates and adds new <tt>Tree</tt>s to a <tt>PredictionUnit</tt>.

Say that the regeneration model runs in period 2, and the saplings are to be activated in period 4. A <tt>Tree</tt> object would then have the following states for each period (before and after treatment, Residual State is state after treatment):

{| border="1"
|-
|Period||width="120pt"|0||width="120pt"|1||width="120pt"|2||width="120pt"|3||width="120pt"|4||width="120pt"|5
|-
|State||Invalid||Invalid||Invalid||Waiting Sapling||Waiting Sapling||Sapling
|-
|Residual State||Invalid||Invalid||Waiting Sapling||Waiting Sapling||Sapling||Sapling
|}

This means that:

* If current period of the <tt>TreatmentUnit</tt> is changed back to period 0, 1, or 2 the <tt>Tree</tt> object will be removed, since its state is invalid.
* If current period is 3 or 4, growth of the <tt>Tree</tt> shall not be calculated, since the state WaitingSapling indicates that the <tt>Tree</tt> already has a calculated future state.
* If current period is 5, growth of the <tt>Tree</tt> shall be calculated, using height growth model for saplings. The <tt>Tree</tt> may also be cleaned since it represents a sapling.

Handling of tree states

2010-05-21T09:12:46Z

Fkl: /* Adding new Trees */

== Tree States ==

Each tree may have one of the following states:
;Tree: Establised tree
;IngrownTree: A tree that just has been ingrown.
;Sapling: Sapling
;WatingTree: Tree waiting to be activated. This means that the future state of the tree has been calculated, and growth for the tree should not be calculated in growth prognosis. Waiting trees might be felled.
;WaitingSapling: Sapling waiting to be activated. This is similar to waiting trees. However, waiting saplings cannot be cleaned.
;RemovedTree:Tree that is dead
;InvalidTree:Tree that is invalid. A tree can be removed if it is invalid in the current period.

Each <tt>Tree</tt> has a state before treatment, <tt>TreeCategory</tt>, and after treatment, <tt>TreeCategoryResidual</tt>.

== Sorting Trees ==

The <tt>TreeCollection</tt> class keeps trees sorted in the current period. This makes it easy and fast to iterate over trees with a certain state, since all those trees are kept together.

== Adding new Trees ==

Both the ingrowth model and the regeneration models creates and adds new <tt>Tree</tt>s to a <tt>PredictionUnit</tt>.

Say that the regeneration model runs in period 2, and the saplings are to be activated in period 4. A <tt>Tree</tt> object would then have the following states for each period (before and after treatment, Residual State is state after treatment):

{| border="1"
|-
|Period||width="120pt"|0||width="120pt"|1||width="120pt"|2||width="120pt"|3||width="120pt"|4||width="120pt"|5
|-
|State||Invalid||Invalid||Invalid||Waiting Sapling||Waiting Sapling||Sapling
|-
|Residual State||Invalid||Invalid||Waiting Sapling||Waiting Sapling||Sapling||Sapling
|}

This means that:

* If current period of the <tt>TreatmentUnit</tt> is changed back to period 0, 1, or 2 the <tt>Tree</tt> object will be removed, since its state is invalid.
* If current period is 3, growth of the <tt>Tree</tt> shall not be calculated, since the state WaitingSapling indicates that the <tt>Tree</tt> already has a calculated future state.
* If current period is 4, growth of the <tt>Tree</tt> shall be calculated, using height growth model for saplings. The <tt>Tree</tt> may also be cleaned since it represents a sapling.

System Architecture

2010-05-21T09:08:09Z

Fkl: /* Persisting Data */

== Architectural Goals and Quality ==

For Heureka, the two most important quality goals are modifiability and performance. The system should be flexible enough to allow maintenance and further development in a cost effective manner. At the same time performance should be good enough to allow simulation on large amounts of data. To a certain extent, these goals are contradictable.

In addition to this, testability is an important quality aspect. As many parts as possible should be possible to test automatically, e.g. with unit testing tools such as [http://www.nunit.org/ NUnit]. This sometimes means that sub functions must be made public so that they can be tested from external code. Over time, this goal has been proven more important than originally expected. This means that this goal has not always been met in the existing code, for instance many classes has a lot of dependencies on other classes making them harder to test.*

Other quality goals are less important:

* Security. There are no specific security requirements. The system will use security functions available in the database and operating system.
* Availability. The system is a single user application, so availability is not considered in the architecture.
* Portability. Portability is not required.

== Logical View ==

=== Forest model and Calculations ===
[[file:Forest_and_Calculations.png]]

The key entity in Heureka is the Treatment Unit, that represents a stand, i.e. an area restricted in space, with the same type of forest. A Treatment Unit is the smallest unit treatments are applied for. Each treatment unit contains one or more predictions units. A prediction unit represents a plot or a cell inside the treatment unit. Each prediction unit contains trees. Trees have [[Handling of tree states|different states]], identifying if the tree object represents a sapling, a tree, is dead and so forth. Each of these entities [[handle different time periods]].

Treatments are simulated in Heureka with different type of treatment models such as regeneration, fertilization, cleaning, thinning, and final felling.

Growth and yield models calculates tree related values such as volume, basal area growth, height, age, and bark thickness. With help of the growth models, a treatment unit can grow, i.e. the state in a future time period can be calculated.

[[Result models]] are used to calculate different types on results. Based on the state of a treatment unit in a given time period, different types of results can be calculated, such as cost and revenue of treatments, amount of biomass in the living forest, or amount of litter added to the ground. A result model may also produce a result based on the results in other result models (e.g. the recreation model uses input from the dead wood model).

Simulation models or frameworks, allows treatment programs to be calculated for a treatment unit. A simulation model utilizes the growth and yield models, the treatment models, and sometimes also result models, to simulate different alternatives for managing a treatment unit. When growth prognosis and treatments has been simulated for a number of periods, the treatment unit (together with its prediction units and their trees and saplings) contains information about the forest state in all periods that were included in the simulation. The results can be saved in a treatment program, which contains results for all periods with the desired result models. Currently, three simulation models are implemented in Heureka: the (strategic) [[Treatment Program Generator Design|Treatment Program Generator]], the [[Tactical Treatment Program Generator Design|Tactical Treatment Program Generator]], and the [[Regional Framework Design|Regional Framework]].

An optimization model is used to create a plan. A plan consists of a selection of treatment programs (one for each treatment unit in the plan), that gives the best result according to the optimization model. An optimization model is defined using the results from the result models. Any variable produced by a result model can be used in an optimization model. Optimization models differs from other models in Heureka, these are the only models that are defined by the user (all other models are programmed into the system).

Treatment units may be classified in forest domains. A user may define a forest domain, based on variables from the result models. The forest domain is then used to configure a simulation model.

=== Data Import ===

[[file:Data_Import.png]]

A <tt>TreatmentUnit</tt> can be created from a NFI plot (Riksskogstaxeringen). In this case, a<tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each NFI plot (if the NFI plot is splitted a <tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each part of the plot).

Similarly FMPP data can be imported into Heureka (not shown in figure).

Another option is to import a stand register. From <tt>StandObject</tt>s in the stand register, <tt>TreatmentUnit</tt>s can be simulated. In this case, trees or saplings are created for the <tt>TreatmentUnit</tt>, based on stand level variables in the <tt>StandObject</tt>. The simulation process is stochastic, meaning that the result will be slightly different each time if repeated several times for the same <tt>StandObject</tt>.

It is also possible to get data to Heureka by making a sample design, choosing <tt>StandObject</tt>s to be inventoried, and then to make a field inventory using [[Ivent]], to get real plot data and inventoried trees and from that data create <tt>TreatmentUnit</tt>s.

The last option to get data into Heureka is to manually enter data using [[StandWise]] (not shown in figure).

All forest data is stored in a relational database.

=== Projects ===

[[file:Projects.png]]

A <tt>Project</tt> contains <tt>ControlCategories</tt> and <tt>ForestDomains</tt>. Each <tt>ForestDomain</tt> refers to a <tt>ControlCategory</tt>, and each <tt>ControlCategory</tt> contains a number of <tt>[[Design of Control Tables|ControlTables]]</tt>, each of which contains user settings for a model or a group of related models in the system.

Also, a <tt>Project</tt> contains the <tt>TreatmentUnits</tt> that the user is working with (the <tt>TreatmentUnits</tt> are actually kept in an <tt>AnalysisArea</tt>, not shown in the figure).

A <tt>Project</tt> may also contain other items, such as optimization models (not shown in the figure).

The project information is saved as files in the file system.

== Design Principles ==

=== Layering ===

[[file:layering.png]]

The system is built with a layered architecture (see for example [[ISBN 0321154959|Bass et al: Software Architecture in Practice]]. The layering is based on the system logic, where each layer adds functionality from a lower layer.

The three layers are:

;Application Layer: Each application is a separate subsystem. An application connects the domain specific subsystems into the functionality provided by the application.
;Domain Layer: A large number of subsystems with different types of domain specific functionality. Each subsystem has its own logic, and in many cases also presentation and persistence services. By having the presentation in the domain layer, UI functionality can be reused between applications.
;Base Layer: General purpose support functions.

The purpose of the layering is to achieve modifiability by isolation of changes. Changes in a higher layer does not affect a lower layer at all.

The layering is not strict, meaning that a higher layer can access any lower layer.

A similar layering is proposed in IBM Rational Unified Process, and in Domain Driven Design. The advantage of layering by generality as opposed to layering by type (as proposed by Microsoft) is lower coupling and higher cohesion.

Inside a subsystem, layering by type, i.e. UI -> Logic -> DB should be done (if a subsystem has a presentation and/or persistence service). A subsystem should be able to use the logic of another subsystem without refering to the presentation or persistence service of that subsystem. The persistence service should be encapsulated inside the subsystem and not be used directly by other subsystems. The presentation service of a subsystem should be available for composition of UI.

''Unfortunately the subsystem layering has not always been used, in many cases several subsystems access the same tables in the database directly. Some subsystems are also poorly layered, e.g. with database code inside the UI, or UI code inside the logic.''

=== MVC ===

Linking between user interface and the domain model is done with the architectural pattern Model-View-Controller (Reenskaug 1979).

The model is a domain entity. When the entity is changed, it signals that with an event so that all views rendering the entity can update themselves. The event <tt>PropertyChanged</tt> is used when a property is changed, the interface <tt>IBindingList</tt> is used when a list or collection is changed. In some cases other events are also used, in <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> there are a few more EventArgs that can be used. That namespace also contains the class <tt>ExtendedBindingList</tt> which is recommended for collections that can be bound.

The view is any kind of graphical control, such as a TextBox, a DataGrid, a TreeView, or a Map. The view can show and change some parts of the entity.

The controller is the object that reacts on user inputs, typically event handlers in a form.

When developing with MVC it is important not to short-circuit the view and the controller when they are implemented in the same class. The event handler should only update the model, and not trigger changes in the view directly.

=== Dependency inversion ===

To reduce dependencies between classes and subsystems, should the subsystems that need a particular service define an interface for that service. For example, the <tt>Forest</tt> subsystem needs biomass to be calculated. To avoid a direct (and circular) dependency from <tt>Forest</tt> to <tt>Biomass</tt>, the <tt>Forest</tt> subsystem declares an interface, <tt>IBiomassService</tt>, and the <tt>Biomass</tt> subsystem implements that interface.

With dependency inversation, a new problem arises, how does an object locate the needed services? There are two common approaches to solving this problem: either Dependency Injection is used, or a Service Locator is used. For Heureka, the latter approach has been used.

The subsystem <tt>Slu.Heureka.BaseLayer.Services</tt> implements a service locator. Key classes in interfaces in that subsystem are:

;IService:Interface that must be implemented by all services
;Service<T>:Generic class for accessing a service
;ServiceAttribute:Attribute that should be set on all services that should be auto loaded
;ServiceBase:Base class for implementing a service
;ServiceManager:The service locator

The <tt>ServiceManager</tt> is a Singleton. It supports auto loading of services (all services marked with the service attribute will be loaded at application startup) as well as explicit loading of services (very useful in unit tests).

The <tt>Services</tt> subsystem was introduced relatively late in the project but has proven to be very flexible and useful. In future development, it is recommended to use it more frequently to reduce dependencies in the system. The recommended approach is that when:

* A class needs to instantiate other classes (except .Net classes), a FactoryService should be implemented
* A class needs to use another subsystem, an interface to that subsystem should be implemented

Static classes and singletons should never be used, with the <tt>ServiceManager</tt> as the single exception to this rule.

=== Persisting Data ===

The system uses both the file system and RDBMS:s (SQL Server) to store data.

* Forest data (stand registers, inventory data, GIS data, treatment units etc) are stored in a RDBMS, the "ForestDb"
* Calculated results and optimization results (plans) are stored in another RDBMS, the "ResultDb"
* Project information and templates are stored in the file system (typically in the user's document folder)
* Application configuration is stored in the file system (typically in the user's application data folder)

Storgate to files are mainly done via serialization. However, a major drawback with serialization is that versioning can be a problem. Also, performance can be an issue. The subsystem <tt>Slu.Heureka.BaseLayer.SerializationManagement</tt> provides helper classes to resolve some of these issues. The classes <tt>SerializationReader</tt> and <tt>SerializationWriter</tt> improves performance drastically. A recommended practice is to always serialize a version number first. By doing this, deserialization of different versions can easily be implemented. A different problem is when a class changes its name or becomes obsolete. A solution for that problem has not been implemented in the Heureka system, but it should be possible to do it using the <tt>[[http://msdn.microsoft.com/en-US/library/system.runtime.serialization.serializationbinder |SerializationBinder]]</tt> class in the .Net framework.

For simple configuration data, the class <tt>ConfigurationStore</tt> should be used.

For control tables, a helper class that serializes control tables has been developed. Thus it is not necessary to implement serialization for control tables.

For interaction with RDBMS the following techniques are used:
;Data readers: For fast loading of objects, mainly used for forest data
;Typed data sets: Used when the user is updating data
;Custom OR-mappning: Used for the result database

Note that for the result database, custom OR-mapping is used. The result database are created automatically based on the [[Result Models]] in the system, and existing result databases will automatically be extended if new result variables and models are introduced in later versions of the system. Queries against the result database are created by SQL queries generated with reflection from the result models.

=== Error Handling ===

When an error is discovered an exception is thrown. Built-in exceptions can be used if appropriate, such as <tt>ArgumentException</tt>, <tt>ArgumentNullException</tt>, and <tt>InvalidOperationException</tt>. In other cases Heureka specific exceptions, inheriting from <tt>ApplicationException</tt>, are used.

Code that depends on exceptions in the normal flow should be avoided. For instance, if a string should be checked for a valid number it is better to use <tt>int.TryParse()</tt> than <tt>int.Parse()</tt> as the latter throws an exception of the string not is numeric. When designing classes, consider implementing similar methods allowing clients to determine beforehand if an operation is valid or not.

Exceptions should only be caught if they are to be handled, and only those exceptions that are relevant should be caught. Do not just catch and re-throw exceptions. This leads to poor performance and also destroys the call stack of the exception.

In the user interface there must be an exception handler for all code that might throw exceptions. That code should show an error message to the user if an exception is caught. Use <tt>Slu.Heureka.BaseLayer.HeurekaForms.ErrorDialog</tt> to show error messages.

The exception message should be brief. If a longer description is needed, set the <tt>HelpLink</tt> for the exception.

=== Kommandon ===

The Command design pattern is used to encapsulate actions that the user performs into separate objects. There are several benefits with this simple pattern, so it should be used frequently:

* Command makes it possible to implement Undo and Redo
* Command moves logic from forms into separate classes, and thus reduces the complexity of forms
* The logic in a Command can easily be used in separate forms and applications

Technically, commands belongs to the presentation services. Commands are allowed to launch dialogs and message boxes, guiding the user through a flow.

=== Reports ===

Standrd reports are developed in Visual Studio as Microsoft Client Report Definitions (rdlc). These are shown in the applications with the <tt>ReportViewer</tt> component.

=== Help ===

The applications should have support for online help.

== Technical Environment ==

System Architecture

2010-05-21T09:06:50Z

Fkl: /* Persisting Data */

== Architectural Goals and Quality ==

For Heureka, the two most important quality goals are modifiability and performance. The system should be flexible enough to allow maintenance and further development in a cost effective manner. At the same time performance should be good enough to allow simulation on large amounts of data. To a certain extent, these goals are contradictable.

In addition to this, testability is an important quality aspect. As many parts as possible should be possible to test automatically, e.g. with unit testing tools such as [http://www.nunit.org/ NUnit]. This sometimes means that sub functions must be made public so that they can be tested from external code. Over time, this goal has been proven more important than originally expected. This means that this goal has not always been met in the existing code, for instance many classes has a lot of dependencies on other classes making them harder to test.*

Other quality goals are less important:

* Security. There are no specific security requirements. The system will use security functions available in the database and operating system.
* Availability. The system is a single user application, so availability is not considered in the architecture.
* Portability. Portability is not required.

== Logical View ==

=== Forest model and Calculations ===
[[file:Forest_and_Calculations.png]]

The key entity in Heureka is the Treatment Unit, that represents a stand, i.e. an area restricted in space, with the same type of forest. A Treatment Unit is the smallest unit treatments are applied for. Each treatment unit contains one or more predictions units. A prediction unit represents a plot or a cell inside the treatment unit. Each prediction unit contains trees. Trees have [[Handling of tree states|different states]], identifying if the tree object represents a sapling, a tree, is dead and so forth. Each of these entities [[handle different time periods]].

Treatments are simulated in Heureka with different type of treatment models such as regeneration, fertilization, cleaning, thinning, and final felling.

Growth and yield models calculates tree related values such as volume, basal area growth, height, age, and bark thickness. With help of the growth models, a treatment unit can grow, i.e. the state in a future time period can be calculated.

[[Result models]] are used to calculate different types on results. Based on the state of a treatment unit in a given time period, different types of results can be calculated, such as cost and revenue of treatments, amount of biomass in the living forest, or amount of litter added to the ground. A result model may also produce a result based on the results in other result models (e.g. the recreation model uses input from the dead wood model).

Simulation models or frameworks, allows treatment programs to be calculated for a treatment unit. A simulation model utilizes the growth and yield models, the treatment models, and sometimes also result models, to simulate different alternatives for managing a treatment unit. When growth prognosis and treatments has been simulated for a number of periods, the treatment unit (together with its prediction units and their trees and saplings) contains information about the forest state in all periods that were included in the simulation. The results can be saved in a treatment program, which contains results for all periods with the desired result models. Currently, three simulation models are implemented in Heureka: the (strategic) [[Treatment Program Generator Design|Treatment Program Generator]], the [[Tactical Treatment Program Generator Design|Tactical Treatment Program Generator]], and the [[Regional Framework Design|Regional Framework]].

An optimization model is used to create a plan. A plan consists of a selection of treatment programs (one for each treatment unit in the plan), that gives the best result according to the optimization model. An optimization model is defined using the results from the result models. Any variable produced by a result model can be used in an optimization model. Optimization models differs from other models in Heureka, these are the only models that are defined by the user (all other models are programmed into the system).

Treatment units may be classified in forest domains. A user may define a forest domain, based on variables from the result models. The forest domain is then used to configure a simulation model.

=== Data Import ===

[[file:Data_Import.png]]

A <tt>TreatmentUnit</tt> can be created from a NFI plot (Riksskogstaxeringen). In this case, a<tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each NFI plot (if the NFI plot is splitted a <tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each part of the plot).

Similarly FMPP data can be imported into Heureka (not shown in figure).

Another option is to import a stand register. From <tt>StandObject</tt>s in the stand register, <tt>TreatmentUnit</tt>s can be simulated. In this case, trees or saplings are created for the <tt>TreatmentUnit</tt>, based on stand level variables in the <tt>StandObject</tt>. The simulation process is stochastic, meaning that the result will be slightly different each time if repeated several times for the same <tt>StandObject</tt>.

It is also possible to get data to Heureka by making a sample design, choosing <tt>StandObject</tt>s to be inventoried, and then to make a field inventory using [[Ivent]], to get real plot data and inventoried trees and from that data create <tt>TreatmentUnit</tt>s.

The last option to get data into Heureka is to manually enter data using [[StandWise]] (not shown in figure).

All forest data is stored in a relational database.

=== Projects ===

[[file:Projects.png]]

A <tt>Project</tt> contains <tt>ControlCategories</tt> and <tt>ForestDomains</tt>. Each <tt>ForestDomain</tt> refers to a <tt>ControlCategory</tt>, and each <tt>ControlCategory</tt> contains a number of <tt>[[Design of Control Tables|ControlTables]]</tt>, each of which contains user settings for a model or a group of related models in the system.

Also, a <tt>Project</tt> contains the <tt>TreatmentUnits</tt> that the user is working with (the <tt>TreatmentUnits</tt> are actually kept in an <tt>AnalysisArea</tt>, not shown in the figure).

A <tt>Project</tt> may also contain other items, such as optimization models (not shown in the figure).

The project information is saved as files in the file system.

== Design Principles ==

=== Layering ===

[[file:layering.png]]

The system is built with a layered architecture (see for example [[ISBN 0321154959|Bass et al: Software Architecture in Practice]]. The layering is based on the system logic, where each layer adds functionality from a lower layer.

The three layers are:

;Application Layer: Each application is a separate subsystem. An application connects the domain specific subsystems into the functionality provided by the application.
;Domain Layer: A large number of subsystems with different types of domain specific functionality. Each subsystem has its own logic, and in many cases also presentation and persistence services. By having the presentation in the domain layer, UI functionality can be reused between applications.
;Base Layer: General purpose support functions.

The purpose of the layering is to achieve modifiability by isolation of changes. Changes in a higher layer does not affect a lower layer at all.

The layering is not strict, meaning that a higher layer can access any lower layer.

A similar layering is proposed in IBM Rational Unified Process, and in Domain Driven Design. The advantage of layering by generality as opposed to layering by type (as proposed by Microsoft) is lower coupling and higher cohesion.

Inside a subsystem, layering by type, i.e. UI -> Logic -> DB should be done (if a subsystem has a presentation and/or persistence service). A subsystem should be able to use the logic of another subsystem without refering to the presentation or persistence service of that subsystem. The persistence service should be encapsulated inside the subsystem and not be used directly by other subsystems. The presentation service of a subsystem should be available for composition of UI.

''Unfortunately the subsystem layering has not always been used, in many cases several subsystems access the same tables in the database directly. Some subsystems are also poorly layered, e.g. with database code inside the UI, or UI code inside the logic.''

=== MVC ===

Linking between user interface and the domain model is done with the architectural pattern Model-View-Controller (Reenskaug 1979).

The model is a domain entity. When the entity is changed, it signals that with an event so that all views rendering the entity can update themselves. The event <tt>PropertyChanged</tt> is used when a property is changed, the interface <tt>IBindingList</tt> is used when a list or collection is changed. In some cases other events are also used, in <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> there are a few more EventArgs that can be used. That namespace also contains the class <tt>ExtendedBindingList</tt> which is recommended for collections that can be bound.

The view is any kind of graphical control, such as a TextBox, a DataGrid, a TreeView, or a Map. The view can show and change some parts of the entity.

The controller is the object that reacts on user inputs, typically event handlers in a form.

When developing with MVC it is important not to short-circuit the view and the controller when they are implemented in the same class. The event handler should only update the model, and not trigger changes in the view directly.

=== Dependency inversion ===

To reduce dependencies between classes and subsystems, should the subsystems that need a particular service define an interface for that service. For example, the <tt>Forest</tt> subsystem needs biomass to be calculated. To avoid a direct (and circular) dependency from <tt>Forest</tt> to <tt>Biomass</tt>, the <tt>Forest</tt> subsystem declares an interface, <tt>IBiomassService</tt>, and the <tt>Biomass</tt> subsystem implements that interface.

With dependency inversation, a new problem arises, how does an object locate the needed services? There are two common approaches to solving this problem: either Dependency Injection is used, or a Service Locator is used. For Heureka, the latter approach has been used.

The subsystem <tt>Slu.Heureka.BaseLayer.Services</tt> implements a service locator. Key classes in interfaces in that subsystem are:

;IService:Interface that must be implemented by all services
;Service<T>:Generic class for accessing a service
;ServiceAttribute:Attribute that should be set on all services that should be auto loaded
;ServiceBase:Base class for implementing a service
;ServiceManager:The service locator

The <tt>ServiceManager</tt> is a Singleton. It supports auto loading of services (all services marked with the service attribute will be loaded at application startup) as well as explicit loading of services (very useful in unit tests).

The <tt>Services</tt> subsystem was introduced relatively late in the project but has proven to be very flexible and useful. In future development, it is recommended to use it more frequently to reduce dependencies in the system. The recommended approach is that when:

* A class needs to instantiate other classes (except .Net classes), a FactoryService should be implemented
* A class needs to use another subsystem, an interface to that subsystem should be implemented

Static classes and singletons should never be used, with the <tt>ServiceManager</tt> as the single exception to this rule.

=== Persisting Data ===

The system uses both the file system and RDBMS:s (SQL Server) to store data.

* Forest data (stand registers, inventory data, GIS data, treatment units etc) are stored in a RDBMS, the "ForestDb"
* Calculated results and optimization results (plans) are stored in another RDBMS, the "ResultDb"
* Project information and templates are stored in the file system (typically in the user's document folder)
* Application configuration is stored in the file system (typically in the user's application data folder)

Storgate to files are mainly done via serialization. However, a major drawback with serialization is that versioning can be a problem. Also, performance can be an issue. The subsystem <tt>Slu.Heureka.BaseLayer.SerializationManagement</tt> provides helper classes to resolve some of these issues. The classes <tt>SerializationReader</tt> and <tt>SerializationWriter</tt> improves performance drastically. A recommended practice is to always serialize a version number first. By doing this, deserialization of different versions can easily be implemented. A different problem is when a class changes its name or becomes obsolete. A solution for that problem has not been implemented in the Heureka system, but it should be possible to do it using the <tt>[[http://msdn.microsoft.com/en-US/library/system.runtime.serialization.serializationbinder|SerializationBinder]]</tt> class in the .Net framework.

For simple configuration data, the class <tt>ConfigurationStore</tt> should be used.

For control tables, a helper class that serializes control tables has been developed. Thus it is not necessary to implement serialization for control tables.

For interaction with RDBMS the following techniques are used:
;Data readers: For fast loading of objects, mainly used for forest data
;Typed data sets: Used when the user is updating data
;Custom OR-mappning: Used for the result database

Note that for the result database, custom OR-mapping is used. The result database are created automatically based on the [[Result Models]] in the system, and existing result databases will automatically be extended if new result variables and models are introduced in later versions of the system. Queries against the result database are created by SQL queries generated with reflection from the result models.

=== Error Handling ===

When an error is discovered an exception is thrown. Built-in exceptions can be used if appropriate, such as <tt>ArgumentException</tt>, <tt>ArgumentNullException</tt>, and <tt>InvalidOperationException</tt>. In other cases Heureka specific exceptions, inheriting from <tt>ApplicationException</tt>, are used.

Code that depends on exceptions in the normal flow should be avoided. For instance, if a string should be checked for a valid number it is better to use <tt>int.TryParse()</tt> than <tt>int.Parse()</tt> as the latter throws an exception of the string not is numeric. When designing classes, consider implementing similar methods allowing clients to determine beforehand if an operation is valid or not.

Exceptions should only be caught if they are to be handled, and only those exceptions that are relevant should be caught. Do not just catch and re-throw exceptions. This leads to poor performance and also destroys the call stack of the exception.

In the user interface there must be an exception handler for all code that might throw exceptions. That code should show an error message to the user if an exception is caught. Use <tt>Slu.Heureka.BaseLayer.HeurekaForms.ErrorDialog</tt> to show error messages.

The exception message should be brief. If a longer description is needed, set the <tt>HelpLink</tt> for the exception.

=== Kommandon ===

The Command design pattern is used to encapsulate actions that the user performs into separate objects. There are several benefits with this simple pattern, so it should be used frequently:

* Command makes it possible to implement Undo and Redo
* Command moves logic from forms into separate classes, and thus reduces the complexity of forms
* The logic in a Command can easily be used in separate forms and applications

Technically, commands belongs to the presentation services. Commands are allowed to launch dialogs and message boxes, guiding the user through a flow.

=== Reports ===

Standrd reports are developed in Visual Studio as Microsoft Client Report Definitions (rdlc). These are shown in the applications with the <tt>ReportViewer</tt> component.

=== Help ===

The applications should have support for online help.

== Technical Environment ==

System Architecture

2010-05-21T09:03:47Z

Fkl: /* Data Import */

== Architectural Goals and Quality ==

For Heureka, the two most important quality goals are modifiability and performance. The system should be flexible enough to allow maintenance and further development in a cost effective manner. At the same time performance should be good enough to allow simulation on large amounts of data. To a certain extent, these goals are contradictable.

In addition to this, testability is an important quality aspect. As many parts as possible should be possible to test automatically, e.g. with unit testing tools such as [http://www.nunit.org/ NUnit]. This sometimes means that sub functions must be made public so that they can be tested from external code. Over time, this goal has been proven more important than originally expected. This means that this goal has not always been met in the existing code, for instance many classes has a lot of dependencies on other classes making them harder to test.*

Other quality goals are less important:

* Security. There are no specific security requirements. The system will use security functions available in the database and operating system.
* Availability. The system is a single user application, so availability is not considered in the architecture.
* Portability. Portability is not required.

== Logical View ==

=== Forest model and Calculations ===
[[file:Forest_and_Calculations.png]]

The key entity in Heureka is the Treatment Unit, that represents a stand, i.e. an area restricted in space, with the same type of forest. A Treatment Unit is the smallest unit treatments are applied for. Each treatment unit contains one or more predictions units. A prediction unit represents a plot or a cell inside the treatment unit. Each prediction unit contains trees. Trees have [[Handling of tree states|different states]], identifying if the tree object represents a sapling, a tree, is dead and so forth. Each of these entities [[handle different time periods]].

Treatments are simulated in Heureka with different type of treatment models such as regeneration, fertilization, cleaning, thinning, and final felling.

Growth and yield models calculates tree related values such as volume, basal area growth, height, age, and bark thickness. With help of the growth models, a treatment unit can grow, i.e. the state in a future time period can be calculated.

[[Result models]] are used to calculate different types on results. Based on the state of a treatment unit in a given time period, different types of results can be calculated, such as cost and revenue of treatments, amount of biomass in the living forest, or amount of litter added to the ground. A result model may also produce a result based on the results in other result models (e.g. the recreation model uses input from the dead wood model).

Simulation models or frameworks, allows treatment programs to be calculated for a treatment unit. A simulation model utilizes the growth and yield models, the treatment models, and sometimes also result models, to simulate different alternatives for managing a treatment unit. When growth prognosis and treatments has been simulated for a number of periods, the treatment unit (together with its prediction units and their trees and saplings) contains information about the forest state in all periods that were included in the simulation. The results can be saved in a treatment program, which contains results for all periods with the desired result models. Currently, three simulation models are implemented in Heureka: the (strategic) [[Treatment Program Generator Design|Treatment Program Generator]], the [[Tactical Treatment Program Generator Design|Tactical Treatment Program Generator]], and the [[Regional Framework Design|Regional Framework]].

An optimization model is used to create a plan. A plan consists of a selection of treatment programs (one for each treatment unit in the plan), that gives the best result according to the optimization model. An optimization model is defined using the results from the result models. Any variable produced by a result model can be used in an optimization model. Optimization models differs from other models in Heureka, these are the only models that are defined by the user (all other models are programmed into the system).

Treatment units may be classified in forest domains. A user may define a forest domain, based on variables from the result models. The forest domain is then used to configure a simulation model.

=== Data Import ===

[[file:Data_Import.png]]

A <tt>TreatmentUnit</tt> can be created from a NFI plot (Riksskogstaxeringen). In this case, a<tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each NFI plot (if the NFI plot is splitted a <tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each part of the plot).

Similarly FMPP data can be imported into Heureka (not shown in figure).

Another option is to import a stand register. From <tt>StandObject</tt>s in the stand register, <tt>TreatmentUnit</tt>s can be simulated. In this case, trees or saplings are created for the <tt>TreatmentUnit</tt>, based on stand level variables in the <tt>StandObject</tt>. The simulation process is stochastic, meaning that the result will be slightly different each time if repeated several times for the same <tt>StandObject</tt>.

It is also possible to get data to Heureka by making a sample design, choosing <tt>StandObject</tt>s to be inventoried, and then to make a field inventory using [[Ivent]], to get real plot data and inventoried trees and from that data create <tt>TreatmentUnit</tt>s.

The last option to get data into Heureka is to manually enter data using [[StandWise]] (not shown in figure).

All forest data is stored in a relational database.

=== Projects ===

[[file:Projects.png]]

A <tt>Project</tt> contains <tt>ControlCategories</tt> and <tt>ForestDomains</tt>. Each <tt>ForestDomain</tt> refers to a <tt>ControlCategory</tt>, and each <tt>ControlCategory</tt> contains a number of <tt>[[Design of Control Tables|ControlTables]]</tt>, each of which contains user settings for a model or a group of related models in the system.

Also, a <tt>Project</tt> contains the <tt>TreatmentUnits</tt> that the user is working with (the <tt>TreatmentUnits</tt> are actually kept in an <tt>AnalysisArea</tt>, not shown in the figure).

A <tt>Project</tt> may also contain other items, such as optimization models (not shown in the figure).

The project information is saved as files in the file system.

== Design Principles ==

=== Layering ===

[[file:layering.png]]

The system is built with a layered architecture (see for example [[ISBN 0321154959|Bass et al: Software Architecture in Practice]]. The layering is based on the system logic, where each layer adds functionality from a lower layer.

The three layers are:

;Application Layer: Each application is a separate subsystem. An application connects the domain specific subsystems into the functionality provided by the application.
;Domain Layer: A large number of subsystems with different types of domain specific functionality. Each subsystem has its own logic, and in many cases also presentation and persistence services. By having the presentation in the domain layer, UI functionality can be reused between applications.
;Base Layer: General purpose support functions.

The purpose of the layering is to achieve modifiability by isolation of changes. Changes in a higher layer does not affect a lower layer at all.

The layering is not strict, meaning that a higher layer can access any lower layer.

A similar layering is proposed in IBM Rational Unified Process, and in Domain Driven Design. The advantage of layering by generality as opposed to layering by type (as proposed by Microsoft) is lower coupling and higher cohesion.

Inside a subsystem, layering by type, i.e. UI -> Logic -> DB should be done (if a subsystem has a presentation and/or persistence service). A subsystem should be able to use the logic of another subsystem without refering to the presentation or persistence service of that subsystem. The persistence service should be encapsulated inside the subsystem and not be used directly by other subsystems. The presentation service of a subsystem should be available for composition of UI.

''Unfortunately the subsystem layering has not always been used, in many cases several subsystems access the same tables in the database directly. Some subsystems are also poorly layered, e.g. with database code inside the UI, or UI code inside the logic.''

=== MVC ===

Linking between user interface and the domain model is done with the architectural pattern Model-View-Controller (Reenskaug 1979).

The model is a domain entity. When the entity is changed, it signals that with an event so that all views rendering the entity can update themselves. The event <tt>PropertyChanged</tt> is used when a property is changed, the interface <tt>IBindingList</tt> is used when a list or collection is changed. In some cases other events are also used, in <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> there are a few more EventArgs that can be used. That namespace also contains the class <tt>ExtendedBindingList</tt> which is recommended for collections that can be bound.

The view is any kind of graphical control, such as a TextBox, a DataGrid, a TreeView, or a Map. The view can show and change some parts of the entity.

The controller is the object that reacts on user inputs, typically event handlers in a form.

When developing with MVC it is important not to short-circuit the view and the controller when they are implemented in the same class. The event handler should only update the model, and not trigger changes in the view directly.

=== Dependency inversion ===

To reduce dependencies between classes and subsystems, should the subsystems that need a particular service define an interface for that service. For example, the <tt>Forest</tt> subsystem needs biomass to be calculated. To avoid a direct (and circular) dependency from <tt>Forest</tt> to <tt>Biomass</tt>, the <tt>Forest</tt> subsystem declares an interface, <tt>IBiomassService</tt>, and the <tt>Biomass</tt> subsystem implements that interface.

With dependency inversation, a new problem arises, how does an object locate the needed services? There are two common approaches to solving this problem: either Dependency Injection is used, or a Service Locator is used. For Heureka, the latter approach has been used.

The subsystem <tt>Slu.Heureka.BaseLayer.Services</tt> implements a service locator. Key classes in interfaces in that subsystem are:

;IService:Interface that must be implemented by all services
;Service<T>:Generic class for accessing a service
;ServiceAttribute:Attribute that should be set on all services that should be auto loaded
;ServiceBase:Base class for implementing a service
;ServiceManager:The service locator

The <tt>ServiceManager</tt> is a Singleton. It supports auto loading of services (all services marked with the service attribute will be loaded at application startup) as well as explicit loading of services (very useful in unit tests).

The <tt>Services</tt> subsystem was introduced relatively late in the project but has proven to be very flexible and useful. In future development, it is recommended to use it more frequently to reduce dependencies in the system. The recommended approach is that when:

* A class needs to instantiate other classes (except .Net classes), a FactoryService should be implemented
* A class needs to use another subsystem, an interface to that subsystem should be implemented

Static classes and singletons should never be used, with the <tt>ServiceManager</tt> as the single exception to this rule.

=== Persisting Data ===

The system uses both the file system and RDBMS:s (SQL Server) to store data.

* Forest data (stand registers, inventory data, GIS data, treatment units etc) are stored in a RDBMS, the "ForestDb"
* Calculated results and optimization results (plans) are stored in another RDBMS, the "ResultDb"
* Project information and templates are stored in the file system (typically in the user's document folder)
* Application configuration is stored in the file system (typically in the user's application data folder)

Storgate to files are mainly done via serialization. However, a major drawback with serialization is that versioning can be a problem. Also, performance can be an issue. The subsystem <tt>Slu.Heureka.BaseLayer.SerializationManagement</tt> provides helper classes to resolve some of these issues. The classes <tt>SerializationReader</tt> and <tt>SerializationWriter</tt> improves performance drastically. A recommended practice is to always serialize a version number first. By doing this, deserialization of different versions can easily be implemented. A different problem is when a class changes its name or becomes obsolete. A solution for that problem has not been implemented in the Heureka system, but it should be possible to do it using the <tt>[[http://msdn.microsoft.com/en-US/library/system.runtime.serialization.serializationbinder|SerializationBinder]]</tt> class in the .Net framework.

For simple configuration data, the class <tt>ConfigurationStore</tt> should be used.

For control tables, a helper class that serializes control tables has been developed. Thus it is not necessary to implement serialization for control tables.

For interaction with RDBMS the following techniques are used:
;Data readers: For fast loading of objects, mainly used for forest data
;Typed data sets: Used when the user is updating data
;Custom OR-mappning: Used for the result database

=== Error Handling ===

When an error is discovered an exception is thrown. Built-in exceptions can be used if appropriate, such as <tt>ArgumentException</tt>, <tt>ArgumentNullException</tt>, and <tt>InvalidOperationException</tt>. In other cases Heureka specific exceptions, inheriting from <tt>ApplicationException</tt>, are used.

Code that depends on exceptions in the normal flow should be avoided. For instance, if a string should be checked for a valid number it is better to use <tt>int.TryParse()</tt> than <tt>int.Parse()</tt> as the latter throws an exception of the string not is numeric. When designing classes, consider implementing similar methods allowing clients to determine beforehand if an operation is valid or not.

Exceptions should only be caught if they are to be handled, and only those exceptions that are relevant should be caught. Do not just catch and re-throw exceptions. This leads to poor performance and also destroys the call stack of the exception.

In the user interface there must be an exception handler for all code that might throw exceptions. That code should show an error message to the user if an exception is caught. Use <tt>Slu.Heureka.BaseLayer.HeurekaForms.ErrorDialog</tt> to show error messages.

The exception message should be brief. If a longer description is needed, set the <tt>HelpLink</tt> for the exception.

=== Kommandon ===

The Command design pattern is used to encapsulate actions that the user performs into separate objects. There are several benefits with this simple pattern, so it should be used frequently:

* Command makes it possible to implement Undo and Redo
* Command moves logic from forms into separate classes, and thus reduces the complexity of forms
* The logic in a Command can easily be used in separate forms and applications

Technically, commands belongs to the presentation services. Commands are allowed to launch dialogs and message boxes, guiding the user through a flow.

=== Reports ===

Standrd reports are developed in Visual Studio as Microsoft Client Report Definitions (rdlc). These are shown in the applications with the <tt>ReportViewer</tt> component.

=== Help ===

The applications should have support for online help.

== Technical Environment ==

Design of Control Tables

2010-05-21T09:02:33Z

Fkl: /* Serialization and Deserialization of Control Tables */

== Introduction ==

A <tt>ControlTable</tt> is a class whose instances can hold user settings. <tt>ControlTables</tt> are typically presented in a <tt>PropertyGrid</tt>, which means that no user interface has to be built for properties with a simple type.

By adding the sttribute <tt>Slu.Heureka.BaseLayer.ConfigurationHandling.ControlTable</tt> a class is marked as a <tt>ControlTable</tt>. The system will automatically discover all <tt>ControlTables</tt> at startup.

== Implementation of Control Tables ==

=== Creating a new Control Table ===

Although not required, it is recommended that <tt>ControlTables</tt> inherit from <tt>UndoablePropertyChangedBase</tt>. This base class simplifies implementation of the INotifyPropertyChanged interface, which should be used for classes presented in the <tt>PropertyGrid</tt>.

To add a property of a simple type, follow this example:

<tt>
public int CleaningVariation
{
get { return _cleaningVariation; }
[System.Runtime.CompilerServices.MethodImpl(System.Runtime.CompilerServices.MethodImplOptions.NoInlining)]
set
{
if (value < 0)
throw new ArgumentOutOfRangeException("value", "CleaningVariation must be >= 0");
ChangeProperty(ref _cleaningVariation, value);
}
}
</tt>

Note the following:

* <tt>NoInlining</tt> must be set for the set method, otherwise property changed won't work in release mode
* Validation can be done before the value is changed
* <tt>UndoablePropertyChangedBase</tt> implements <tt>ChangeProperty</tt> methods with overloads for the most common simple types.

=== Presentation of Control Tables ===

Since <tt>ControlTables</tt> are presented in a <tt>PropertyGrid</tt>, the attributes in <tt>System.ComponentModel</tt> aids with the presentation of a <tt>ControlTable</tt>, such as:

;Category: Properties with the same Category are grouped in the <tt>PropertyGrid</tt>
;DisplayName: The DisplayName is the name for the property shown in the <tt>PropertyGrid</tt>.
;Description: The Description is shown at the bottom of the <tt>PropertyGrid</tt> when the property is selected. The description should give a brief help to the user.
;DefaultValue: The DefaultValue is the value set when a new instance of a <tt>ControlTable</tt> is created. Also, the <tt>PropertyGrid</tt> shows properties with the default value in a normal font, and properties with a changed value in a bold font.
;Browsable: The Browsable attribute can be set to false to hide properties in the property grid (unconditionally, to conditionally hide properties see [[#Hiding Properties Conditionally|Hiding Properties Conditionally]]

In addition to this, a number of additional attributes and type converters are available in the <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> namespace:

;ObjectDefaultValues:Allows default values to be set on other types than simple types
;PercentTypeConverter:Presents a property with a fraction (e.g. 0.03) to be presented as a percentage (e.g. 3%)

=== Hiding Properties Conditionally ===

If the <tt>ControlTable</tt> inherits from <tt>UndoablePropertyChangedBase</tt>, it is easy to hide properties conditionally. Two protected methods can be overriden to hide properties:

;GetCategoryNamesToHide:Gets names of entire categories to be hidden
;GetPropertyNamesToHide:Gets names of properties to be hidden

Each time the <tt>ControlTable</tt> is rendered, these two methods are called, and any returned category or property will be hidden from the user.

=== Using Custom Classes inside a Control Table ===

Sometimes simple types are not convenient in a <tt>ControlTable</tt>, and a special class is developed to hold the configuration. There are several considerations when making such a class:

# The class must be serializable
# The class must be clonable
# The <tt>ControlTable</tt> must have one or more properties with the type of the class
# When the control table is cloned, each property with the custom type class must also be cloned
# The class may have a custom editor. To use the custom editor, set the Editor attribute for each property
# Changes in the custom object must trigger the <tt>PropertyChanged</tt> event:
## If the entire object is changed, it is sufficient to just send the event from the property of the ControlTable (typically this works fine
for custom classes with editors)
## If a property is changed inside the object the <tt>ControlTable</tt> must listen for <tt>PropertyChanged</tt> from the object, and propagate the event.

=== Cloning Control Tables ===

Each <tt>ControlTable</tt> must implement <tt>IClonable</tt>.

* Don't forget to clone reference types (e.g. custom classes inside the <tt>ControlTable</tt>)
* If inheriting from another <tt>ControlTable</tt>, make sure that the <tt>base.Clone()</tt> is called.

=== Extending Control Tables ===

It is possible to extend a <tt>ControlTable</tt> by inheriting from it. When <tt>ControlTables</tt> are loaded automatically, only the <tt>ControlTable</tt> lowest in the inheritance hierarchy will be loaded.

Design of Control Tables

2010-05-21T09:02:12Z

Fkl: /* Extending Control Tables */

Design of Control Tables

2010-05-21T09:00:40Z

Fkl: /* Cloning Control Tables */

== Introduction ==

A <tt>ControlTable</tt> is a class whose instances can hold user settings. <tt>ControlTables</tt> are typically presented in a <tt>PropertyGrid</tt>, which means that no user interface has to be built for properties with a simple type.

By adding the sttribute <tt>Slu.Heureka.BaseLayer.ConfigurationHandling.ControlTable</tt> a class is marked as a <tt>ControlTable</tt>. The system will automatically discover all <tt>ControlTables</tt> at startup.

== Implementation of Control Tables ==

=== Creating a new Control Table ===

Although not required, it is recommended that <tt>ControlTables</tt> inherit from <tt>UndoablePropertyChangedBase</tt>. This base class simplifies implementation of the INotifyPropertyChanged interface, which should be used for classes presented in the <tt>PropertyGrid</tt>.

To add a property of a simple type, follow this example:

<tt>
public int CleaningVariation
{
get { return _cleaningVariation; }
[System.Runtime.CompilerServices.MethodImpl(System.Runtime.CompilerServices.MethodImplOptions.NoInlining)]
set
{
if (value < 0)
throw new ArgumentOutOfRangeException("value", "CleaningVariation must be >= 0");
ChangeProperty(ref _cleaningVariation, value);
}
}
</tt>

Note the following:

* <tt>NoInlining</tt> must be set for the set method, otherwise property changed won't work in release mode
* Validation can be done before the value is changed
* <tt>UndoablePropertyChangedBase</tt> implements <tt>ChangeProperty</tt> methods with overloads for the most common simple types.

=== Presentation of Control Tables ===

Since <tt>ControlTables</tt> are presented in a <tt>PropertyGrid</tt>, the attributes in <tt>System.ComponentModel</tt> aids with the presentation of a <tt>ControlTable</tt>, such as:

;Category: Properties with the same Category are grouped in the <tt>PropertyGrid</tt>
;DisplayName: The DisplayName is the name for the property shown in the <tt>PropertyGrid</tt>.
;Description: The Description is shown at the bottom of the <tt>PropertyGrid</tt> when the property is selected. The description should give a brief help to the user.
;DefaultValue: The DefaultValue is the value set when a new instance of a <tt>ControlTable</tt> is created. Also, the <tt>PropertyGrid</tt> shows properties with the default value in a normal font, and properties with a changed value in a bold font.
;Browsable: The Browsable attribute can be set to false to hide properties in the property grid (unconditionally, to conditionally hide properties see [[#Hiding Properties Conditionally|Hiding Properties Conditionally]]

In addition to this, a number of additional attributes and type converters are available in the <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> namespace:

;ObjectDefaultValues:Allows default values to be set on other types than simple types
;PercentTypeConverter:Presents a property with a fraction (e.g. 0.03) to be presented as a percentage (e.g. 3%)

=== Hiding Properties Conditionally ===

If the <tt>ControlTable</tt> inherits from <tt>UndoablePropertyChangedBase</tt>, it is easy to hide properties conditionally. Two protected methods can be overriden to hide properties:

;GetCategoryNamesToHide:Gets names of entire categories to be hidden
;GetPropertyNamesToHide:Gets names of properties to be hidden

Each time the <tt>ControlTable</tt> is rendered, these two methods are called, and any returned category or property will be hidden from the user.

=== Using Custom Classes inside a Control Table ===

Sometimes simple types are not convenient in a <tt>ControlTable</tt>, and a special class is developed to hold the configuration. There are several considerations when making such a class:

# The class must be serializable
# The class must be clonable
# The <tt>ControlTable</tt> must have one or more properties with the type of the class
# When the control table is cloned, each property with the custom type class must also be cloned
# The class may have a custom editor. To use the custom editor, set the Editor attribute for each property
# Changes in the custom object must trigger the <tt>PropertyChanged</tt> event:
## If the entire object is changed, it is sufficient to just send the event from the property of the ControlTable (typically this works fine
for custom classes with editors)
## If a property is changed inside the object the <tt>ControlTable</tt> must listen for <tt>PropertyChanged</tt> from the object, and propagate the event.

=== Cloning Control Tables ===

Each <tt>ControlTable</tt> must implement <tt>IClonable</tt>.

* Don't forget to clone reference types (e.g. custom classes inside the <tt>ControlTable</tt>)
* If inheriting from another <tt>ControlTable</tt>, make sure that the <tt>base.Clone()</tt> is called.

=== Extending Control Tables ===

=== Serialization and Deserialization of Control Tables ===

Design of Control Tables

2010-05-21T08:58:39Z

Fkl: /* Using Custom Classes inside a Control Table */

== Introduction ==

A <tt>ControlTable</tt> is a class whose instances can hold user settings. <tt>ControlTables</tt> are typically presented in a <tt>PropertyGrid</tt>, which means that no user interface has to be built for properties with a simple type.

By adding the sttribute <tt>Slu.Heureka.BaseLayer.ConfigurationHandling.ControlTable</tt> a class is marked as a <tt>ControlTable</tt>. The system will automatically discover all <tt>ControlTables</tt> at startup.

== Implementation of Control Tables ==

=== Creating a new Control Table ===

Although not required, it is recommended that <tt>ControlTables</tt> inherit from <tt>UndoablePropertyChangedBase</tt>. This base class simplifies implementation of the INotifyPropertyChanged interface, which should be used for classes presented in the <tt>PropertyGrid</tt>.

To add a property of a simple type, follow this example:

<tt>
public int CleaningVariation
{
get { return _cleaningVariation; }
[System.Runtime.CompilerServices.MethodImpl(System.Runtime.CompilerServices.MethodImplOptions.NoInlining)]
set
{
if (value < 0)
throw new ArgumentOutOfRangeException("value", "CleaningVariation must be >= 0");
ChangeProperty(ref _cleaningVariation, value);
}
}
</tt>

Note the following:

* <tt>NoInlining</tt> must be set for the set method, otherwise property changed won't work in release mode
* Validation can be done before the value is changed
* <tt>UndoablePropertyChangedBase</tt> implements <tt>ChangeProperty</tt> methods with overloads for the most common simple types.

=== Presentation of Control Tables ===

Since <tt>ControlTables</tt> are presented in a <tt>PropertyGrid</tt>, the attributes in <tt>System.ComponentModel</tt> aids with the presentation of a <tt>ControlTable</tt>, such as:

;Category: Properties with the same Category are grouped in the <tt>PropertyGrid</tt>
;DisplayName: The DisplayName is the name for the property shown in the <tt>PropertyGrid</tt>.
;Description: The Description is shown at the bottom of the <tt>PropertyGrid</tt> when the property is selected. The description should give a brief help to the user.
;DefaultValue: The DefaultValue is the value set when a new instance of a <tt>ControlTable</tt> is created. Also, the <tt>PropertyGrid</tt> shows properties with the default value in a normal font, and properties with a changed value in a bold font.
;Browsable: The Browsable attribute can be set to false to hide properties in the property grid (unconditionally, to conditionally hide properties see [[#Hiding Properties Conditionally|Hiding Properties Conditionally]]

In addition to this, a number of additional attributes and type converters are available in the <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> namespace:

;ObjectDefaultValues:Allows default values to be set on other types than simple types
;PercentTypeConverter:Presents a property with a fraction (e.g. 0.03) to be presented as a percentage (e.g. 3%)

=== Hiding Properties Conditionally ===

If the <tt>ControlTable</tt> inherits from <tt>UndoablePropertyChangedBase</tt>, it is easy to hide properties conditionally. Two protected methods can be overriden to hide properties:

;GetCategoryNamesToHide:Gets names of entire categories to be hidden
;GetPropertyNamesToHide:Gets names of properties to be hidden

Each time the <tt>ControlTable</tt> is rendered, these two methods are called, and any returned category or property will be hidden from the user.

=== Using Custom Classes inside a Control Table ===

Sometimes simple types are not convenient in a <tt>ControlTable</tt>, and a special class is developed to hold the configuration. There are several considerations when making such a class:

# The class must be serializable
# The class must be clonable
# The <tt>ControlTable</tt> must have one or more properties with the type of the class
# When the control table is cloned, each property with the custom type class must also be cloned
# The class may have a custom editor. To use the custom editor, set the Editor attribute for each property
# Changes in the custom object must trigger the <tt>PropertyChanged</tt> event:
## If the entire object is changed, it is sufficient to just send the event from the property of the ControlTable (typically this works fine
for custom classes with editors)
## If a property is changed inside the object the <tt>ControlTable</tt> must listen for <tt>PropertyChanged</tt> from the object, and propagate the event.

=== Cloning Control Tables ===
=== Extending Control Tables ===

=== Serialization and Deserialization of Control Tables ===

Design of Control Tables

2010-05-21T08:40:44Z

Fkl: /* Hiding Properties Conditionally */

== Introduction ==

A <tt>ControlTable</tt> is a class whose instances can hold user settings. <tt>ControlTables</tt> are typically presented in a <tt>PropertyGrid</tt>, which means that no user interface has to be built for properties with a simple type.

By adding the sttribute <tt>Slu.Heureka.BaseLayer.ConfigurationHandling.ControlTable</tt> a class is marked as a <tt>ControlTable</tt>. The system will automatically discover all <tt>ControlTables</tt> at startup.

== Implementation of Control Tables ==

=== Creating a new Control Table ===

Although not required, it is recommended that <tt>ControlTables</tt> inherit from <tt>UndoablePropertyChangedBase</tt>. This base class simplifies implementation of the INotifyPropertyChanged interface, which should be used for classes presented in the <tt>PropertyGrid</tt>.

To add a property of a simple type, follow this example:

<tt>
public int CleaningVariation
{
get { return _cleaningVariation; }
[System.Runtime.CompilerServices.MethodImpl(System.Runtime.CompilerServices.MethodImplOptions.NoInlining)]
set
{
if (value < 0)
throw new ArgumentOutOfRangeException("value", "CleaningVariation must be >= 0");
ChangeProperty(ref _cleaningVariation, value);
}
}
</tt>

Note the following:

* <tt>NoInlining</tt> must be set for the set method, otherwise property changed won't work in release mode
* Validation can be done before the value is changed
* <tt>UndoablePropertyChangedBase</tt> implements <tt>ChangeProperty</tt> methods with overloads for the most common simple types.

=== Presentation of Control Tables ===

Since <tt>ControlTables</tt> are presented in a <tt>PropertyGrid</tt>, the attributes in <tt>System.ComponentModel</tt> aids with the presentation of a <tt>ControlTable</tt>, such as:

;Category: Properties with the same Category are grouped in the <tt>PropertyGrid</tt>
;DisplayName: The DisplayName is the name for the property shown in the <tt>PropertyGrid</tt>.
;Description: The Description is shown at the bottom of the <tt>PropertyGrid</tt> when the property is selected. The description should give a brief help to the user.
;DefaultValue: The DefaultValue is the value set when a new instance of a <tt>ControlTable</tt> is created. Also, the <tt>PropertyGrid</tt> shows properties with the default value in a normal font, and properties with a changed value in a bold font.
;Browsable: The Browsable attribute can be set to false to hide properties in the property grid (unconditionally, to conditionally hide properties see [[#Hiding Properties Conditionally|Hiding Properties Conditionally]]

In addition to this, a number of additional attributes and type converters are available in the <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> namespace:

;ObjectDefaultValues:Allows default values to be set on other types than simple types
;PercentTypeConverter:Presents a property with a fraction (e.g. 0.03) to be presented as a percentage (e.g. 3%)

=== Hiding Properties Conditionally ===

If the <tt>ControlTable</tt> inherits from <tt>UndoablePropertyChangedBase</tt>, it is easy to hide properties conditionally. Two protected methods can be overriden to hide properties:

;GetCategoryNamesToHide:Gets names of entire categories to be hidden
;GetPropertyNamesToHide:Gets names of properties to be hidden

Each time the <tt>ControlTable</tt> is rendered, these two methods are called, and any returned category or property will be hidden from the user.

=== Using Custom Classes inside a Control Table ===

=== Cloning Control Tables ===
=== Extending Control Tables ===

=== Serialization and Deserialization of Control Tables ===

Design of Control Tables

2010-05-21T08:35:52Z

Fkl: /* Creating a new Control Table */

Design of Control Tables

2010-05-21T07:53:09Z

Fkl:

System Architecture

2010-05-21T06:52:42Z

Fkl: /* Error Handling */

== Architectural Goals and Quality ==

For Heureka, the two most important quality goals are modifiability and performance. The system should be flexible enough to allow maintenance and further development in a cost effective manner. At the same time performance should be good enough to allow simulation on large amounts of data. To a certain extent, these goals are contradictable.

In addition to this, testability is an important quality aspect. As many parts as possible should be possible to test automatically, e.g. with unit testing tools such as [http://www.nunit.org/ NUnit]. This sometimes means that sub functions must be made public so that they can be tested from external code. Over time, this goal has been proven more important than originally expected. This means that this goal has not always been met in the existing code, for instance many classes has a lot of dependencies on other classes making them harder to test.*

Other quality goals are less important:

* Security. There are no specific security requirements. The system will use security functions available in the database and operating system.
* Availability. The system is a single user application, so availability is not considered in the architecture.
* Portability. Portability is not required.

== Logical View ==

=== Forest model and Calculations ===
[[file:Forest_and_Calculations.png]]

The key entity in Heureka is the Treatment Unit, that represents a stand, i.e. an area restricted in space, with the same type of forest. A Treatment Unit is the smallest unit treatments are applied for. Each treatment unit contains one or more predictions units. A prediction unit represents a plot or a cell inside the treatment unit. Each prediction unit contains trees. Trees have [[Handling of tree states|different states]], identifying if the tree object represents a sapling, a tree, is dead and so forth. Each of these entities [[handle different time periods]].

Treatments are simulated in Heureka with different type of treatment models such as regeneration, fertilization, cleaning, thinning, and final felling.

Growth and yield models calculates tree related values such as volume, basal area growth, height, age, and bark thickness. With help of the growth models, a treatment unit can grow, i.e. the state in a future time period can be calculated.

[[Result models]] are used to calculate different types on results. Based on the state of a treatment unit in a given time period, different types of results can be calculated, such as cost and revenue of treatments, amount of biomass in the living forest, or amount of litter added to the ground. A result model may also produce a result based on the results in other result models (e.g. the recreation model uses input from the dead wood model).

Simulation models or frameworks, allows treatment programs to be calculated for a treatment unit. A simulation model utilizes the growth and yield models, the treatment models, and sometimes also result models, to simulate different alternatives for managing a treatment unit. When growth prognosis and treatments has been simulated for a number of periods, the treatment unit (together with its prediction units and their trees and saplings) contains information about the forest state in all periods that were included in the simulation. The results can be saved in a treatment program, which contains results for all periods with the desired result models. Currently, three simulation models are implemented in Heureka: the (strategic) [[Treatment Program Generator Design|Treatment Program Generator]], the [[Tactical Treatment Program Generator Design|Tactical Treatment Program Generator]], and the [[Regional Framework Design|Regional Framework]].

An optimization model is used to create a plan. A plan consists of a selection of treatment programs (one for each treatment unit in the plan), that gives the best result according to the optimization model. An optimization model is defined using the results from the result models. Any variable produced by a result model can be used in an optimization model. Optimization models differs from other models in Heureka, these are the only models that are defined by the user (all other models are programmed into the system).

Treatment units may be classified in forest domains. A user may define a forest domain, based on variables from the result models. The forest domain is then used to configure a simulation model.

=== Data Import ===

[[file:Data_Import.png]]

A <tt>TreatmentUnit</tt> can be created from a NFI plot. In this case, a<tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each NFI plot (if the NFI plot is splitted a <tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each part of the plot).

Similarly FMPP data can be imported into Heureka (not shown in figure).

Another option is to import a stand register. From <tt>StandObject</tt>s in the stand register, <tt>TreatmentUnit</tt>s can be simulated. In this case, trees or saplings are created for the <tt>TreatmentUnit</tt>, based on stand level variables in the <tt>StandObject</tt>. The simulation process is stochastic, meaning that the result will be slightly different each time if repeated several times for the same <tt>StandObject</tt>.

It is also possible to get data to Heureka by making a sample design, choosing <tt>StandObject</tt>s to be inventoried, and then to make a field inventory using [[Ivent]], to get real plot data and inventoried trees and from that data create <tt>TreatmentUnit</tt>s.

The last option to get data into Heureka is to manually enter data using [[StandWise]] (not shown in figure).

All forest data is stored in a relational database.

=== Projects ===

[[file:Projects.png]]

A <tt>Project</tt> contains <tt>ControlCategories</tt> and <tt>ForestDomains</tt>. Each <tt>ForestDomain</tt> refers to a <tt>ControlCategory</tt>, and each <tt>ControlCategory</tt> contains a number of <tt>[[Design of Control Tables|ControlTables]]</tt>, each of which contains user settings for a model or a group of related models in the system.

Also, a <tt>Project</tt> contains the <tt>TreatmentUnits</tt> that the user is working with (the <tt>TreatmentUnits</tt> are actually kept in an <tt>AnalysisArea</tt>, not shown in the figure).

A <tt>Project</tt> may also contain other items, such as optimization models (not shown in the figure).

The project information is saved as files in the file system.

== Design Principles ==

=== Layering ===

[[file:layering.png]]

The system is built with a layered architecture (see for example [[ISBN 0321154959|Bass et al: Software Architecture in Practice]]. The layering is based on the system logic, where each layer adds functionality from a lower layer.

The three layers are:

;Application Layer: Each application is a separate subsystem. An application connects the domain specific subsystems into the functionality provided by the application.
;Domain Layer: A large number of subsystems with different types of domain specific functionality. Each subsystem has its own logic, and in many cases also presentation and persistence services. By having the presentation in the domain layer, UI functionality can be reused between applications.
;Base Layer: General purpose support functions.

The purpose of the layering is to achieve modifiability by isolation of changes. Changes in a higher layer does not affect a lower layer at all.

The layering is not strict, meaning that a higher layer can access any lower layer.

A similar layering is proposed in IBM Rational Unified Process, and in Domain Driven Design. The advantage of layering by generality as opposed to layering by type (as proposed by Microsoft) is lower coupling and higher cohesion.

Inside a subsystem, layering by type, i.e. UI -> Logic -> DB should be done (if a subsystem has a presentation and/or persistence service). A subsystem should be able to use the logic of another subsystem without refering to the presentation or persistence service of that subsystem. The persistence service should be encapsulated inside the subsystem and not be used directly by other subsystems. The presentation service of a subsystem should be available for composition of UI.

''Unfortunately the subsystem layering has not always been used, in many cases several subsystems access the same tables in the database directly. Some subsystems are also poorly layered, e.g. with database code inside the UI, or UI code inside the logic.''

=== MVC ===

Linking between user interface and the domain model is done with the architectural pattern Model-View-Controller (Reenskaug 1979).

The model is a domain entity. When the entity is changed, it signals that with an event so that all views rendering the entity can update themselves. The event <tt>PropertyChanged</tt> is used when a property is changed, the interface <tt>IBindingList</tt> is used when a list or collection is changed. In some cases other events are also used, in <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> there are a few more EventArgs that can be used. That namespace also contains the class <tt>ExtendedBindingList</tt> which is recommended for collections that can be bound.

The view is any kind of graphical control, such as a TextBox, a DataGrid, a TreeView, or a Map. The view can show and change some parts of the entity.

The controller is the object that reacts on user inputs, typically event handlers in a form.

When developing with MVC it is important not to short-circuit the view and the controller when they are implemented in the same class. The event handler should only update the model, and not trigger changes in the view directly.

=== Dependency inversion ===

To reduce dependencies between classes and subsystems, should the subsystems that need a particular service define an interface for that service. For example, the <tt>Forest</tt> subsystem needs biomass to be calculated. To avoid a direct (and circular) dependency from <tt>Forest</tt> to <tt>Biomass</tt>, the <tt>Forest</tt> subsystem declares an interface, <tt>IBiomassService</tt>, and the <tt>Biomass</tt> subsystem implements that interface.

With dependency inversation, a new problem arises, how does an object locate the needed services? There are two common approaches to solving this problem: either Dependency Injection is used, or a Service Locator is used. For Heureka, the latter approach has been used.

The subsystem <tt>Slu.Heureka.BaseLayer.Services</tt> implements a service locator. Key classes in interfaces in that subsystem are:

;IService:Interface that must be implemented by all services
;Service<T>:Generic class for accessing a service
;ServiceAttribute:Attribute that should be set on all services that should be auto loaded
;ServiceBase:Base class for implementing a service
;ServiceManager:The service locator

The <tt>ServiceManager</tt> is a Singleton. It supports auto loading of services (all services marked with the service attribute will be loaded at application startup) as well as explicit loading of services (very useful in unit tests).

The <tt>Services</tt> subsystem was introduced relatively late in the project but has proven to be very flexible and useful. In future development, it is recommended to use it more frequently to reduce dependencies in the system. The recommended approach is that when:

* A class needs to instantiate other classes (except .Net classes), a FactoryService should be implemented
* A class needs to use another subsystem, an interface to that subsystem should be implemented

Static classes and singletons should never be used, with the <tt>ServiceManager</tt> as the single exception to this rule.

=== Persisting Data ===

The system uses both the file system and RDBMS:s (SQL Server) to store data.

* Forest data (stand registers, inventory data, GIS data, treatment units etc) are stored in a RDBMS, the "ForestDb"
* Calculated results and optimization results (plans) are stored in another RDBMS, the "ResultDb"
* Project information and templates are stored in the file system (typically in the user's document folder)
* Application configuration is stored in the file system (typically in the user's application data folder)

Storgate to files are mainly done via serialization. However, a major drawback with serialization is that versioning can be a problem. Also, performance can be an issue. The subsystem <tt>Slu.Heureka.BaseLayer.SerializationManagement</tt> provides helper classes to resolve some of these issues. The classes <tt>SerializationReader</tt> and <tt>SerializationWriter</tt> improves performance drastically. A recommended practice is to always serialize a version number first. By doing this, deserialization of different versions can easily be implemented. A different problem is when a class changes its name or becomes obsolete. A solution for that problem has not been implemented in the Heureka system, but it should be possible to do it using the <tt>[[http://msdn.microsoft.com/en-US/library/system.runtime.serialization.serializationbinder|SerializationBinder]]</tt> class in the .Net framework.

For simple configuration data, the class <tt>ConfigurationStore</tt> should be used.

For control tables, a helper class that serializes control tables has been developed. Thus it is not necessary to implement serialization for control tables.

For interaction with RDBMS the following techniques are used:
;Data readers: For fast loading of objects, mainly used for forest data
;Typed data sets: Used when the user is updating data
;Custom OR-mappning: Used for the result database

=== Error Handling ===

When an error is discovered an exception is thrown. Built-in exceptions can be used if appropriate, such as <tt>ArgumentException</tt>, <tt>ArgumentNullException</tt>, and <tt>InvalidOperationException</tt>. In other cases Heureka specific exceptions, inheriting from <tt>ApplicationException</tt>, are used.

Code that depends on exceptions in the normal flow should be avoided. For instance, if a string should be checked for a valid number it is better to use <tt>int.TryParse()</tt> than <tt>int.Parse()</tt> as the latter throws an exception of the string not is numeric. When designing classes, consider implementing similar methods allowing clients to determine beforehand if an operation is valid or not.

Exceptions should only be caught if they are to be handled, and only those exceptions that are relevant should be caught. Do not just catch and re-throw exceptions. This leads to poor performance and also destroys the call stack of the exception.

In the user interface there must be an exception handler for all code that might throw exceptions. That code should show an error message to the user if an exception is caught. Use <tt>Slu.Heureka.BaseLayer.HeurekaForms.ErrorDialog</tt> to show error messages.

The exception message should be brief. If a longer description is needed, set the <tt>HelpLink</tt> for the exception.

=== Kommandon ===

The Command design pattern is used to encapsulate actions that the user performs into separate objects. There are several benefits with this simple pattern, so it should be used frequently:

* Command makes it possible to implement Undo and Redo
* Command moves logic from forms into separate classes, and thus reduces the complexity of forms
* The logic in a Command can easily be used in separate forms and applications

Technically, commands belongs to the presentation services. Commands are allowed to launch dialogs and message boxes, guiding the user through a flow.

=== Reports ===

Standrd reports are developed in Visual Studio as Microsoft Client Report Definitions (rdlc). These are shown in the applications with the <tt>ReportViewer</tt> component.

=== Help ===

The applications should have support for online help.

== Technical Environment ==

System Architecture

2010-05-21T06:51:09Z

Fkl: /* Projects */

== Architectural Goals and Quality ==

For Heureka, the two most important quality goals are modifiability and performance. The system should be flexible enough to allow maintenance and further development in a cost effective manner. At the same time performance should be good enough to allow simulation on large amounts of data. To a certain extent, these goals are contradictable.

In addition to this, testability is an important quality aspect. As many parts as possible should be possible to test automatically, e.g. with unit testing tools such as [http://www.nunit.org/ NUnit]. This sometimes means that sub functions must be made public so that they can be tested from external code. Over time, this goal has been proven more important than originally expected. This means that this goal has not always been met in the existing code, for instance many classes has a lot of dependencies on other classes making them harder to test.*

Other quality goals are less important:

* Security. There are no specific security requirements. The system will use security functions available in the database and operating system.
* Availability. The system is a single user application, so availability is not considered in the architecture.
* Portability. Portability is not required.

== Logical View ==

=== Forest model and Calculations ===
[[file:Forest_and_Calculations.png]]

The key entity in Heureka is the Treatment Unit, that represents a stand, i.e. an area restricted in space, with the same type of forest. A Treatment Unit is the smallest unit treatments are applied for. Each treatment unit contains one or more predictions units. A prediction unit represents a plot or a cell inside the treatment unit. Each prediction unit contains trees. Trees have [[Handling of tree states|different states]], identifying if the tree object represents a sapling, a tree, is dead and so forth. Each of these entities [[handle different time periods]].

Treatments are simulated in Heureka with different type of treatment models such as regeneration, fertilization, cleaning, thinning, and final felling.

Growth and yield models calculates tree related values such as volume, basal area growth, height, age, and bark thickness. With help of the growth models, a treatment unit can grow, i.e. the state in a future time period can be calculated.

[[Result models]] are used to calculate different types on results. Based on the state of a treatment unit in a given time period, different types of results can be calculated, such as cost and revenue of treatments, amount of biomass in the living forest, or amount of litter added to the ground. A result model may also produce a result based on the results in other result models (e.g. the recreation model uses input from the dead wood model).

Simulation models or frameworks, allows treatment programs to be calculated for a treatment unit. A simulation model utilizes the growth and yield models, the treatment models, and sometimes also result models, to simulate different alternatives for managing a treatment unit. When growth prognosis and treatments has been simulated for a number of periods, the treatment unit (together with its prediction units and their trees and saplings) contains information about the forest state in all periods that were included in the simulation. The results can be saved in a treatment program, which contains results for all periods with the desired result models. Currently, three simulation models are implemented in Heureka: the (strategic) [[Treatment Program Generator Design|Treatment Program Generator]], the [[Tactical Treatment Program Generator Design|Tactical Treatment Program Generator]], and the [[Regional Framework Design|Regional Framework]].

An optimization model is used to create a plan. A plan consists of a selection of treatment programs (one for each treatment unit in the plan), that gives the best result according to the optimization model. An optimization model is defined using the results from the result models. Any variable produced by a result model can be used in an optimization model. Optimization models differs from other models in Heureka, these are the only models that are defined by the user (all other models are programmed into the system).

Treatment units may be classified in forest domains. A user may define a forest domain, based on variables from the result models. The forest domain is then used to configure a simulation model.

=== Data Import ===

[[file:Data_Import.png]]

A <tt>TreatmentUnit</tt> can be created from a NFI plot. In this case, a<tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each NFI plot (if the NFI plot is splitted a <tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each part of the plot).

Similarly FMPP data can be imported into Heureka (not shown in figure).

Another option is to import a stand register. From <tt>StandObject</tt>s in the stand register, <tt>TreatmentUnit</tt>s can be simulated. In this case, trees or saplings are created for the <tt>TreatmentUnit</tt>, based on stand level variables in the <tt>StandObject</tt>. The simulation process is stochastic, meaning that the result will be slightly different each time if repeated several times for the same <tt>StandObject</tt>.

It is also possible to get data to Heureka by making a sample design, choosing <tt>StandObject</tt>s to be inventoried, and then to make a field inventory using [[Ivent]], to get real plot data and inventoried trees and from that data create <tt>TreatmentUnit</tt>s.

The last option to get data into Heureka is to manually enter data using [[StandWise]] (not shown in figure).

All forest data is stored in a relational database.

=== Projects ===

[[file:Projects.png]]

A <tt>Project</tt> contains <tt>ControlCategories</tt> and <tt>ForestDomains</tt>. Each <tt>ForestDomain</tt> refers to a <tt>ControlCategory</tt>, and each <tt>ControlCategory</tt> contains a number of <tt>[[Design of Control Tables|ControlTables]]</tt>, each of which contains user settings for a model or a group of related models in the system.

Also, a <tt>Project</tt> contains the <tt>TreatmentUnits</tt> that the user is working with (the <tt>TreatmentUnits</tt> are actually kept in an <tt>AnalysisArea</tt>, not shown in the figure).

A <tt>Project</tt> may also contain other items, such as optimization models (not shown in the figure).

The project information is saved as files in the file system.

== Design Principles ==

=== Layering ===

[[file:layering.png]]

The system is built with a layered architecture (see for example [[ISBN 0321154959|Bass et al: Software Architecture in Practice]]. The layering is based on the system logic, where each layer adds functionality from a lower layer.

The three layers are:

;Application Layer: Each application is a separate subsystem. An application connects the domain specific subsystems into the functionality provided by the application.
;Domain Layer: A large number of subsystems with different types of domain specific functionality. Each subsystem has its own logic, and in many cases also presentation and persistence services. By having the presentation in the domain layer, UI functionality can be reused between applications.
;Base Layer: General purpose support functions.

The purpose of the layering is to achieve modifiability by isolation of changes. Changes in a higher layer does not affect a lower layer at all.

The layering is not strict, meaning that a higher layer can access any lower layer.

A similar layering is proposed in IBM Rational Unified Process, and in Domain Driven Design. The advantage of layering by generality as opposed to layering by type (as proposed by Microsoft) is lower coupling and higher cohesion.

Inside a subsystem, layering by type, i.e. UI -> Logic -> DB should be done (if a subsystem has a presentation and/or persistence service). A subsystem should be able to use the logic of another subsystem without refering to the presentation or persistence service of that subsystem. The persistence service should be encapsulated inside the subsystem and not be used directly by other subsystems. The presentation service of a subsystem should be available for composition of UI.

''Unfortunately the subsystem layering has not always been used, in many cases several subsystems access the same tables in the database directly. Some subsystems are also poorly layered, e.g. with database code inside the UI, or UI code inside the logic.''

=== MVC ===

Linking between user interface and the domain model is done with the architectural pattern Model-View-Controller (Reenskaug 1979).

The model is a domain entity. When the entity is changed, it signals that with an event so that all views rendering the entity can update themselves. The event <tt>PropertyChanged</tt> is used when a property is changed, the interface <tt>IBindingList</tt> is used when a list or collection is changed. In some cases other events are also used, in <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> there are a few more EventArgs that can be used. That namespace also contains the class <tt>ExtendedBindingList</tt> which is recommended for collections that can be bound.

The view is any kind of graphical control, such as a TextBox, a DataGrid, a TreeView, or a Map. The view can show and change some parts of the entity.

The controller is the object that reacts on user inputs, typically event handlers in a form.

When developing with MVC it is important not to short-circuit the view and the controller when they are implemented in the same class. The event handler should only update the model, and not trigger changes in the view directly.

=== Dependency inversion ===

To reduce dependencies between classes and subsystems, should the subsystems that need a particular service define an interface for that service. For example, the <tt>Forest</tt> subsystem needs biomass to be calculated. To avoid a direct (and circular) dependency from <tt>Forest</tt> to <tt>Biomass</tt>, the <tt>Forest</tt> subsystem declares an interface, <tt>IBiomassService</tt>, and the <tt>Biomass</tt> subsystem implements that interface.

With dependency inversation, a new problem arises, how does an object locate the needed services? There are two common approaches to solving this problem: either Dependency Injection is used, or a Service Locator is used. For Heureka, the latter approach has been used.

The subsystem <tt>Slu.Heureka.BaseLayer.Services</tt> implements a service locator. Key classes in interfaces in that subsystem are:

;IService:Interface that must be implemented by all services
;Service<T>:Generic class for accessing a service
;ServiceAttribute:Attribute that should be set on all services that should be auto loaded
;ServiceBase:Base class for implementing a service
;ServiceManager:The service locator

The <tt>ServiceManager</tt> is a Singleton. It supports auto loading of services (all services marked with the service attribute will be loaded at application startup) as well as explicit loading of services (very useful in unit tests).

The <tt>Services</tt> subsystem was introduced relatively late in the project but has proven to be very flexible and useful. In future development, it is recommended to use it more frequently to reduce dependencies in the system. The recommended approach is that when:

* A class needs to instantiate other classes (except .Net classes), a FactoryService should be implemented
* A class needs to use another subsystem, an interface to that subsystem should be implemented

Static classes and singletons should never be used, with the <tt>ServiceManager</tt> as the single exception to this rule.

=== Persisting Data ===

The system uses both the file system and RDBMS:s (SQL Server) to store data.

* Forest data (stand registers, inventory data, GIS data, treatment units etc) are stored in a RDBMS, the "ForestDb"
* Calculated results and optimization results (plans) are stored in another RDBMS, the "ResultDb"
* Project information and templates are stored in the file system (typically in the user's document folder)
* Application configuration is stored in the file system (typically in the user's application data folder)

Storgate to files are mainly done via serialization. However, a major drawback with serialization is that versioning can be a problem. Also, performance can be an issue. The subsystem <tt>Slu.Heureka.BaseLayer.SerializationManagement</tt> provides helper classes to resolve some of these issues. The classes <tt>SerializationReader</tt> and <tt>SerializationWriter</tt> improves performance drastically. A recommended practice is to always serialize a version number first. By doing this, deserialization of different versions can easily be implemented. A different problem is when a class changes its name or becomes obsolete. A solution for that problem has not been implemented in the Heureka system, but it should be possible to do it using the <tt>[[http://msdn.microsoft.com/en-US/library/system.runtime.serialization.serializationbinder|SerializationBinder]]</tt> class in the .Net framework.

For simple configuration data, the class <tt>ConfigurationStore</tt> should be used.

For control tables, a helper class that serializes control tables has been developed. Thus it is not necessary to implement serialization for control tables.

For interaction with RDBMS the following techniques are used:
;Data readers: For fast loading of objects, mainly used for forest data
;Typed data sets: Used when the user is updating data
;Custom OR-mappning: Used for the result database

=== Error Handling ===

When an error is discovered an exception is thrown. Built-in exceptions can be used if appropriate, such as <tt>ArgumentException</tt>, <tt>ArgumentNullException</tt>, and <tt>InvalidOperationException</tt>. In other cases Heureka specific exceptions, inheriting from <tt>ApplicationException</tt>, are used

Code that depends on exceptions in the normal flow should be avoided. For instance, if a string should be checked for a valid number it is better to use
<tt>int.TryParse()</tt> than <tt>int.Parse()</tt> as the latter throws an exception of the string not is numeric. When designing classes, consider implementing similar methods allowing clients to determine beforehand if an operation is valid or not.

Exceptions should only be caught if they are to be handled, and only those exceptions that are relevant should be caught. Do not just catch and re-throw exceptions. This leads to poor performance and also destroys the call stack of the exception.

In the user interface there must be an exception handler for all code that might throw exceptions. That code should show an error message to the user if an exception is caught. Use <tt>Slu.Heureka.BaseLayer.HeurekaForms.ErrorDialog</tt> to show error messages.

The exception message should be brief. If a longer description is needed, set the <tt>HelpLink</tt> for the exception.

=== Kommandon ===

The Command design pattern is used to encapsulate actions that the user performs into separate objects. There are several benefits with this simple pattern, so it should be used frequently:

* Command makes it possible to implement Undo and Redo
* Command moves logic from forms into separate classes, and thus reduces the complexity of forms
* The logic in a Command can easily be used in separate forms and applications

Technically, commands belongs to the presentation services. Commands are allowed to launch dialogs and message boxes, guiding the user through a flow.

=== Reports ===

Standrd reports are developed in Visual Studio as Microsoft Client Report Definitions (rdlc). These are shown in the applications with the <tt>ReportViewer</tt> component.

=== Help ===

The applications should have support for online help.

== Technical Environment ==

Regional Framework Design

2010-05-20T16:21:42Z

Fkl: /* Implementation */

== Overview ==

The Regional Framework performs the following steps:

# [[#Years to start period|Years to start period]] are calculated
# All treatment units are loaded and [[#Initialization of treatment units|initialized]]
# Treatment units are set aside for [[#Handling of nature conservation|nature conservation]]
# Total area of all treatment units is calculated
# Treatment units are allocated to forest domains and then to control categories
# [[#Initialization of treatment units|Treatment units are initialized]] again
# For each period:
## For each control category:
### Growth to next period is performed
### Restrictions are updated
### Treatments are executed
## Treatment units are allocated to new forest domains
# Results are saved

== Years to start period ==

Number of years to start period is determined by the reference year and the start year given by the user. Start year cannot occur before reference year. If start year and reference year are the same, simulation will be started directly, and the results and settings for the first period will be for the reference year period. If reference year occurs after start year, two extra periods will be added to the simulation, and settings for period 1 and 2 will be used for those periods, while setting for period 3 will be for the reference year period. Similarly two extra periods will be added to the results.

{| border="1"
|-
|Reference Year||Start Year||Period 0||Period 1||Period 2||Period 3
|-
|2006||2010||2006||2008||2010||2015
|-
|2010||2010||2010||2015||2020||2030
|}
== Initialization of treatment units ==

Initialization of treatment units is done twice. The first time the treatment unit is initialized with age, volume, growth, and height for all trees using the settings of the default control category, as these values might be required when assigning treatment units to forest domains.

The second time each treatment unit is assigned to a forest domain. Age, volume, growth, and height is assigned again (since another control category might be used this time), and growth to the start period is performed. Empty treatment units are also regenerated in this step.

== Handling of nature conservation ==

Treatment units are set aside for nature conservation at start of the simulation. Treatment units that has been set aside are included in the normal forest domain handling and treatment handling, but they are never prioritized for treatments.

== Execution of treatments ==

Execution of treatments follow a simple pattern:

* Execution of treatments is done for a domain at a time
* There is a treatment planner for each type of treatment that can be performed
* Each treatment planner evaluates all treatment units in the domain, checks if each treatment unit can be treated by the treatment and sets a priority for it
* Each treatment planner executes treatments for the priorized treatment units until the desired goal for the treatment as set in the domain has been reached

Treatments are executed in the following order:

# Cleaning
# Final felling
# Fertilization
# Regeneration
# Thinning
# Intensive fertilization

Several treatments in the same period is not allowed. This means if several treatments are possible for a treatment unit, the treatment with the highest priority is most likely to be performed.

== Forest Domains ==

=== How it should work ===
A <tt>ForestDomain</tt> is a classification of treatment units. Each forest domain has two properties that are of interest for the regional framework:

;ChangeForestDomainAllowed:Can treatment units assigned to the domain be moved to other domains
;ChangeMaturityClass:At which maturity class can the change be done

A <tt>ControlCategory</tt> specifies how treatments are applied, e.g. a kind of management system. Each control category has the following property of interest here:

;TargetArea: Percentage of the total area being analyzed that should be allocated to the control category

Each <tt>ForestDomain</tt> is connected to one or more <tt>ControlCategories</tt>. The same <tt>ControlCategory</tt> may be connected to more than one domain.

In the regional framework, it is evaluated for each period which treatment units belongs to which control category.

For example:

Say that there are three control categories:

* Intensive management (10%)
* Continous management (20%)
* Even Aged Management (100%)

And three forest domains, assigned to categories:

;Oak Forest: Continous Management , Even Aged Management
;Spruce Forest: Intensive Management, Even Aged Management
;Other Forest: Intensive Management, Continous Management, Even Aged Management

The regional framework will do as follows:

# If possible, allocated oak forest to continous management
# If the area of the oak forest is more than 10%, use even aged management for oak forest
# Similarly try to assign spruce forest to intensive management
# For other forest, use intensive management if possible (there was not enough spruce forest), if not try with continous management, if that not works even aged management will have to do

=== Implementation ===

# Total area of the analysis area is calculated
# For each period:
## If first period:
### All treatment units are added to a list of not assigned treatment units
## If not first period:
### Treatment units that are in a forest domain where change of forest domain is allowed, and has the maturity class of the forest domain, are added to a list of not assigned treatment units
## Remove all treatment units set aside from nature conservation from the list of not assigned treatment units, assign these to the default control category of their forest domain
## For each forest domain:
### For each control category in the domain:
#### While the assigned area of the control category is less than the target area of the control category, and there are available treatment units:
##### Pick a treatment unit with matching forest domain from the list of not assigned treatment units
##### Add the treatment unit to the control category
##### Increase the assigned area of the control category
## For each treatment units that not yet has been assigned:
### Add it to the default control category of its forest domain

Regional Framework Design

2010-05-20T16:20:10Z

Fkl: /* Implementation */

== Overview ==

The Regional Framework performs the following steps:

# [[#Years to start period|Years to start period]] are calculated
# All treatment units are loaded and [[#Initialization of treatment units|initialized]]
# Treatment units are set aside for [[#Handling of nature conservation|nature conservation]]
# Total area of all treatment units is calculated
# Treatment units are allocated to forest domains and then to control categories
# [[#Initialization of treatment units|Treatment units are initialized]] again
# For each period:
## For each control category:
### Growth to next period is performed
### Restrictions are updated
### Treatments are executed
## Treatment units are allocated to new forest domains
# Results are saved

== Years to start period ==

Number of years to start period is determined by the reference year and the start year given by the user. Start year cannot occur before reference year. If start year and reference year are the same, simulation will be started directly, and the results and settings for the first period will be for the reference year period. If reference year occurs after start year, two extra periods will be added to the simulation, and settings for period 1 and 2 will be used for those periods, while setting for period 3 will be for the reference year period. Similarly two extra periods will be added to the results.

{| border="1"
|-
|Reference Year||Start Year||Period 0||Period 1||Period 2||Period 3
|-
|2006||2010||2006||2008||2010||2015
|-
|2010||2010||2010||2015||2020||2030
|}
== Initialization of treatment units ==

Initialization of treatment units is done twice. The first time the treatment unit is initialized with age, volume, growth, and height for all trees using the settings of the default control category, as these values might be required when assigning treatment units to forest domains.

The second time each treatment unit is assigned to a forest domain. Age, volume, growth, and height is assigned again (since another control category might be used this time), and growth to the start period is performed. Empty treatment units are also regenerated in this step.

== Handling of nature conservation ==

Treatment units are set aside for nature conservation at start of the simulation. Treatment units that has been set aside are included in the normal forest domain handling and treatment handling, but they are never prioritized for treatments.

== Execution of treatments ==

Execution of treatments follow a simple pattern:

* Execution of treatments is done for a domain at a time
* There is a treatment planner for each type of treatment that can be performed
* Each treatment planner evaluates all treatment units in the domain, checks if each treatment unit can be treated by the treatment and sets a priority for it
* Each treatment planner executes treatments for the priorized treatment units until the desired goal for the treatment as set in the domain has been reached

Treatments are executed in the following order:

# Cleaning
# Final felling
# Fertilization
# Regeneration
# Thinning
# Intensive fertilization

Several treatments in the same period is not allowed. This means if several treatments are possible for a treatment unit, the treatment with the highest priority is most likely to be performed.

== Forest Domains ==

=== How it should work ===
A <tt>ForestDomain</tt> is a classification of treatment units. Each forest domain has two properties that are of interest for the regional framework:

;ChangeForestDomainAllowed:Can treatment units assigned to the domain be moved to other domains
;ChangeMaturityClass:At which maturity class can the change be done

A <tt>ControlCategory</tt> specifies how treatments are applied, e.g. a kind of management system. Each control category has the following property of interest here:

;TargetArea: Percentage of the total area being analyzed that should be allocated to the control category

Each <tt>ForestDomain</tt> is connected to one or more <tt>ControlCategories</tt>. The same <tt>ControlCategory</tt> may be connected to more than one domain.

In the regional framework, it is evaluated for each period which treatment units belongs to which control category.

For example:

Say that there are three control categories:

* Intensive management (10%)
* Continous management (20%)
* Even Aged Management (100%)

And three forest domains, assigned to categories:

;Oak Forest: Continous Management , Even Aged Management
;Spruce Forest: Intensive Management, Even Aged Management
;Other Forest: Intensive Management, Continous Management, Even Aged Management

The regional framework will do as follows:

# If possible, allocated oak forest to continous management
# If the area of the oak forest is more than 10%, use even aged management for oak forest
# Similarly try to assign spruce forest to intensive management
# For other forest, use intensive management if possible (there was not enough spruce forest), if not try with continous management, if that not works even aged management will have to do

=== Implementation ===

# Total area of the analysis area is calculated
# For each period:
## If first period:
### All treatment units are added to a list of not assigned treatment units
## If not first period:
### Treatment units that are in a forest domain where change of forest domain is allowed, and has the maturity class of the forest domain,
## Remove all treatment units set aside from nature conservation from the list of not assigned treatment units
## For each forest domain:
### For each control category in the domain:
#### While the assigned area of the control category is less than the target area of the control category, and there are available treatment units:
##### Pick a treatment unit with matching forest domain from the list of not assigned treatment units
##### Add the treatment unit to the control category
##### Increase the assigned area of the control category
## For each treatment units that not yet has been assigned:
### Add it to the default control category of its forest domain

Regional Framework Design

2010-05-20T16:07:14Z

Fkl: /* Forest Domains */

Regional Framework Design

2010-05-20T14:31:47Z

Fkl: /* Overview */

Regional Framework Design

2010-05-20T14:31:08Z

Fkl: /* Forest Domains */

Regional Framework Design

2010-05-20T14:18:20Z

Fkl:

System Architecture

2010-05-20T12:51:12Z

Fkl: /* Forest model and Calculations */

== Architectural Goals and Quality ==

For Heureka, the two most important quality goals are modifiability and performance. The system should be flexible enough to allow maintenance and further development in a cost effective manner. At the same time performance should be good enough to allow simulation on large amounts of data. To a certain extent, these goals are contradictable.

In addition to this, testability is an important quality aspect. As many parts as possible should be possible to test automatically, e.g. with unit testing tools such as [http://www.nunit.org/ NUnit]. This sometimes means that sub functions must be made public so that they can be tested from external code. Over time, this goal has been proven more important than originally expected. This means that this goal has not always been met in the existing code, for instance many classes has a lot of dependencies on other classes making them harder to test.*

Other quality goals are less important:

* Security. There are no specific security requirements. The system will use security functions available in the database and operating system.
* Availability. The system is a single user application, so availability is not considered in the architecture.
* Portability. Portability is not required.

== Logical View ==

=== Forest model and Calculations ===
[[file:Forest_and_Calculations.png]]

The key entity in Heureka is the Treatment Unit, that represents a stand, i.e. an area restricted in space, with the same type of forest. A Treatment Unit is the smallest unit treatments are applied for. Each treatment unit contains one or more predictions units. A prediction unit represents a plot or a cell inside the treatment unit. Each prediction unit contains trees. Trees have [[Handling of tree states|different states]], identifying if the tree object represents a sapling, a tree, is dead and so forth. Each of these entities [[handle different time periods]].

Treatments are simulated in Heureka with different type of treatment models such as regeneration, fertilization, cleaning, thinning, and final felling.

Growth and yield models calculates tree related values such as volume, basal area growth, height, age, and bark thickness. With help of the growth models, a treatment unit can grow, i.e. the state in a future time period can be calculated.

[[Result models]] are used to calculate different types on results. Based on the state of a treatment unit in a given time period, different types of results can be calculated, such as cost and revenue of treatments, amount of biomass in the living forest, or amount of litter added to the ground. A result model may also produce a result based on the results in other result models (e.g. the recreation model uses input from the dead wood model).

Simulation models or frameworks, allows treatment programs to be calculated for a treatment unit. A simulation model utilizes the growth and yield models, the treatment models, and sometimes also result models, to simulate different alternatives for managing a treatment unit. When growth prognosis and treatments has been simulated for a number of periods, the treatment unit (together with its prediction units and their trees and saplings) contains information about the forest state in all periods that were included in the simulation. The results can be saved in a treatment program, which contains results for all periods with the desired result models. Currently, three simulation models are implemented in Heureka: the (strategic) [[Treatment Program Generator Design|Treatment Program Generator]], the [[Tactical Treatment Program Generator Design|Tactical Treatment Program Generator]], and the [[Regional Framework Design|Regional Framework]].

An optimization model is used to create a plan. A plan consists of a selection of treatment programs (one for each treatment unit in the plan), that gives the best result according to the optimization model. An optimization model is defined using the results from the result models. Any variable produced by a result model can be used in an optimization model. Optimization models differs from other models in Heureka, these are the only models that are defined by the user (all other models are programmed into the system).

Treatment units may be classified in forest domains. A user may define a forest domain, based on variables from the result models. The forest domain is then used to configure a simulation model.

=== Data Import ===

[[file:Data_Import.png]]

A <tt>TreatmentUnit</tt> can be created from a NFI plot. In this case, a<tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each NFI plot (if the NFI plot is splitted a <tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each part of the plot).

Similarly FMPP data can be imported into Heureka (not shown in figure).

Another option is to import a stand register. From <tt>StandObject</tt>s in the stand register, <tt>TreatmentUnit</tt>s can be simulated. In this case, trees or saplings are created for the <tt>TreatmentUnit</tt>, based on stand level variables in the <tt>StandObject</tt>. The simulation process is stochastic, meaning that the result will be slightly different each time if repeated several times for the same <tt>StandObject</tt>.

It is also possible to get data to Heureka by making a sample design, choosing <tt>StandObject</tt>s to be inventoried, and then to make a field inventory using [[Ivent]], to get real plot data and inventoried trees and from that data create <tt>TreatmentUnit</tt>s.

The last option to get data into Heureka is to manually enter data using [[StandWise]] (not shown in figure).

All forest data is stored in a relational database.

=== Projects ===

[[file:Projects.png]]

A <tt>Project</tt> contains <tt>ControlCategories</tt> and <tt>ForestDomains</tt>. Each <tt>ForestDomain</tt> refers to a <tt>ControlCategory</tt>, and each <tt>ControlCategory</tt> contains a number of <tt>ControlTables</tt>, each of which contains user settings for a model or a group of related models in the system.

Also, a <tt>Project</tt> contains the <tt>TreatmentUnits</tt> that the user is working with (the <tt>TreatmentUnits</tt> are actually kept in an <tt>AnalysisArea</tt>, not shown in the figure).

A <tt>Project</tt> may also contain other items, such as optimization models (not shown in the figure).

The project information is saved as files in the file system.

== Design Principles ==

=== Layering ===

[[file:layering.png]]

The system is built with a layered architecture (see for example [[ISBN 0321154959|Bass et al: Software Architecture in Practice]]. The layering is based on the system logic, where each layer adds functionality from a lower layer.

The three layers are:

;Application Layer: Each application is a separate subsystem. An application connects the domain specific subsystems into the functionality provided by the application.
;Domain Layer: A large number of subsystems with different types of domain specific functionality. Each subsystem has its own logic, and in many cases also presentation and persistence services. By having the presentation in the domain layer, UI functionality can be reused between applications.
;Base Layer: General purpose support functions.

The purpose of the layering is to achieve modifiability by isolation of changes. Changes in a higher layer does not affect a lower layer at all.

The layering is not strict, meaning that a higher layer can access any lower layer.

A similar layering is proposed in IBM Rational Unified Process, and in Domain Driven Design. The advantage of layering by generality as opposed to layering by type (as proposed by Microsoft) is lower coupling and higher cohesion.

Inside a subsystem, layering by type, i.e. UI -> Logic -> DB should be done (if a subsystem has a presentation and/or persistence service). A subsystem should be able to use the logic of another subsystem without refering to the presentation or persistence service of that subsystem. The persistence service should be encapsulated inside the subsystem and not be used directly by other subsystems. The presentation service of a subsystem should be available for composition of UI.

''Unfortunately the subsystem layering has not always been used, in many cases several subsystems access the same tables in the database directly. Some subsystems are also poorly layered, e.g. with database code inside the UI, or UI code inside the logic.''

=== MVC ===

Linking between user interface and the domain model is done with the architectural pattern Model-View-Controller (Reenskaug 1979).

The model is a domain entity. When the entity is changed, it signals that with an event so that all views rendering the entity can update themselves. The event <tt>PropertyChanged</tt> is used when a property is changed, the interface <tt>IBindingList</tt> is used when a list or collection is changed. In some cases other events are also used, in <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> there are a few more EventArgs that can be used. That namespace also contains the class <tt>ExtendedBindingList</tt> which is recommended for collections that can be bound.

The view is any kind of graphical control, such as a TextBox, a DataGrid, a TreeView, or a Map. The view can show and change some parts of the entity.

The controller is the object that reacts on user inputs, typically event handlers in a form.

When developing with MVC it is important not to short-circuit the view and the controller when they are implemented in the same class. The event handler should only update the model, and not trigger changes in the view directly.

=== Dependency inversion ===

To reduce dependencies between classes and subsystems, should the subsystems that need a particular service define an interface for that service. For example, the <tt>Forest</tt> subsystem needs biomass to be calculated. To avoid a direct (and circular) dependency from <tt>Forest</tt> to <tt>Biomass</tt>, the <tt>Forest</tt> subsystem declares an interface, <tt>IBiomassService</tt>, and the <tt>Biomass</tt> subsystem implements that interface.

With dependency inversation, a new problem arises, how does an object locate the needed services? There are two common approaches to solving this problem: either Dependency Injection is used, or a Service Locator is used. For Heureka, the latter approach has been used.

The subsystem <tt>Slu.Heureka.BaseLayer.Services</tt> implements a service locator. Key classes in interfaces in that subsystem are:

;IService:Interface that must be implemented by all services
;Service<T>:Generic class for accessing a service
;ServiceAttribute:Attribute that should be set on all services that should be auto loaded
;ServiceBase:Base class for implementing a service
;ServiceManager:The service locator

The <tt>ServiceManager</tt> is a Singleton. It supports auto loading of services (all services marked with the service attribute will be loaded at application startup) as well as explicit loading of services (very useful in unit tests).

The <tt>Services</tt> subsystem was introduced relatively late in the project but has proven to be very flexible and useful. In future development, it is recommended to use it more frequently to reduce dependencies in the system. The recommended approach is that when:

* A class needs to instantiate other classes (except .Net classes), a FactoryService should be implemented
* A class needs to use another subsystem, an interface to that subsystem should be implemented

Static classes and singletons should never be used, with the <tt>ServiceManager</tt> as the single exception to this rule.

=== Persisting Data ===

The system uses both the file system and RDBMS:s (SQL Server) to store data.

* Forest data (stand registers, inventory data, GIS data, treatment units etc) are stored in a RDBMS, the "ForestDb"
* Calculated results and optimization results (plans) are stored in another RDBMS, the "ResultDb"
* Project information and templates are stored in the file system (typically in the user's document folder)
* Application configuration is stored in the file system (typically in the user's application data folder)

Storgate to files are mainly done via serialization. However, a major drawback with serialization is that versioning can be a problem. Also, performance can be an issue. The subsystem <tt>Slu.Heureka.BaseLayer.SerializationManagement</tt> provides helper classes to resolve some of these issues. The classes <tt>SerializationReader</tt> and <tt>SerializationWriter</tt> improves performance drastically. A recommended practice is to always serialize a version number first. By doing this, deserialization of different versions can easily be implemented. A different problem is when a class changes its name or becomes obsolete. A solution for that problem has not been implemented in the Heureka system, but it should be possible to do it using the <tt>[[http://msdn.microsoft.com/en-US/library/system.runtime.serialization.serializationbinder|SerializationBinder]]</tt> class in the .Net framework.

For simple configuration data, the class <tt>ConfigurationStore</tt> should be used.

For control tables, a helper class that serializes control tables has been developed. Thus it is not necessary to implement serialization for control tables.

For interaction with RDBMS the following techniques are used:
;Data readers: For fast loading of objects, mainly used for forest data
;Typed data sets: Used when the user is updating data
;Custom OR-mappning: Used for the result database

=== Error Handling ===

When an error is discovered an exception is thrown. Built-in exceptions can be used if appropriate, such as <tt>ArgumentException</tt>, <tt>ArgumentNullException</tt>, and <tt>InvalidOperationException</tt>. In other cases Heureka specific exceptions, inheriting from <tt>ApplicationException</tt>, are used

Code that depends on exceptions in the normal flow should be avoided. For instance, if a string should be checked for a valid number it is better to use
<tt>int.TryParse()</tt> than <tt>int.Parse()</tt> as the latter throws an exception of the string not is numeric. When designing classes, consider implementing similar methods allowing clients to determine beforehand if an operation is valid or not.

Exceptions should only be caught if they are to be handled, and only those exceptions that are relevant should be caught. Do not just catch and re-throw exceptions. This leads to poor performance and also destroys the call stack of the exception.

In the user interface there must be an exception handler for all code that might throw exceptions. That code should show an error message to the user if an exception is caught. Use <tt>Slu.Heureka.BaseLayer.HeurekaForms.ErrorDialog</tt> to show error messages.

The exception message should be brief. If a longer description is needed, set the <tt>HelpLink</tt> for the exception.

=== Kommandon ===

The Command design pattern is used to encapsulate actions that the user performs into separate objects. There are several benefits with this simple pattern, so it should be used frequently:

* Command makes it possible to implement Undo and Redo
* Command moves logic from forms into separate classes, and thus reduces the complexity of forms
* The logic in a Command can easily be used in separate forms and applications

Technically, commands belongs to the presentation services. Commands are allowed to launch dialogs and message boxes, guiding the user through a flow.

=== Reports ===

Standrd reports are developed in Visual Studio as Microsoft Client Report Definitions (rdlc). These are shown in the applications with the <tt>ReportViewer</tt> component.

=== Help ===

The applications should have support for online help.

== Technical Environment ==

System Architecture

2010-05-20T12:49:32Z

Fkl: /* Forest model and Calculations */

== Architectural Goals and Quality ==

For Heureka, the two most important quality goals are modifiability and performance. The system should be flexible enough to allow maintenance and further development in a cost effective manner. At the same time performance should be good enough to allow simulation on large amounts of data. To a certain extent, these goals are contradictable.

In addition to this, testability is an important quality aspect. As many parts as possible should be possible to test automatically, e.g. with unit testing tools such as [http://www.nunit.org/ NUnit]. This sometimes means that sub functions must be made public so that they can be tested from external code. Over time, this goal has been proven more important than originally expected. This means that this goal has not always been met in the existing code, for instance many classes has a lot of dependencies on other classes making them harder to test.*

Other quality goals are less important:

* Security. There are no specific security requirements. The system will use security functions available in the database and operating system.
* Availability. The system is a single user application, so availability is not considered in the architecture.
* Portability. Portability is not required.

== Logical View ==

=== Forest model and Calculations ===
[[file:Forest_and_Calculations.png]]

The key entity in Heureka is the Treatment Unit, that represents a stand, i.e. an area restricted in space, with the same type of forest. A Treatment Unit is the smallest unit treatments are applied for. Each treatment unit contains one or more predictions units. A prediction unit represents a plot or a cell inside the treatment unit. Each prediction unit contains trees. Trees have [[Handling of tree states|different states]], identifying if the tree object represents a sapling, a tree, is dead and so forth. Each of these entities [[handle different time periods]].

Treatments are simulated in Heureka with different type of treatment models such as regeneration, fertilization, cleaning, thinning, and final felling.

Growth and yield models calculates tree related values such as volume, basal area growth, height, age, and bark thickness. With help of the growth models, a treatment unit can grow, i.e. the state in a future time period can be calculated.

[[Result models]] are used to calculate different types on results. Based on the state of a treatment unit in a given time period, different types of results can be calculated, such as cost and revenue of treatments, amount of biomass in the living forest, or amount of litter added to the ground. A result model may also produce a result based on the results in other result models (e.g. the recreation model uses input from the dead wood model).

Simulation models or frameworks, allows treatment programs to be calculated for a treatment unit. A simulation model utilizes the growth and yield models, the treatment models, and sometimes also result models, to simulate different alternatives for managing a treatment unit. When growth prognosis and treatments has been simulated for a number of periods, the treatment unit (together with its prediction units and their trees and saplings) contains information about the forest state in all periods that were included in the simulation. The results can be saved in a treatment program, which contains results for all periods with the desired result models. Currently, three simulation models are implemented in Heureka: the (strategic) [[Treatment Program Generator]], the [[Tactical Treatment Program Generator]], and the [[Regional Framework]].

An optimization model is used to create a plan. A plan consists of a selection of treatment programs (one for each treatment unit in the plan), that gives the best result according to the optimization model. An optimization model is defined using the results from the result models. Any variable produced by a result model can be used in an optimization model. Optimization models differs from other models in Heureka, these are the only models that are defined by the user (all other models are programmed into the system).

Treatment units may be classified in forest domains. A user may define a forest domain, based on variables from the result models. The forest domain is then used to configure a simulation model.

=== Data Import ===

[[file:Data_Import.png]]

A <tt>TreatmentUnit</tt> can be created from a NFI plot. In this case, a<tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each NFI plot (if the NFI plot is splitted a <tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each part of the plot).

Similarly FMPP data can be imported into Heureka (not shown in figure).

Another option is to import a stand register. From <tt>StandObject</tt>s in the stand register, <tt>TreatmentUnit</tt>s can be simulated. In this case, trees or saplings are created for the <tt>TreatmentUnit</tt>, based on stand level variables in the <tt>StandObject</tt>. The simulation process is stochastic, meaning that the result will be slightly different each time if repeated several times for the same <tt>StandObject</tt>.

It is also possible to get data to Heureka by making a sample design, choosing <tt>StandObject</tt>s to be inventoried, and then to make a field inventory using [[Ivent]], to get real plot data and inventoried trees and from that data create <tt>TreatmentUnit</tt>s.

The last option to get data into Heureka is to manually enter data using [[StandWise]] (not shown in figure).

All forest data is stored in a relational database.

=== Projects ===

[[file:Projects.png]]

A <tt>Project</tt> contains <tt>ControlCategories</tt> and <tt>ForestDomains</tt>. Each <tt>ForestDomain</tt> refers to a <tt>ControlCategory</tt>, and each <tt>ControlCategory</tt> contains a number of <tt>ControlTables</tt>, each of which contains user settings for a model or a group of related models in the system.

Also, a <tt>Project</tt> contains the <tt>TreatmentUnits</tt> that the user is working with (the <tt>TreatmentUnits</tt> are actually kept in an <tt>AnalysisArea</tt>, not shown in the figure).

A <tt>Project</tt> may also contain other items, such as optimization models (not shown in the figure).

The project information is saved as files in the file system.

== Design Principles ==

=== Layering ===

[[file:layering.png]]

The system is built with a layered architecture (see for example [[ISBN 0321154959|Bass et al: Software Architecture in Practice]]. The layering is based on the system logic, where each layer adds functionality from a lower layer.

The three layers are:

;Application Layer: Each application is a separate subsystem. An application connects the domain specific subsystems into the functionality provided by the application.
;Domain Layer: A large number of subsystems with different types of domain specific functionality. Each subsystem has its own logic, and in many cases also presentation and persistence services. By having the presentation in the domain layer, UI functionality can be reused between applications.
;Base Layer: General purpose support functions.

The purpose of the layering is to achieve modifiability by isolation of changes. Changes in a higher layer does not affect a lower layer at all.

The layering is not strict, meaning that a higher layer can access any lower layer.

A similar layering is proposed in IBM Rational Unified Process, and in Domain Driven Design. The advantage of layering by generality as opposed to layering by type (as proposed by Microsoft) is lower coupling and higher cohesion.

Inside a subsystem, layering by type, i.e. UI -> Logic -> DB should be done (if a subsystem has a presentation and/or persistence service). A subsystem should be able to use the logic of another subsystem without refering to the presentation or persistence service of that subsystem. The persistence service should be encapsulated inside the subsystem and not be used directly by other subsystems. The presentation service of a subsystem should be available for composition of UI.

''Unfortunately the subsystem layering has not always been used, in many cases several subsystems access the same tables in the database directly. Some subsystems are also poorly layered, e.g. with database code inside the UI, or UI code inside the logic.''

=== MVC ===

Linking between user interface and the domain model is done with the architectural pattern Model-View-Controller (Reenskaug 1979).

The model is a domain entity. When the entity is changed, it signals that with an event so that all views rendering the entity can update themselves. The event <tt>PropertyChanged</tt> is used when a property is changed, the interface <tt>IBindingList</tt> is used when a list or collection is changed. In some cases other events are also used, in <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> there are a few more EventArgs that can be used. That namespace also contains the class <tt>ExtendedBindingList</tt> which is recommended for collections that can be bound.

The view is any kind of graphical control, such as a TextBox, a DataGrid, a TreeView, or a Map. The view can show and change some parts of the entity.

The controller is the object that reacts on user inputs, typically event handlers in a form.

When developing with MVC it is important not to short-circuit the view and the controller when they are implemented in the same class. The event handler should only update the model, and not trigger changes in the view directly.

=== Dependency inversion ===

To reduce dependencies between classes and subsystems, should the subsystems that need a particular service define an interface for that service. For example, the <tt>Forest</tt> subsystem needs biomass to be calculated. To avoid a direct (and circular) dependency from <tt>Forest</tt> to <tt>Biomass</tt>, the <tt>Forest</tt> subsystem declares an interface, <tt>IBiomassService</tt>, and the <tt>Biomass</tt> subsystem implements that interface.

With dependency inversation, a new problem arises, how does an object locate the needed services? There are two common approaches to solving this problem: either Dependency Injection is used, or a Service Locator is used. For Heureka, the latter approach has been used.

The subsystem <tt>Slu.Heureka.BaseLayer.Services</tt> implements a service locator. Key classes in interfaces in that subsystem are:

;IService:Interface that must be implemented by all services
;Service<T>:Generic class for accessing a service
;ServiceAttribute:Attribute that should be set on all services that should be auto loaded
;ServiceBase:Base class for implementing a service
;ServiceManager:The service locator

The <tt>ServiceManager</tt> is a Singleton. It supports auto loading of services (all services marked with the service attribute will be loaded at application startup) as well as explicit loading of services (very useful in unit tests).

The <tt>Services</tt> subsystem was introduced relatively late in the project but has proven to be very flexible and useful. In future development, it is recommended to use it more frequently to reduce dependencies in the system. The recommended approach is that when:

* A class needs to instantiate other classes (except .Net classes), a FactoryService should be implemented
* A class needs to use another subsystem, an interface to that subsystem should be implemented

Static classes and singletons should never be used, with the <tt>ServiceManager</tt> as the single exception to this rule.

=== Persisting Data ===

The system uses both the file system and RDBMS:s (SQL Server) to store data.

* Forest data (stand registers, inventory data, GIS data, treatment units etc) are stored in a RDBMS, the "ForestDb"
* Calculated results and optimization results (plans) are stored in another RDBMS, the "ResultDb"
* Project information and templates are stored in the file system (typically in the user's document folder)
* Application configuration is stored in the file system (typically in the user's application data folder)

Storgate to files are mainly done via serialization. However, a major drawback with serialization is that versioning can be a problem. Also, performance can be an issue. The subsystem <tt>Slu.Heureka.BaseLayer.SerializationManagement</tt> provides helper classes to resolve some of these issues. The classes <tt>SerializationReader</tt> and <tt>SerializationWriter</tt> improves performance drastically. A recommended practice is to always serialize a version number first. By doing this, deserialization of different versions can easily be implemented. A different problem is when a class changes its name or becomes obsolete. A solution for that problem has not been implemented in the Heureka system, but it should be possible to do it using the <tt>[[http://msdn.microsoft.com/en-US/library/system.runtime.serialization.serializationbinder|SerializationBinder]]</tt> class in the .Net framework.

For simple configuration data, the class <tt>ConfigurationStore</tt> should be used.

For control tables, a helper class that serializes control tables has been developed. Thus it is not necessary to implement serialization for control tables.

For interaction with RDBMS the following techniques are used:
;Data readers: For fast loading of objects, mainly used for forest data
;Typed data sets: Used when the user is updating data
;Custom OR-mappning: Used for the result database

=== Error Handling ===

When an error is discovered an exception is thrown. Built-in exceptions can be used if appropriate, such as <tt>ArgumentException</tt>, <tt>ArgumentNullException</tt>, and <tt>InvalidOperationException</tt>. In other cases Heureka specific exceptions, inheriting from <tt>ApplicationException</tt>, are used

Code that depends on exceptions in the normal flow should be avoided. For instance, if a string should be checked for a valid number it is better to use
<tt>int.TryParse()</tt> than <tt>int.Parse()</tt> as the latter throws an exception of the string not is numeric. When designing classes, consider implementing similar methods allowing clients to determine beforehand if an operation is valid or not.

Exceptions should only be caught if they are to be handled, and only those exceptions that are relevant should be caught. Do not just catch and re-throw exceptions. This leads to poor performance and also destroys the call stack of the exception.

In the user interface there must be an exception handler for all code that might throw exceptions. That code should show an error message to the user if an exception is caught. Use <tt>Slu.Heureka.BaseLayer.HeurekaForms.ErrorDialog</tt> to show error messages.

The exception message should be brief. If a longer description is needed, set the <tt>HelpLink</tt> for the exception.

=== Kommandon ===

The Command design pattern is used to encapsulate actions that the user performs into separate objects. There are several benefits with this simple pattern, so it should be used frequently:

* Command makes it possible to implement Undo and Redo
* Command moves logic from forms into separate classes, and thus reduces the complexity of forms
* The logic in a Command can easily be used in separate forms and applications

Technically, commands belongs to the presentation services. Commands are allowed to launch dialogs and message boxes, guiding the user through a flow.

=== Reports ===

Standrd reports are developed in Visual Studio as Microsoft Client Report Definitions (rdlc). These are shown in the applications with the <tt>ReportViewer</tt> component.

=== Help ===

The applications should have support for online help.

== Technical Environment ==

System Architecture

2010-05-20T12:43:29Z

Fkl: /* Reports */

== Architectural Goals and Quality ==

For Heureka, the two most important quality goals are modifiability and performance. The system should be flexible enough to allow maintenance and further development in a cost effective manner. At the same time performance should be good enough to allow simulation on large amounts of data. To a certain extent, these goals are contradictable.

In addition to this, testability is an important quality aspect. As many parts as possible should be possible to test automatically, e.g. with unit testing tools such as [http://www.nunit.org/ NUnit]. This sometimes means that sub functions must be made public so that they can be tested from external code. Over time, this goal has been proven more important than originally expected. This means that this goal has not always been met in the existing code, for instance many classes has a lot of dependencies on other classes making them harder to test.*

Other quality goals are less important:

* Security. There are no specific security requirements. The system will use security functions available in the database and operating system.
* Availability. The system is a single user application, so availability is not considered in the architecture.
* Portability. Portability is not required.

== Logical View ==

=== Forest model and Calculations ===
[[file:Forest_and_Calculations.png]]

The key entity in Heureka is the Treatment Unit, that represents a stand, i.e. an area restricted in space, with the same type of forest. A Treatment Unit is the smallest unit treatments are applied for. Each treatment unit contains one or more predictions units. A prediction unit represents a plot or a cell inside the treatment unit. Each prediction unit contains trees. Trees have [[Handling of tree states|different states]], identifying if the tree object represents a sapling, a tree, is dead and so forth. Each of these entities [[handle different time periods]].

Treatments are simulated in Heureka with different type of treatment models such as regeneration, fertilization, cleaning, thinning, and final felling.

Growth and yield models calculates tree related values such as volume, basal area growth, height, age, and bark thickness. With help of the growth models, a treatment unit can grow, i.e. the state in a future time period can be calculated.

[[Result models]] are used to calculate different types on results. Based on the state of a treatment unit in a given time period, different types of results can be calculated, such as cost and revenue of treatments, amount of biomass in the living forest, or amount of litter added to the ground. A result model may also produce a result based on the results in other result models (e.g. the recreation model uses input from the dead wood model).

Simulation models or frameworks, allows treatment programs to be calculated for a treatment unit. A simulation model utilizes the growth and yield models, the treatment models, and sometimes also result models, to simulate different alternatives for managing a treatment unit. When growth prognosis and treatments has been simulated for a number of periods, the treatment unit (together with its prediction units and their trees and saplings) contains information about the forest state in all periods that were included in the simulation. The results can be saved in a treatment program, which contains results for all periods with the desired result models.

An optimization model is used to create a plan. A plan consists of a selection of treatment programs (one for each treatment unit in the plan), that gives the best result according to the optimization model. An optimization model is defined using the results from the result models. Any variable produced by a result model can be used in an optimization model. Optimization models differs from other models in Heureka, these are the only models that are defined by the user (all other models are programmed into the system).

Treatment units may be classified in forest domains. A user may define a forest domain, based on variables from the result models. The forest domain is then used to configure a simulation model.

=== Data Import ===

[[file:Data_Import.png]]

A <tt>TreatmentUnit</tt> can be created from a NFI plot. In this case, a<tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each NFI plot (if the NFI plot is splitted a <tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each part of the plot).

Similarly FMPP data can be imported into Heureka (not shown in figure).

Another option is to import a stand register. From <tt>StandObject</tt>s in the stand register, <tt>TreatmentUnit</tt>s can be simulated. In this case, trees or saplings are created for the <tt>TreatmentUnit</tt>, based on stand level variables in the <tt>StandObject</tt>. The simulation process is stochastic, meaning that the result will be slightly different each time if repeated several times for the same <tt>StandObject</tt>.

It is also possible to get data to Heureka by making a sample design, choosing <tt>StandObject</tt>s to be inventoried, and then to make a field inventory using [[Ivent]], to get real plot data and inventoried trees and from that data create <tt>TreatmentUnit</tt>s.

The last option to get data into Heureka is to manually enter data using [[StandWise]] (not shown in figure).

All forest data is stored in a relational database.

=== Projects ===

[[file:Projects.png]]

A <tt>Project</tt> contains <tt>ControlCategories</tt> and <tt>ForestDomains</tt>. Each <tt>ForestDomain</tt> refers to a <tt>ControlCategory</tt>, and each <tt>ControlCategory</tt> contains a number of <tt>ControlTables</tt>, each of which contains user settings for a model or a group of related models in the system.

Also, a <tt>Project</tt> contains the <tt>TreatmentUnits</tt> that the user is working with (the <tt>TreatmentUnits</tt> are actually kept in an <tt>AnalysisArea</tt>, not shown in the figure).

A <tt>Project</tt> may also contain other items, such as optimization models (not shown in the figure).

The project information is saved as files in the file system.

== Design Principles ==

=== Layering ===

[[file:layering.png]]

The system is built with a layered architecture (see for example [[ISBN 0321154959|Bass et al: Software Architecture in Practice]]. The layering is based on the system logic, where each layer adds functionality from a lower layer.

The three layers are:

;Application Layer: Each application is a separate subsystem. An application connects the domain specific subsystems into the functionality provided by the application.
;Domain Layer: A large number of subsystems with different types of domain specific functionality. Each subsystem has its own logic, and in many cases also presentation and persistence services. By having the presentation in the domain layer, UI functionality can be reused between applications.
;Base Layer: General purpose support functions.

The purpose of the layering is to achieve modifiability by isolation of changes. Changes in a higher layer does not affect a lower layer at all.

The layering is not strict, meaning that a higher layer can access any lower layer.

A similar layering is proposed in IBM Rational Unified Process, and in Domain Driven Design. The advantage of layering by generality as opposed to layering by type (as proposed by Microsoft) is lower coupling and higher cohesion.

Inside a subsystem, layering by type, i.e. UI -> Logic -> DB should be done (if a subsystem has a presentation and/or persistence service). A subsystem should be able to use the logic of another subsystem without refering to the presentation or persistence service of that subsystem. The persistence service should be encapsulated inside the subsystem and not be used directly by other subsystems. The presentation service of a subsystem should be available for composition of UI.

''Unfortunately the subsystem layering has not always been used, in many cases several subsystems access the same tables in the database directly. Some subsystems are also poorly layered, e.g. with database code inside the UI, or UI code inside the logic.''

=== MVC ===

Linking between user interface and the domain model is done with the architectural pattern Model-View-Controller (Reenskaug 1979).

The model is a domain entity. When the entity is changed, it signals that with an event so that all views rendering the entity can update themselves. The event <tt>PropertyChanged</tt> is used when a property is changed, the interface <tt>IBindingList</tt> is used when a list or collection is changed. In some cases other events are also used, in <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> there are a few more EventArgs that can be used. That namespace also contains the class <tt>ExtendedBindingList</tt> which is recommended for collections that can be bound.

The view is any kind of graphical control, such as a TextBox, a DataGrid, a TreeView, or a Map. The view can show and change some parts of the entity.

The controller is the object that reacts on user inputs, typically event handlers in a form.

When developing with MVC it is important not to short-circuit the view and the controller when they are implemented in the same class. The event handler should only update the model, and not trigger changes in the view directly.

=== Dependency inversion ===

To reduce dependencies between classes and subsystems, should the subsystems that need a particular service define an interface for that service. For example, the <tt>Forest</tt> subsystem needs biomass to be calculated. To avoid a direct (and circular) dependency from <tt>Forest</tt> to <tt>Biomass</tt>, the <tt>Forest</tt> subsystem declares an interface, <tt>IBiomassService</tt>, and the <tt>Biomass</tt> subsystem implements that interface.

With dependency inversation, a new problem arises, how does an object locate the needed services? There are two common approaches to solving this problem: either Dependency Injection is used, or a Service Locator is used. For Heureka, the latter approach has been used.

The subsystem <tt>Slu.Heureka.BaseLayer.Services</tt> implements a service locator. Key classes in interfaces in that subsystem are:

;IService:Interface that must be implemented by all services
;Service<T>:Generic class for accessing a service
;ServiceAttribute:Attribute that should be set on all services that should be auto loaded
;ServiceBase:Base class for implementing a service
;ServiceManager:The service locator

The <tt>ServiceManager</tt> is a Singleton. It supports auto loading of services (all services marked with the service attribute will be loaded at application startup) as well as explicit loading of services (very useful in unit tests).

The <tt>Services</tt> subsystem was introduced relatively late in the project but has proven to be very flexible and useful. In future development, it is recommended to use it more frequently to reduce dependencies in the system. The recommended approach is that when:

* A class needs to instantiate other classes (except .Net classes), a FactoryService should be implemented
* A class needs to use another subsystem, an interface to that subsystem should be implemented

Static classes and singletons should never be used, with the <tt>ServiceManager</tt> as the single exception to this rule.

=== Persisting Data ===

The system uses both the file system and RDBMS:s (SQL Server) to store data.

* Forest data (stand registers, inventory data, GIS data, treatment units etc) are stored in a RDBMS, the "ForestDb"
* Calculated results and optimization results (plans) are stored in another RDBMS, the "ResultDb"
* Project information and templates are stored in the file system (typically in the user's document folder)
* Application configuration is stored in the file system (typically in the user's application data folder)

Storgate to files are mainly done via serialization. However, a major drawback with serialization is that versioning can be a problem. Also, performance can be an issue. The subsystem <tt>Slu.Heureka.BaseLayer.SerializationManagement</tt> provides helper classes to resolve some of these issues. The classes <tt>SerializationReader</tt> and <tt>SerializationWriter</tt> improves performance drastically. A recommended practice is to always serialize a version number first. By doing this, deserialization of different versions can easily be implemented. A different problem is when a class changes its name or becomes obsolete. A solution for that problem has not been implemented in the Heureka system, but it should be possible to do it using the <tt>[[http://msdn.microsoft.com/en-US/library/system.runtime.serialization.serializationbinder|SerializationBinder]]</tt> class in the .Net framework.

For simple configuration data, the class <tt>ConfigurationStore</tt> should be used.

For control tables, a helper class that serializes control tables has been developed. Thus it is not necessary to implement serialization for control tables.

For interaction with RDBMS the following techniques are used:
;Data readers: For fast loading of objects, mainly used for forest data
;Typed data sets: Used when the user is updating data
;Custom OR-mappning: Used for the result database

=== Error Handling ===

When an error is discovered an exception is thrown. Built-in exceptions can be used if appropriate, such as <tt>ArgumentException</tt>, <tt>ArgumentNullException</tt>, and <tt>InvalidOperationException</tt>. In other cases Heureka specific exceptions, inheriting from <tt>ApplicationException</tt>, are used

Code that depends on exceptions in the normal flow should be avoided. For instance, if a string should be checked for a valid number it is better to use
<tt>int.TryParse()</tt> than <tt>int.Parse()</tt> as the latter throws an exception of the string not is numeric. When designing classes, consider implementing similar methods allowing clients to determine beforehand if an operation is valid or not.

Exceptions should only be caught if they are to be handled, and only those exceptions that are relevant should be caught. Do not just catch and re-throw exceptions. This leads to poor performance and also destroys the call stack of the exception.

In the user interface there must be an exception handler for all code that might throw exceptions. That code should show an error message to the user if an exception is caught. Use <tt>Slu.Heureka.BaseLayer.HeurekaForms.ErrorDialog</tt> to show error messages.

The exception message should be brief. If a longer description is needed, set the <tt>HelpLink</tt> for the exception.

=== Kommandon ===

The Command design pattern is used to encapsulate actions that the user performs into separate objects. There are several benefits with this simple pattern, so it should be used frequently:

* Command makes it possible to implement Undo and Redo
* Command moves logic from forms into separate classes, and thus reduces the complexity of forms
* The logic in a Command can easily be used in separate forms and applications

Technically, commands belongs to the presentation services. Commands are allowed to launch dialogs and message boxes, guiding the user through a flow.

=== Reports ===

Standrd reports are developed in Visual Studio as Microsoft Client Report Definitions (rdlc). These are shown in the applications with the <tt>ReportViewer</tt> component.

=== Help ===

The applications should have support for online help.

== Technical Environment ==

System Architecture

2010-05-20T12:43:13Z

Fkl: /* Reports */

== Architectural Goals and Quality ==

For Heureka, the two most important quality goals are modifiability and performance. The system should be flexible enough to allow maintenance and further development in a cost effective manner. At the same time performance should be good enough to allow simulation on large amounts of data. To a certain extent, these goals are contradictable.

In addition to this, testability is an important quality aspect. As many parts as possible should be possible to test automatically, e.g. with unit testing tools such as [http://www.nunit.org/ NUnit]. This sometimes means that sub functions must be made public so that they can be tested from external code. Over time, this goal has been proven more important than originally expected. This means that this goal has not always been met in the existing code, for instance many classes has a lot of dependencies on other classes making them harder to test.*

Other quality goals are less important:

* Security. There are no specific security requirements. The system will use security functions available in the database and operating system.
* Availability. The system is a single user application, so availability is not considered in the architecture.
* Portability. Portability is not required.

== Logical View ==

=== Forest model and Calculations ===
[[file:Forest_and_Calculations.png]]

The key entity in Heureka is the Treatment Unit, that represents a stand, i.e. an area restricted in space, with the same type of forest. A Treatment Unit is the smallest unit treatments are applied for. Each treatment unit contains one or more predictions units. A prediction unit represents a plot or a cell inside the treatment unit. Each prediction unit contains trees. Trees have [[Handling of tree states|different states]], identifying if the tree object represents a sapling, a tree, is dead and so forth. Each of these entities [[handle different time periods]].

Treatments are simulated in Heureka with different type of treatment models such as regeneration, fertilization, cleaning, thinning, and final felling.

Growth and yield models calculates tree related values such as volume, basal area growth, height, age, and bark thickness. With help of the growth models, a treatment unit can grow, i.e. the state in a future time period can be calculated.

[[Result models]] are used to calculate different types on results. Based on the state of a treatment unit in a given time period, different types of results can be calculated, such as cost and revenue of treatments, amount of biomass in the living forest, or amount of litter added to the ground. A result model may also produce a result based on the results in other result models (e.g. the recreation model uses input from the dead wood model).

Simulation models or frameworks, allows treatment programs to be calculated for a treatment unit. A simulation model utilizes the growth and yield models, the treatment models, and sometimes also result models, to simulate different alternatives for managing a treatment unit. When growth prognosis and treatments has been simulated for a number of periods, the treatment unit (together with its prediction units and their trees and saplings) contains information about the forest state in all periods that were included in the simulation. The results can be saved in a treatment program, which contains results for all periods with the desired result models.

An optimization model is used to create a plan. A plan consists of a selection of treatment programs (one for each treatment unit in the plan), that gives the best result according to the optimization model. An optimization model is defined using the results from the result models. Any variable produced by a result model can be used in an optimization model. Optimization models differs from other models in Heureka, these are the only models that are defined by the user (all other models are programmed into the system).

Treatment units may be classified in forest domains. A user may define a forest domain, based on variables from the result models. The forest domain is then used to configure a simulation model.

=== Data Import ===

[[file:Data_Import.png]]

A <tt>TreatmentUnit</tt> can be created from a NFI plot. In this case, a<tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each NFI plot (if the NFI plot is splitted a <tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each part of the plot).

Similarly FMPP data can be imported into Heureka (not shown in figure).

Another option is to import a stand register. From <tt>StandObject</tt>s in the stand register, <tt>TreatmentUnit</tt>s can be simulated. In this case, trees or saplings are created for the <tt>TreatmentUnit</tt>, based on stand level variables in the <tt>StandObject</tt>. The simulation process is stochastic, meaning that the result will be slightly different each time if repeated several times for the same <tt>StandObject</tt>.

It is also possible to get data to Heureka by making a sample design, choosing <tt>StandObject</tt>s to be inventoried, and then to make a field inventory using [[Ivent]], to get real plot data and inventoried trees and from that data create <tt>TreatmentUnit</tt>s.

The last option to get data into Heureka is to manually enter data using [[StandWise]] (not shown in figure).

All forest data is stored in a relational database.

=== Projects ===

[[file:Projects.png]]

A <tt>Project</tt> contains <tt>ControlCategories</tt> and <tt>ForestDomains</tt>. Each <tt>ForestDomain</tt> refers to a <tt>ControlCategory</tt>, and each <tt>ControlCategory</tt> contains a number of <tt>ControlTables</tt>, each of which contains user settings for a model or a group of related models in the system.

Also, a <tt>Project</tt> contains the <tt>TreatmentUnits</tt> that the user is working with (the <tt>TreatmentUnits</tt> are actually kept in an <tt>AnalysisArea</tt>, not shown in the figure).

A <tt>Project</tt> may also contain other items, such as optimization models (not shown in the figure).

The project information is saved as files in the file system.

== Design Principles ==

=== Layering ===

[[file:layering.png]]

The system is built with a layered architecture (see for example [[ISBN 0321154959|Bass et al: Software Architecture in Practice]]. The layering is based on the system logic, where each layer adds functionality from a lower layer.

The three layers are:

;Application Layer: Each application is a separate subsystem. An application connects the domain specific subsystems into the functionality provided by the application.
;Domain Layer: A large number of subsystems with different types of domain specific functionality. Each subsystem has its own logic, and in many cases also presentation and persistence services. By having the presentation in the domain layer, UI functionality can be reused between applications.
;Base Layer: General purpose support functions.

The purpose of the layering is to achieve modifiability by isolation of changes. Changes in a higher layer does not affect a lower layer at all.

The layering is not strict, meaning that a higher layer can access any lower layer.

A similar layering is proposed in IBM Rational Unified Process, and in Domain Driven Design. The advantage of layering by generality as opposed to layering by type (as proposed by Microsoft) is lower coupling and higher cohesion.

Inside a subsystem, layering by type, i.e. UI -> Logic -> DB should be done (if a subsystem has a presentation and/or persistence service). A subsystem should be able to use the logic of another subsystem without refering to the presentation or persistence service of that subsystem. The persistence service should be encapsulated inside the subsystem and not be used directly by other subsystems. The presentation service of a subsystem should be available for composition of UI.

''Unfortunately the subsystem layering has not always been used, in many cases several subsystems access the same tables in the database directly. Some subsystems are also poorly layered, e.g. with database code inside the UI, or UI code inside the logic.''

=== MVC ===

Linking between user interface and the domain model is done with the architectural pattern Model-View-Controller (Reenskaug 1979).

The model is a domain entity. When the entity is changed, it signals that with an event so that all views rendering the entity can update themselves. The event <tt>PropertyChanged</tt> is used when a property is changed, the interface <tt>IBindingList</tt> is used when a list or collection is changed. In some cases other events are also used, in <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> there are a few more EventArgs that can be used. That namespace also contains the class <tt>ExtendedBindingList</tt> which is recommended for collections that can be bound.

The view is any kind of graphical control, such as a TextBox, a DataGrid, a TreeView, or a Map. The view can show and change some parts of the entity.

The controller is the object that reacts on user inputs, typically event handlers in a form.

When developing with MVC it is important not to short-circuit the view and the controller when they are implemented in the same class. The event handler should only update the model, and not trigger changes in the view directly.

=== Dependency inversion ===

To reduce dependencies between classes and subsystems, should the subsystems that need a particular service define an interface for that service. For example, the <tt>Forest</tt> subsystem needs biomass to be calculated. To avoid a direct (and circular) dependency from <tt>Forest</tt> to <tt>Biomass</tt>, the <tt>Forest</tt> subsystem declares an interface, <tt>IBiomassService</tt>, and the <tt>Biomass</tt> subsystem implements that interface.

With dependency inversation, a new problem arises, how does an object locate the needed services? There are two common approaches to solving this problem: either Dependency Injection is used, or a Service Locator is used. For Heureka, the latter approach has been used.

The subsystem <tt>Slu.Heureka.BaseLayer.Services</tt> implements a service locator. Key classes in interfaces in that subsystem are:

;IService:Interface that must be implemented by all services
;Service<T>:Generic class for accessing a service
;ServiceAttribute:Attribute that should be set on all services that should be auto loaded
;ServiceBase:Base class for implementing a service
;ServiceManager:The service locator

The <tt>ServiceManager</tt> is a Singleton. It supports auto loading of services (all services marked with the service attribute will be loaded at application startup) as well as explicit loading of services (very useful in unit tests).

The <tt>Services</tt> subsystem was introduced relatively late in the project but has proven to be very flexible and useful. In future development, it is recommended to use it more frequently to reduce dependencies in the system. The recommended approach is that when:

* A class needs to instantiate other classes (except .Net classes), a FactoryService should be implemented
* A class needs to use another subsystem, an interface to that subsystem should be implemented

Static classes and singletons should never be used, with the <tt>ServiceManager</tt> as the single exception to this rule.

=== Persisting Data ===

The system uses both the file system and RDBMS:s (SQL Server) to store data.

* Forest data (stand registers, inventory data, GIS data, treatment units etc) are stored in a RDBMS, the "ForestDb"
* Calculated results and optimization results (plans) are stored in another RDBMS, the "ResultDb"
* Project information and templates are stored in the file system (typically in the user's document folder)
* Application configuration is stored in the file system (typically in the user's application data folder)

Storgate to files are mainly done via serialization. However, a major drawback with serialization is that versioning can be a problem. Also, performance can be an issue. The subsystem <tt>Slu.Heureka.BaseLayer.SerializationManagement</tt> provides helper classes to resolve some of these issues. The classes <tt>SerializationReader</tt> and <tt>SerializationWriter</tt> improves performance drastically. A recommended practice is to always serialize a version number first. By doing this, deserialization of different versions can easily be implemented. A different problem is when a class changes its name or becomes obsolete. A solution for that problem has not been implemented in the Heureka system, but it should be possible to do it using the <tt>[[http://msdn.microsoft.com/en-US/library/system.runtime.serialization.serializationbinder|SerializationBinder]]</tt> class in the .Net framework.

For simple configuration data, the class <tt>ConfigurationStore</tt> should be used.

For control tables, a helper class that serializes control tables has been developed. Thus it is not necessary to implement serialization for control tables.

For interaction with RDBMS the following techniques are used:
;Data readers: For fast loading of objects, mainly used for forest data
;Typed data sets: Used when the user is updating data
;Custom OR-mappning: Used for the result database

=== Error Handling ===

When an error is discovered an exception is thrown. Built-in exceptions can be used if appropriate, such as <tt>ArgumentException</tt>, <tt>ArgumentNullException</tt>, and <tt>InvalidOperationException</tt>. In other cases Heureka specific exceptions, inheriting from <tt>ApplicationException</tt>, are used

Code that depends on exceptions in the normal flow should be avoided. For instance, if a string should be checked for a valid number it is better to use
<tt>int.TryParse()</tt> than <tt>int.Parse()</tt> as the latter throws an exception of the string not is numeric. When designing classes, consider implementing similar methods allowing clients to determine beforehand if an operation is valid or not.

Exceptions should only be caught if they are to be handled, and only those exceptions that are relevant should be caught. Do not just catch and re-throw exceptions. This leads to poor performance and also destroys the call stack of the exception.

In the user interface there must be an exception handler for all code that might throw exceptions. That code should show an error message to the user if an exception is caught. Use <tt>Slu.Heureka.BaseLayer.HeurekaForms.ErrorDialog</tt> to show error messages.

The exception message should be brief. If a longer description is needed, set the <tt>HelpLink</tt> for the exception.

=== Kommandon ===

The Command design pattern is used to encapsulate actions that the user performs into separate objects. There are several benefits with this simple pattern, so it should be used frequently:

* Command makes it possible to implement Undo and Redo
* Command moves logic from forms into separate classes, and thus reduces the complexity of forms
* The logic in a Command can easily be used in separate forms and applications

Technically, commands belongs to the presentation services. Commands are allowed to launch dialogs and message boxes, guiding the user through a flow.

=== Reports ===

Standrd reports are developed in Visual Studio as Microsoft Client Report Definitions (rdlc). These are shown in the applications with the <tt>ReportViewer/</tt> component.

=== Help ===

The applications should have support for online help.

== Technical Environment ==

System Architecture

2010-05-20T12:42:49Z

Fkl: /* Kommandon */

== Architectural Goals and Quality ==

For Heureka, the two most important quality goals are modifiability and performance. The system should be flexible enough to allow maintenance and further development in a cost effective manner. At the same time performance should be good enough to allow simulation on large amounts of data. To a certain extent, these goals are contradictable.

In addition to this, testability is an important quality aspect. As many parts as possible should be possible to test automatically, e.g. with unit testing tools such as [http://www.nunit.org/ NUnit]. This sometimes means that sub functions must be made public so that they can be tested from external code. Over time, this goal has been proven more important than originally expected. This means that this goal has not always been met in the existing code, for instance many classes has a lot of dependencies on other classes making them harder to test.*

Other quality goals are less important:

* Security. There are no specific security requirements. The system will use security functions available in the database and operating system.
* Availability. The system is a single user application, so availability is not considered in the architecture.
* Portability. Portability is not required.

== Logical View ==

=== Forest model and Calculations ===
[[file:Forest_and_Calculations.png]]

The key entity in Heureka is the Treatment Unit, that represents a stand, i.e. an area restricted in space, with the same type of forest. A Treatment Unit is the smallest unit treatments are applied for. Each treatment unit contains one or more predictions units. A prediction unit represents a plot or a cell inside the treatment unit. Each prediction unit contains trees. Trees have [[Handling of tree states|different states]], identifying if the tree object represents a sapling, a tree, is dead and so forth. Each of these entities [[handle different time periods]].

Treatments are simulated in Heureka with different type of treatment models such as regeneration, fertilization, cleaning, thinning, and final felling.

Growth and yield models calculates tree related values such as volume, basal area growth, height, age, and bark thickness. With help of the growth models, a treatment unit can grow, i.e. the state in a future time period can be calculated.

[[Result models]] are used to calculate different types on results. Based on the state of a treatment unit in a given time period, different types of results can be calculated, such as cost and revenue of treatments, amount of biomass in the living forest, or amount of litter added to the ground. A result model may also produce a result based on the results in other result models (e.g. the recreation model uses input from the dead wood model).

Simulation models or frameworks, allows treatment programs to be calculated for a treatment unit. A simulation model utilizes the growth and yield models, the treatment models, and sometimes also result models, to simulate different alternatives for managing a treatment unit. When growth prognosis and treatments has been simulated for a number of periods, the treatment unit (together with its prediction units and their trees and saplings) contains information about the forest state in all periods that were included in the simulation. The results can be saved in a treatment program, which contains results for all periods with the desired result models.

An optimization model is used to create a plan. A plan consists of a selection of treatment programs (one for each treatment unit in the plan), that gives the best result according to the optimization model. An optimization model is defined using the results from the result models. Any variable produced by a result model can be used in an optimization model. Optimization models differs from other models in Heureka, these are the only models that are defined by the user (all other models are programmed into the system).

Treatment units may be classified in forest domains. A user may define a forest domain, based on variables from the result models. The forest domain is then used to configure a simulation model.

=== Data Import ===

[[file:Data_Import.png]]

A <tt>TreatmentUnit</tt> can be created from a NFI plot. In this case, a<tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each NFI plot (if the NFI plot is splitted a <tt>TreatmentUnit</tt> and a <tt>PredictionUnit</tt> is created for each part of the plot).

Similarly FMPP data can be imported into Heureka (not shown in figure).

Another option is to import a stand register. From <tt>StandObject</tt>s in the stand register, <tt>TreatmentUnit</tt>s can be simulated. In this case, trees or saplings are created for the <tt>TreatmentUnit</tt>, based on stand level variables in the <tt>StandObject</tt>. The simulation process is stochastic, meaning that the result will be slightly different each time if repeated several times for the same <tt>StandObject</tt>.

It is also possible to get data to Heureka by making a sample design, choosing <tt>StandObject</tt>s to be inventoried, and then to make a field inventory using [[Ivent]], to get real plot data and inventoried trees and from that data create <tt>TreatmentUnit</tt>s.

The last option to get data into Heureka is to manually enter data using [[StandWise]] (not shown in figure).

All forest data is stored in a relational database.

=== Projects ===

[[file:Projects.png]]

A <tt>Project</tt> contains <tt>ControlCategories</tt> and <tt>ForestDomains</tt>. Each <tt>ForestDomain</tt> refers to a <tt>ControlCategory</tt>, and each <tt>ControlCategory</tt> contains a number of <tt>ControlTables</tt>, each of which contains user settings for a model or a group of related models in the system.

Also, a <tt>Project</tt> contains the <tt>TreatmentUnits</tt> that the user is working with (the <tt>TreatmentUnits</tt> are actually kept in an <tt>AnalysisArea</tt>, not shown in the figure).

A <tt>Project</tt> may also contain other items, such as optimization models (not shown in the figure).

The project information is saved as files in the file system.

== Design Principles ==

=== Layering ===

[[file:layering.png]]

The system is built with a layered architecture (see for example [[ISBN 0321154959|Bass et al: Software Architecture in Practice]]. The layering is based on the system logic, where each layer adds functionality from a lower layer.

The three layers are:

;Application Layer: Each application is a separate subsystem. An application connects the domain specific subsystems into the functionality provided by the application.
;Domain Layer: A large number of subsystems with different types of domain specific functionality. Each subsystem has its own logic, and in many cases also presentation and persistence services. By having the presentation in the domain layer, UI functionality can be reused between applications.
;Base Layer: General purpose support functions.

The purpose of the layering is to achieve modifiability by isolation of changes. Changes in a higher layer does not affect a lower layer at all.

The layering is not strict, meaning that a higher layer can access any lower layer.

A similar layering is proposed in IBM Rational Unified Process, and in Domain Driven Design. The advantage of layering by generality as opposed to layering by type (as proposed by Microsoft) is lower coupling and higher cohesion.

Inside a subsystem, layering by type, i.e. UI -> Logic -> DB should be done (if a subsystem has a presentation and/or persistence service). A subsystem should be able to use the logic of another subsystem without refering to the presentation or persistence service of that subsystem. The persistence service should be encapsulated inside the subsystem and not be used directly by other subsystems. The presentation service of a subsystem should be available for composition of UI.

''Unfortunately the subsystem layering has not always been used, in many cases several subsystems access the same tables in the database directly. Some subsystems are also poorly layered, e.g. with database code inside the UI, or UI code inside the logic.''

=== MVC ===

Linking between user interface and the domain model is done with the architectural pattern Model-View-Controller (Reenskaug 1979).

The model is a domain entity. When the entity is changed, it signals that with an event so that all views rendering the entity can update themselves. The event <tt>PropertyChanged</tt> is used when a property is changed, the interface <tt>IBindingList</tt> is used when a list or collection is changed. In some cases other events are also used, in <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> there are a few more EventArgs that can be used. That namespace also contains the class <tt>ExtendedBindingList</tt> which is recommended for collections that can be bound.

The view is any kind of graphical control, such as a TextBox, a DataGrid, a TreeView, or a Map. The view can show and change some parts of the entity.

The controller is the object that reacts on user inputs, typically event handlers in a form.

When developing with MVC it is important not to short-circuit the view and the controller when they are implemented in the same class. The event handler should only update the model, and not trigger changes in the view directly.

=== Dependency inversion ===

To reduce dependencies between classes and subsystems, should the subsystems that need a particular service define an interface for that service. For example, the <tt>Forest</tt> subsystem needs biomass to be calculated. To avoid a direct (and circular) dependency from <tt>Forest</tt> to <tt>Biomass</tt>, the <tt>Forest</tt> subsystem declares an interface, <tt>IBiomassService</tt>, and the <tt>Biomass</tt> subsystem implements that interface.

With dependency inversation, a new problem arises, how does an object locate the needed services? There are two common approaches to solving this problem: either Dependency Injection is used, or a Service Locator is used. For Heureka, the latter approach has been used.

The subsystem <tt>Slu.Heureka.BaseLayer.Services</tt> implements a service locator. Key classes in interfaces in that subsystem are:

;IService:Interface that must be implemented by all services
;Service<T>:Generic class for accessing a service
;ServiceAttribute:Attribute that should be set on all services that should be auto loaded
;ServiceBase:Base class for implementing a service
;ServiceManager:The service locator

The <tt>ServiceManager</tt> is a Singleton. It supports auto loading of services (all services marked with the service attribute will be loaded at application startup) as well as explicit loading of services (very useful in unit tests).

The <tt>Services</tt> subsystem was introduced relatively late in the project but has proven to be very flexible and useful. In future development, it is recommended to use it more frequently to reduce dependencies in the system. The recommended approach is that when:

* A class needs to instantiate other classes (except .Net classes), a FactoryService should be implemented
* A class needs to use another subsystem, an interface to that subsystem should be implemented

Static classes and singletons should never be used, with the <tt>ServiceManager</tt> as the single exception to this rule.

=== Persisting Data ===

The system uses both the file system and RDBMS:s (SQL Server) to store data.

* Forest data (stand registers, inventory data, GIS data, treatment units etc) are stored in a RDBMS, the "ForestDb"
* Calculated results and optimization results (plans) are stored in another RDBMS, the "ResultDb"
* Project information and templates are stored in the file system (typically in the user's document folder)
* Application configuration is stored in the file system (typically in the user's application data folder)

Storgate to files are mainly done via serialization. However, a major drawback with serialization is that versioning can be a problem. Also, performance can be an issue. The subsystem <tt>Slu.Heureka.BaseLayer.SerializationManagement</tt> provides helper classes to resolve some of these issues. The classes <tt>SerializationReader</tt> and <tt>SerializationWriter</tt> improves performance drastically. A recommended practice is to always serialize a version number first. By doing this, deserialization of different versions can easily be implemented. A different problem is when a class changes its name or becomes obsolete. A solution for that problem has not been implemented in the Heureka system, but it should be possible to do it using the <tt>[[http://msdn.microsoft.com/en-US/library/system.runtime.serialization.serializationbinder|SerializationBinder]]</tt> class in the .Net framework.

For simple configuration data, the class <tt>ConfigurationStore</tt> should be used.

For control tables, a helper class that serializes control tables has been developed. Thus it is not necessary to implement serialization for control tables.

For interaction with RDBMS the following techniques are used:
;Data readers: For fast loading of objects, mainly used for forest data
;Typed data sets: Used when the user is updating data
;Custom OR-mappning: Used for the result database

=== Error Handling ===

When an error is discovered an exception is thrown. Built-in exceptions can be used if appropriate, such as <tt>ArgumentException</tt>, <tt>ArgumentNullException</tt>, and <tt>InvalidOperationException</tt>. In other cases Heureka specific exceptions, inheriting from <tt>ApplicationException</tt>, are used

Code that depends on exceptions in the normal flow should be avoided. For instance, if a string should be checked for a valid number it is better to use
<tt>int.TryParse()</tt> than <tt>int.Parse()</tt> as the latter throws an exception of the string not is numeric. When designing classes, consider implementing similar methods allowing clients to determine beforehand if an operation is valid or not.

Exceptions should only be caught if they are to be handled, and only those exceptions that are relevant should be caught. Do not just catch and re-throw exceptions. This leads to poor performance and also destroys the call stack of the exception.

In the user interface there must be an exception handler for all code that might throw exceptions. That code should show an error message to the user if an exception is caught. Use <tt>Slu.Heureka.BaseLayer.HeurekaForms.ErrorDialog</tt> to show error messages.

The exception message should be brief. If a longer description is needed, set the <tt>HelpLink</tt> for the exception.

=== Kommandon ===

The Command design pattern is used to encapsulate actions that the user performs into separate objects. There are several benefits with this simple pattern, so it should be used frequently:

* Command makes it possible to implement Undo and Redo
* Command moves logic from forms into separate classes, and thus reduces the complexity of forms
* The logic in a Command can easily be used in separate forms and applications

Technically, commands belongs to the presentation services. Commands are allowed to launch dialogs and message boxes, guiding the user through a flow.

=== Reports ===

Standrd reports are developed in Visual Studio as Microsoft Client Report Definitions (rdlc). These are shown in the applications with the <tt>ReportViewer/<tt> component.
=== Help ===

The applications should have support for online help.

== Technical Environment ==

System Architecture

2010-05-20T12:39:12Z

Fkl: /* Error Handling */

System Architecture

2010-05-20T12:31:28Z

Fkl: /* Help = */

System Architecture

2010-05-20T12:31:06Z

Fkl: /* Persisting Data = */

System Architecture

2010-05-20T09:35:48Z

Fkl: /* Dependency inversion */

System Architecture

2010-05-20T09:19:05Z

Fkl: /* Design Principles */

System Architecture

2010-05-20T07:11:31Z

Fkl: /* Layering */

System Architecture

2010-05-20T07:10:55Z

Fkl: /* Design Principles */

File:Layering.png

2010-05-20T06:47:32Z

Fkl:

System Architecture

2010-05-19T14:32:15Z

Fkl: /* = Projects */