Solving Your First Model¶
Welcome to solving your first Casal2 model. This tutorial assumes you have completed the Writing Your First Model tutorial and have the full input configuration file ready to modify.
This section covers solving the model we have specified. Casal2 can solve a model when you give it observations of what the population should look like and a list of parameters you will allow it to tweak in order to find the best fit. Similar to machine learning and artificial models, Casal2 uses standard operations research methodologies. In this tutorial, we’ll be using a basic gradient descent based solver.
By the end of this tutorial, you will have a model that Casal2 can solve.
Adding a second input configuration file¶
To keep the model definition easy to follow and work on, we’ll create a new file called estimation.csl2 in the same directory as the initial config.csl2. This file should be a basic text file with UTF-8 encoding. Line endings can be either Windows or Linux.
Now, we need to tell Casal2 that this file needs to be loaded when we run the model. Add the following line to the end of the config.csl file
!include "estimation.csl2".
The !include command allows you to include files within the model configuration at that exact location. This is useful for injecting data in to processes or observations where the data files are going to be automatically generated by external sources.
Note: When Casal2 loads the configuration files, it creates a huge singular in-memory file that contains the entire end-to-end definition of the model. This means that any !include commands are treated as just injecting the included file in that exact location of the parent file.
Specifying the minimiser¶
To solve the model, Casal2 requires us to tell it which solver we want to use. Casal2 has multiple solvers provided and does not select one by default for you. In Casal2, we refer to the different solvers as minimisers, because they will minimise the score on the objective (fitness/energy) function. Casal2 does not support maximisation.
For this model, we’re going to use a gradient based minimiser that does not use auto-differentiation. Casal2 supports multiple auto differentiation and non-auto differentiation based minimisers.
Add the following to the estimation.csl2 configuration file:
@minimiser gammadiff
type numerical_differences
iterations 1000
evaluations 4000
step_size 1e-7
tolerance 0.002
covariance true
We’re defining a minimiser with the label gammadiff of type numerical_differences. This is a standard non-auto differentiation gradient solver. We’re going to tell the model that the maximum number of model runs (iterations) is 1000 and evaluations 4000. These are sensible values for a small model, but your experience may vary on larger models and you may need to tweak these parameters. The step_size is used to determine how big of a jump the gradient descent should make and tolerance is how we define what a good solution is. covariance just defines that we want the minimiser to generate a covariance matrix for us. The covariance matrix is used in other model runs like markov chain monte carlo.
Observations of the population¶
In order to solve a model, Casal2 needs two things. The first which we will define here are observations. An @observation is a block that provides data about what the population should look like, or what was observed in the real world. The observed data is compared against the data generated by the model to calculate a score for the objective function. The less of a difference, the lower the objective function score, and the better the model proposed solution is.
Below, we define two observations, firstly an observation that looks at the proportions of the population at age; the second which looks at the abundance of the population. After the observations we define a catchability and selectivity that are required for the observation. More information about catchabilities can be found in the Casal2 user manual.
@observation CAA_year
type proportions_at_age
years 1998:2007
time_step step_one
categories *+
selectivities FishingSel FishingSel FishingSel FishingSel
min_age 1
max_age 35
plus_group True
table obs
1998 0.00000 0.00000 0.01382 0.03178 0.08416 0.03859 0.06588 0.08455 0.05462 0.07629 0.03963 0.07307 0.07535 0.07065 0.04555 0.06775 0.02900 0.02156 0.02174 0.01617 0.01136 0.01653 0.00646 0.01327 0.00948 0.00838 0.00959 0.00189 0.00414 0.00518 0.00000 0.00000 0.00058 0.00068 0.00230
1999 0.00000 0.00000 0.00086 0.00244 0.00448 0.03929 0.10549 0.11335 0.10784 0.09378 0.08746 0.10926 0.07183 0.07593 0.06111 0.03952 0.01718 0.01463 0.01281 0.00675 0.01591 0.00337 0.00814 0.00000 0.00051 0.00000 0.00391 0.00090 0.00138 0.00000 0.00000 0.00000 0.00000 0.00097 0.00090
2000 0.00000 0.00000 0.00000 0.00038 0.00415 0.00640 0.01976 0.07120 0.08222 0.07515 0.08747 0.05801 0.10737 0.08080 0.08953 0.09575 0.06014 0.06322 0.02783 0.02057 0.02040 0.00738 0.00755 0.00536 0.00203 0.00438 0.00000 0.00242 0.00000 0.00045 0.00000 0.00000 0.00008 0.00000 0.00000
2001 0.00000 0.00000 0.00000 0.00263 0.00359 0.03549 0.06726 0.09951 0.08653 0.04724 0.05347 0.04106 0.03943 0.05259 0.05045 0.06034 0.04739 0.04569 0.04445 0.03272 0.03233 0.02405 0.02646 0.02949 0.01345 0.01439 0.01173 0.01423 0.00349 0.00762 0.00389 0.00477 0.00227 0.00073 0.00126
2002 0.00000 0.00000 0.00900 0.00021 0.00123 0.00281 0.00261 0.01229 0.04306 0.03154 0.05151 0.06312 0.06697 0.09535 0.05892 0.07222 0.07539 0.04725 0.04795 0.02844 0.04516 0.04174 0.02689 0.03357 0.01697 0.03698 0.02749 0.01893 0.01425 0.01098 0.00479 0.00452 0.00247 0.00324 0.00215
2003 0.00000 0.00000 0.00000 0.00000 0.01084 0.00065 0.00066 0.00345 0.00887 0.00748 0.01729 0.03141 0.03914 0.05192 0.03888 0.05965 0.06126 0.05314 0.06201 0.06782 0.04751 0.05956 0.08472 0.05216 0.05335 0.05356 0.02539 0.02896 0.03062 0.01596 0.01437 0.00435 0.00976 0.00364 0.00162
2004 0.00000 0.00000 0.00300 0.00090 0.00223 0.01643 0.01650 0.01642 0.01872 0.03421 0.02997 0.04186 0.06070 0.08973 0.08342 0.06299 0.09181 0.05329 0.06977 0.03387 0.04415 0.04125 0.02680 0.02912 0.01770 0.03041 0.01543 0.01909 0.01444 0.01296 0.00816 0.00938 0.00159 0.00235 0.00135
2005 0.00000 0.00000 0.01722 0.00581 0.01441 0.01392 0.00835 0.01600 0.01843 0.01546 0.03134 0.03891 0.06389 0.07664 0.08851 0.07702 0.08848 0.07067 0.05496 0.06758 0.03703 0.03704 0.03964 0.01325 0.02080 0.00893 0.00995 0.02363 0.01265 0.00666 0.00688 0.00301 0.00223 0.01005 0.00065
2006 0.00000 0.00000 0.00032 0.00100 0.00434 0.00278 0.02499 0.02925 0.02513 0.02217 0.05581 0.06836 0.06633 0.10862 0.10592 0.10892 0.08496 0.06597 0.05506 0.02521 0.03047 0.02841 0.01219 0.01519 0.00872 0.01126 0.01303 0.00897 0.00162 0.00294 0.00305 0.00629 0.00269 0.00003 0.00000
2007 0.00000 0.00000 0.00032 0.00095 0.00970 0.01689 0.02675 0.03727 0.03764 0.03621 0.05253 0.04765 0.04557 0.06458 0.09280 0.08854 0.09656 0.07813 0.06467 0.03323 0.03816 0.02401 0.02313 0.02351 0.01130 0.01114 0.01160 0.00656 0.00294 0.00491 0.00302 0.00557 0.00097 0.00319 0.00000
end_table
table error_values
1998 343
1999 564
2000 651
2001 840
2002 598
2003 456
2004 538
2005 438
2006 817
2007 915
end_table
likelihood multinomial
delta 1e-11
time_step_proportion 1.0
@observation CPUE
type abundance
catchability CPUEq
time_step step_one
categories *+
selectivities FishingSel FishingSel FishingSel FishingSel
likelihood lognormal
time_step_proportion 1.0
years 1998:2007
table obs
1998 22.55065505 0.2
1999 57.30952381 0.2
2000 57.92066148 0.2
2001 33.52834377 0.2
2002 108.4380734 0.2
2003 72.84761934 0.2
2004 38.29753826 0.2
2005 75.84993311 0.2
2006 109.47353102 0.2
2007 85.7732931 0.2
end_table
@catchability CPUEq
type free
q 0.000153139
@selectivity FishingSel
type logistic
a50 8
ato95 3
Parameters for the model to solve¶
The second thing we need for Casal2 to solve a model is a list of parameters in the model that it can modify. These are free parameters or estimates. An estimate is a parameter that the model gets given a default value for (from it’s initial definition), and a range that it’s allowed to move the parameter while solving the model.
Below we are specifying four parameters across the model that we’d like to solve for. This is us telling Casal2 that “Hey, you can modify these parameters as long as you stay within the lower_bound and upper_bound to try and find the overall lowest score”. The type of @estimate just defines what and how the estimate value will be added to the objective function as a part of the objective score.
@estimate
parameter catchability[CPUEq].q
lower_bound 1e-10
upper_bound 1e-1
type uniform
@estimate recruitment.r0
parameter process[recruitment].R0
lower_bound 1e5
upper_bound 1e10
type uniform_log
@estimate
parameter selectivity[FishingSel].a50
lower_bound 1
upper_bound 20
type uniform
@estimate FishingSel.ato95
parameter selectivity[FishingSel].ato95
lower_bound 0.01
upper_bound 50
type uniform
Required reports¶
In theory, the model should now be specified in a way that allows Casal2 to solve it. Before we can run it, we need to specify an estimate_value report to print out the solves values of the estimates, and we’ll also add an objective_function report to print the final objective function. We don’t want to provide any additional parameters for the models, so these definitions are very simple.
Add the following to the configuration file:
@report obj
type objective_function
@report ev
type estimate_value
Checking and solving the model¶
The objective_function report is handy, in that it runs in pretty much every run mode of Casal2. Now that we have a completed model definition for a solvable model we’ll run it in a basic run mode to validate it, then solve it.
Run the following commands casal2 -r to run the model. ALl going well, you should see some output with a print out of the objective function and a total score of 4561.32. This is the score of the objective function based entirely on the configuration we have provided.
Let’s get Casal2 to solve the model, run the following commands casal2 -e. This will take a few seconds and produce a good amount of output. Once complete if you scroll up you should see the objective function with a total score of 3176.83. Below this will be the estimate values report, with the final values of the @estimate blocks from the solved solution.
That’s it. You’ve defined your first model and Casal2 has both run and solved it for you. From here you can expand this model to include markov chain monte carlo, projections, simulations and more. Check out the Casal2 user manual provided with your installation for more details.
Further to this, Casal2 has a large number of example models that are used as part of the build validation process. You can find these here. All of these models are executed as part of the Casal2 development process, so they’re continually updated and validated to ensure they run with Casal2. A more complex and complete example of the TwoSex model can be found here.
The final model input configuration files¶
The following is the complete input configuration file.
config.csl2¶
@model
start_year 1994
final_year 2008
min_age 1
max_age 50
age_plus t
initialisation_phases iphase1
time_steps step_one step_two
@categories
format stage.sex
names immature.male mature.male immature.female mature.female
@initialisation_phase iphase1
years 200
@time_step step_one
processes recruitment maturation mortality
@time_step step_two
processes ageing
@process recruitment
type recruitment_constant
r0 999999
categories stage=immature
proportions 0.5 0.5
age 1
@process maturation
type transition_category
from stage=immature
to stage=mature
proportions 1.0 1.0
selectivities maturation_sel maturation_sel
@process mortality
type mortality_constant_rate
categories *
m 0.065 0.065 0.065 0.065
relative_m_by_age One One One One
time_step_proportions 1.0
@process ageing
type ageing
categories *
@selectivity One
type constant
c 1
@selectivity maturation_sel
type logistic_producing
L 5
H 30
a50 8
ato95 3
@report partition
type partition
years 2008
time_step step_two
!include "estimation.csl2"
estimation.csl2¶
@minimiser gammadiff
type numerical_differences
iterations 1000
evaluations 4000
step_size 1e-7
tolerance 0.002
covariance true
@observation CAA_year
type proportions_at_age
years 1998:2007
time_step step_one
categories *+
selectivities FishingSel FishingSel FishingSel FishingSel
min_age 1
max_age 35
plus_group True
table obs
1998 0.00000 0.00000 0.01382 0.03178 0.08416 0.03859 0.06588 0.08455 0.05462 0.07629 0.03963 0.07307 0.07535 0.07065 0.04555 0.06775 0.02900 0.02156 0.02174 0.01617 0.01136 0.01653 0.00646 0.01327 0.00948 0.00838 0.00959 0.00189 0.00414 0.00518 0.00000 0.00000 0.00058 0.00068 0.00230
1999 0.00000 0.00000 0.00086 0.00244 0.00448 0.03929 0.10549 0.11335 0.10784 0.09378 0.08746 0.10926 0.07183 0.07593 0.06111 0.03952 0.01718 0.01463 0.01281 0.00675 0.01591 0.00337 0.00814 0.00000 0.00051 0.00000 0.00391 0.00090 0.00138 0.00000 0.00000 0.00000 0.00000 0.00097 0.00090
2000 0.00000 0.00000 0.00000 0.00038 0.00415 0.00640 0.01976 0.07120 0.08222 0.07515 0.08747 0.05801 0.10737 0.08080 0.08953 0.09575 0.06014 0.06322 0.02783 0.02057 0.02040 0.00738 0.00755 0.00536 0.00203 0.00438 0.00000 0.00242 0.00000 0.00045 0.00000 0.00000 0.00008 0.00000 0.00000
2001 0.00000 0.00000 0.00000 0.00263 0.00359 0.03549 0.06726 0.09951 0.08653 0.04724 0.05347 0.04106 0.03943 0.05259 0.05045 0.06034 0.04739 0.04569 0.04445 0.03272 0.03233 0.02405 0.02646 0.02949 0.01345 0.01439 0.01173 0.01423 0.00349 0.00762 0.00389 0.00477 0.00227 0.00073 0.00126
2002 0.00000 0.00000 0.00900 0.00021 0.00123 0.00281 0.00261 0.01229 0.04306 0.03154 0.05151 0.06312 0.06697 0.09535 0.05892 0.07222 0.07539 0.04725 0.04795 0.02844 0.04516 0.04174 0.02689 0.03357 0.01697 0.03698 0.02749 0.01893 0.01425 0.01098 0.00479 0.00452 0.00247 0.00324 0.00215
2003 0.00000 0.00000 0.00000 0.00000 0.01084 0.00065 0.00066 0.00345 0.00887 0.00748 0.01729 0.03141 0.03914 0.05192 0.03888 0.05965 0.06126 0.05314 0.06201 0.06782 0.04751 0.05956 0.08472 0.05216 0.05335 0.05356 0.02539 0.02896 0.03062 0.01596 0.01437 0.00435 0.00976 0.00364 0.00162
2004 0.00000 0.00000 0.00300 0.00090 0.00223 0.01643 0.01650 0.01642 0.01872 0.03421 0.02997 0.04186 0.06070 0.08973 0.08342 0.06299 0.09181 0.05329 0.06977 0.03387 0.04415 0.04125 0.02680 0.02912 0.01770 0.03041 0.01543 0.01909 0.01444 0.01296 0.00816 0.00938 0.00159 0.00235 0.00135
2005 0.00000 0.00000 0.01722 0.00581 0.01441 0.01392 0.00835 0.01600 0.01843 0.01546 0.03134 0.03891 0.06389 0.07664 0.08851 0.07702 0.08848 0.07067 0.05496 0.06758 0.03703 0.03704 0.03964 0.01325 0.02080 0.00893 0.00995 0.02363 0.01265 0.00666 0.00688 0.00301 0.00223 0.01005 0.00065
2006 0.00000 0.00000 0.00032 0.00100 0.00434 0.00278 0.02499 0.02925 0.02513 0.02217 0.05581 0.06836 0.06633 0.10862 0.10592 0.10892 0.08496 0.06597 0.05506 0.02521 0.03047 0.02841 0.01219 0.01519 0.00872 0.01126 0.01303 0.00897 0.00162 0.00294 0.00305 0.00629 0.00269 0.00003 0.00000
2007 0.00000 0.00000 0.00032 0.00095 0.00970 0.01689 0.02675 0.03727 0.03764 0.03621 0.05253 0.04765 0.04557 0.06458 0.09280 0.08854 0.09656 0.07813 0.06467 0.03323 0.03816 0.02401 0.02313 0.02351 0.01130 0.01114 0.01160 0.00656 0.00294 0.00491 0.00302 0.00557 0.00097 0.00319 0.00000
end_table
table error_values
1998 343
1999 564
2000 651
2001 840
2002 598
2003 456
2004 538
2005 438
2006 817
2007 915
end_table
likelihood multinomial
delta 1e-11
time_step_proportion 1.0
@observation CPUE
type abundance
catchability CPUEq
time_step step_one
categories *+
selectivities FishingSel FishingSel FishingSel FishingSel
likelihood lognormal
time_step_proportion 1.0
years 1998:2007
table obs
1998 22.55065505 0.2
1999 57.30952381 0.2
2000 57.92066148 0.2
2001 33.52834377 0.2
2002 108.4380734 0.2
2003 72.84761934 0.2
2004 38.29753826 0.2
2005 75.84993311 0.2
2006 109.47353102 0.2
2007 85.7732931 0.2
end_table
@catchability CPUEq
type free
q 0.000153139
@selectivity FishingSel
type logistic
a50 8
ato95 3
@estimate
parameter catchability[CPUEq].q
lower_bound 1e-10
upper_bound 1e-1
type uniform
@estimate recruitment.r0
parameter process[recruitment].R0
lower_bound 1e5
upper_bound 1e10
type uniform_log
@estimate
parameter selectivity[FishingSel].a50
lower_bound 1
upper_bound 20
type uniform
@estimate FishingSel.ato95
parameter selectivity[FishingSel].ato95
lower_bound 0.01
upper_bound 50
type uniform
@report obj
type objective_function
@report ev
type estimate_value