1 of 64

Training: Calibrating Atlantis using calibrar

A Puget Sound example

Alaia Morell

October 2025

atlantis2ls

2 of 64

Ressources

On github:
Calibrar package

https://github.com/roliveros-ramos/calibrar

- Package that connects Atlantis and calibrar:

https://github.com/alaiam/atlantis2ls

- AMPS calibration without fisheries:

https://github.com/alaiam/Atlantis_Calibration

Documentation and papers:
Calibrar vignettes: https://roliveros-ramos.github.io/calibrar/
Calibrar paper: Oliveros-Ramos, R., Shin, Y.-J., 2025. calibrar: An R package for fitting complex ecological models. Methods in Ecology and Evolution 16, 507–519. https://doi.org/10.1111/2041-210X.14452
Calibrar application to OSMOSE: Oliveros-Ramos, R., Verley, P., Echevin, V., Shin, Y.-J., 2017. A sequential approach to calibrate ecosystem models with multiple time series data. Progress in Oceanography 151, 227–244. https://doi.org/10.1016/j.pocean.2017.01.002
Calibrar application to Atlantis: Morell, A., Kaplan, I.C., Morzaria-Luna, H.M., Rovellini, A., Harvey, C., Porobic, J.,Fulton, E.A., Oliveros-Ramos, R. From Manual Tuning to Semi-Automated Calibration: A Practical Framework for Calibrating Atlantis Ecosystem Models. In prep

3 of 64

Training organization

Overview of the framework
A calibration repository: the Puget Sound example
Alternative calibration options

4 of 64

Overview of the framework

5 of 64

Adapted from Oliveros-Ramos and Shin 2025

6 of 64

Adapted from Oliveros-Ramos and Shin 2025

atlantis2ls

7 of 64

Adapted from Oliveros-Ramos and Shin 2025

8 of 64

Adapted from Oliveros-Ramos and Shin 2025

9 of 64

Adapted from Oliveros-Ramos and Shin 2025

10 of 64

Adapted from Oliveros-Ramos and Shin 2025

11 of 64

Adapted from Oliveros-Ramos and Shin 2025

12 of 64

Adapted from Oliveros-Ramos and Shin 2025

13 of 64

II. A calibration repository: the Puget Sound example

14 of 64

A calibration repository

https://github.com/alaiam/Atlantis_Calibration

15 of 64

A calibration repository

https://github.com/alaiam/Atlantis_Calibration

16 of 64

17 of 64

1) The model

A folder that holds the configuration file:

The prm files
The functional group file
The .sh file

This is the folder that will be copied for each simulation.

Recommandation:

The heavy files (initial conditions, forcing files…) can be stored outside the configuration files.

https://github.com/alaiam/Atlantis_Calibration

18 of 64

1) The model

The model configuration is going to be duplicated X times and each duplicata will be a simulation with a different comination of parameters

https://github.com/alaiam/Atlantis_Calibration

19 of 64

2) The data

A folder that holds the data file.

Recommandation:

One file per data type

https://github.com/alaiam/Atlantis_Calibration

20 of 64

2) The data

A file format:

Two columns (Time, Varid)

Row = N (User defined)

Here, N = 2. The data are confronted to the model for 2 timesteps

https://github.com/alaiam/Atlantis_Calibration

21 of 64

2) The data

A file format:

Two columns (Time, Varid)

Row = N (User defined)

Here, N = 2. The data are confronted to the model for 2 timesteps

Varid defined in setting files (see « 3) The objective function »)

https://github.com/alaiam/Atlantis_Calibration

22 of 64

3) The objective function

The csv file that collects the information to build the objective function.

A csv file that lists all your data, the type of data, the function to compare to data, the weight.

https://github.com/alaiam/Atlantis_Calibration

23 of 64

3) The objective function

https://github.com/alaiam/Atlantis_Calibration

24 of 64

3) The objective function

Variable name (used in « 5 - Run model function »)

https://github.com/alaiam/Atlantis_Calibration

25 of 64

3) The objective function

Function to compare observed and simulated data

https://github.com/alaiam/Atlantis_Calibration

26 of 64

3) The objective function

Function to compare observed and simulated data

https://github.com/alaiam/Atlantis_Calibration

27 of 64

3) The objective function

https://github.com/roliveros-ramos/calibrar/blob/master/R/calibraR-fitness.R

https://github.com/alaiam/Atlantis_Calibration

28 of 64

3) The objective function

Include in the objective function estimation

https://github.com/alaiam/Atlantis_Calibration

29 of 64

3) The objective function

Weight of this data

https://github.com/alaiam/Atlantis_Calibration

30 of 64

3) The objective function

Include in the outputs

Recommandation: Use false to calibrate and use data coherently

https://github.com/alaiam/Atlantis_Calibration

31 of 64

3) The objective function

Path to data (relative path from the roots of the project)

https://github.com/alaiam/Atlantis_Calibration

32 of 64

3) The objective function

Varid needs to be consistent with data column name (see « 2) The data) »

https://github.com/alaiam/Atlantis_Calibration

33 of 64

4) The parameters

https://github.com/alaiam/Atlantis_Calibration

34 of 64

4) The parameters

https://github.com/alaiam/Atlantis_Calibration

35 of 64

4) The parameters

Parameter name

https://github.com/alaiam/Atlantis_Calibration

36 of 64

4) The parameters

Parameter initial guess

https://github.com/alaiam/Atlantis_Calibration

37 of 64

4) The parameters

Parameter minimal bound

https://github.com/alaiam/Atlantis_Calibration

38 of 64

4) The parameters

Parameter maximal bound

https://github.com/alaiam/Atlantis_Calibration

39 of 64

4) The parameters

Parameter phase of calibration

For Atlantis, recommandation = 1

https://github.com/alaiam/Atlantis_Calibration

40 of 64

4) The parameters

Parameter name:

Species_Parameter-type_Transformation

https://github.com/alaiam/Atlantis_Calibration

41 of 64

5) Run Model function

https://github.com/alaiam/Atlantis_Calibration

42 of 64

5) Run Model function

A function divided in three parts:

1) The parameter modification
2) The Atlantis run
3) The processing of the outputs

https://github.com/alaiam/Atlantis_Calibration

43 of 64

5) Run Model function

1) The parameter modification: example with « mum »

https://github.com/alaiam/Atlantis_Calibration

44 of 64

5) Run Model function

1) The parameter modification: example with « mum »

2 biological prm files in the simulation folder: the inital before modification and the one with modifications (bio.prm).

.sh needs to call « bio.prm »

https://github.com/alaiam/Atlantis_Calibration

45 of 64

5) Run Model function

2) The Atlantis run

https://github.com/alaiam/Atlantis_Calibration

46 of 64

5) Run Model function

3) The processing of the outputs

https://github.com/alaiam/Atlantis_Calibration

47 of 64

5) Run Model function

3) The processing of the outputs: useful tip if the simulation did not finish

https://github.com/alaiam/Atlantis_Calibration

48 of 64

6) The calibrate script

https://github.com/alaiam/Atlantis_Calibration

49 of 64

6) The calibrate script

A script divided in four parts:

1) Importation of the information
2) The controls
3) The cluster management
4) Run the calibration

https://github.com/alaiam/Atlantis_Calibration

50 of 64

6) The calibrate script

1) Importation of the information

https://github.com/alaiam/Atlantis_Calibration

51 of 64

6) The calibrate script

2) The controls

This part of the script controls calibration options

https://github.com/alaiam/Atlantis_Calibration

52 of 64

6) The calibrate script

3) The cluster management

https://github.com/alaiam/Atlantis_Calibration

53 of 64

6) The calibrate script

4) Run the calibration

https://github.com/alaiam/Atlantis_Calibration

54 of 64

6) The calibrate script

4) Run the calibration

The parameter information

https://github.com/alaiam/Atlantis_Calibration

55 of 64

6) The calibrate script

4) Run the calibration

The objective function information

https://github.com/alaiam/Atlantis_Calibration

56 of 64

6) The calibrate script

4) Run the calibration

The objective algorithm information

https://github.com/alaiam/Atlantis_Calibration

57 of 64

7) The outputs of the calibration

https://github.com/alaiam/Atlantis_Calibration

58 of 64

III. Alternative calibration options

(advance training)

59 of 64

3) The objective function

https://github.com/alaiam/Atlantis_Calibration

Other options for the objective function are available in calibrar and are displayed at this link: https://github.com/roliveros-ramos/calibrar/blob/master/R/calibraR-fitness.R

It includes distribution that are normal, lognormal, poisson, multinomial…

Additional function can be added. For example:

Trend penalty:

Range:

60 of 64

3) The objective function

Weight of this data

https://github.com/alaiam/Atlantis_Calibration

Should inversely proportionnal to the uncertainty

61 of 64

2) The data

https://github.com/alaiam/Atlantis_Calibration

1200.5

Stable state

Annual variability

62 of 64

2) The data

https://github.com/alaiam/Atlantis_Calibration

Other type of data can be added:

Diet, number-at-age … (multinomial)
Biomass index (lnorm3)
Catch data (lnorm2)
Eventually spatial data (?)
Etc…

63 of 64

4) The parameters

Adding a new parameters only requires a new function to modify the prm files

https://github.com/alaiam/Atlantis_Calibration

64 of 64

6) The calibrate script

4) Run the calibration

https://github.com/alaiam/Atlantis_Calibration

methods = c("L-BFGS-B", "nlminb", "Rcgmin", "Rvmmin",

"hjn", "spg", "LBFGSB3", "CMA-ES", "genSA", "DE", "soma", "genoud", "PSO",

"hybridPSO", "mads", "hjkb", "nmkb", "bobyqa", "AHR-ES", "Nelder-Mead",

"CG", "BFGS", "SANN")

Other calibration algorithms are available in the function calibrate (argument « method »).

AHR-ES and Rvmmin are the two methods recommended for Atlantis. For now, this two methods only can record a restart between iterations, which is highly recommended in the case of a long run.

After empirical test, AHR-ES is the most recommended option.