# README for the coupled anice model - Bas de Boer (IMAU), April 2017

The coupled model consists of 6 directories, 4 of which containt the ice-sheet model for a specific region, 
a main directory and a directory for the sea level model (NOT USED)

main_src  : The main directory that contains the mian program inverse_coupling_program.f90, the main configuration
            routine, configuration_main_module.f90, that set ups al variables and reads the configuration file (from the directory config_files)
src_nam4  : contains the ice-sheet model for the North American ice-sheet, main routine is nam_grice_module.f90
src_eas4  : contains the ice-sheet model for the Eurasian ice-sheet, main routine is eas_grice_module.f90
src_ant4  : contains the ice-sheet model for the Antarctic ice-sheet, main routine is ant_grice_module.f90
src_grl4  : contains the ice-sheet model for the Greenland ice-sheet, main routine is grl_grice_module.f90
selen_src : NOT USED!

#--------------------------#
#    Compiling the code    #
#--------------------------#

The model is compiled with Makefiles in each directory. The main makefile is in main_src and is just called Makefile. 
All Makefiles use the same compiler makefile which is called Makefile.include. This is just a copy of the Makefile that 
is specifically needed for which machine and/or compiler you use. To run the model with ifort on the LISA super 
computer for example one should use Makefile.ifort-lisa by copying this to Makefile.include. In the Terminal go 
to the directory main_src and:

By default the model is run with gfortran-mp-4.9 on a Mac

It uses Netcdf libraries, which (of not already done so) need to be installed as follows, go to the Terminal and type: 

sudo port install netcdf-fortran +gcc49

If you have full authorisation on your Mac this should work.
You can also check all the installed libraries and programmes by:

sudo port installed

If you run the model on a Mac with gfortran-mp-4.9 you should do:

cp Makefile.gfortran-mac-mp-4.9 Makefile.include

# NOTE: by default this is already done, so Makefile.include includes the gfortran-mp-4.9 compiler

To compile the model go to main_src and run in Terminal:
make all

If you do change something in the code, the best thing to do is first clean up all compiled modules by:
make clean
make all

An easier way is running the shell script run_coupled_model.sh without arguments from the main directory anice_coupled_model:
./run_coupled_model.sh

This compiles the code for you, and in this script you can also add a 'make clean' statement when recompiling the code 
by removing the commenting #. 

#--------------------------#
#    Configuration file    #
#--------------------------#

First and foremost, the model is set up with a configuration file, in the config_files directory. The main example 
is config_anice4_short_benchmark_for_testing. Keep this file as an example and do not change it!

In main_src, in the configuration_main_module.f90 routine this files is read and all CONFIG variables are given there values.
In the code, all CONFIG variables are saved when initialising the model in a structure called C% in configuration_main_module.f90.
One can easily change a parameter by setting it do a different value in the configuration file. This way you do not 
have to recompile the code and sensitivity tests can be performed by just altering the configuration file, DO NOT CHANGE configuration_main_module.f90!

All variables and parameters that are important are listed in the config files and are specifically explained there as well. 

Note that all input files are given with their full paths, in order that they always can be found no matter from which 
directory you run the from IMPORTANT: Do not forget to change the full paths for all input files. You can locate where the input_fields 
directory is by typing in Terminal:
pwd

#--------------------------#
#    Running the model     #
#--------------------------#

A short and simple test can be done by running the model, in the foreground, with adding an argument to the run script:
./run_coupled_model normal

The model output is then saved in the standard output directory results_ice4.
An example of output files can be seen in the directory results_test_by_BdB.

To perform a long run in a specific directory you can run the script: 
./long_local_run_antarctica.sh 001

This uses the configuration file config_anice4_run_with_northamerica.

The long_local_run.sh script needs one arguments to run (as the example above: 001 or a name):
argument 1: the number or name of the run

#--------------------------#
#      Output files        #
#--------------------------#

- restart_ant.nc                      The restart netcdf file, includes fields that are needed for a restart
- recording_ant.nc                    Averages and time-dependend variables 
- help_fields_ant.nc                  Additional fields of output such as mass balance, surface slopes, etc.

- ANICE4_output_antarctica            Output from the Antarctic model such as sea-level contribution, volumes, areas
- ANICE4_output_ant_total_mass_change Output from the Antarctic model concerning mass balance and changes in ice thickness

- ANICE4_output_standard              Main output of the model, for example lists specific sea-level contributions and input forcing
- ANICE4_output_isotopes              Main output of the model, concerning isotope contribtions, wouldn't be useful at this point

additional messages

- fort.10925    Concerning warnings or checks by the model. The model can run well with these messages though.
- fort.111      Some additional output and error messages if the model crashed in the shelf or thermodynamics routines.











