= How to loop over years with libIGCM =
Author: M. !McGrath[[BR]]
Last revision: 2020/02/28, F. Maignan

Let's say that you want to run a 200Y long simulation, but you only want to use a few years of forcing data (we won't worry about why you want to do this at the moment). This is pretty easy to do with libIGCM by slightly modifying Josefine's instructions for running with analytical spinup, which I've mostly copied here.

== How it works to use cyclic forcing ==
By adding the 2 variables '''!CyclicBegin''' and '''!CyclicEnd''' to config.card the cyclic functionality can be used. 
!CyclicBegin is the first year of the forcing file to be used and !CyclicEnd is the last year. So if I wanted to loop over years 1950-1953, I would add the following to config.card:

{{{
CyclicBegin=1950
CyclicEnd=1953
}}}

libIGCM will use these variables to calculate the new variable '''!CyclicYear'''. !CyclicYear is the year within the forcing period [!CyclicBegin, !CyclicEnd]. This new variable has to be used in orchidee_ol.card and sechiba.card to copy the correct forcing files.

Now let's say that I want to run for 10 total years (notice this is not a multiple of the number of cyclic years. If you are doing analytical spinup, it has to be, but not if you're just doing cyclic forcing. Again, we won't ask why you want to do this). We need to change config.card.

{{{
DateBegin=1950-01-01   # Same as CyclicBegin
DateEnd=1959-12-31     
PeriodLength=1Y
}}}

If we leave everything else the same, libIGCM isn't going to know to use the cyclic forcing files and it will just use the ones corresponding to the current date. This is because we only defined the variables in config.card; we haven't actually told libIGCM to use the variables anywhere yet. If we make the following modifications, then we are telling libIGCM exactly where to use the new variables.


=== COMP/orchidee_ol.card ===
{{{
[BoundaryFiles]
List=	(${R_BC}/OOL/${config_UserChoices_TagName}/NCC/ncc_for_${CyclicYear}.nc, forcing_file.nc)
}}}


=== COMP/sechiba.card ===
The PFTmap file must be copied using the variable !CyclicYear. In sechiba.card, remove PFTmap from section [!InitialStateFiles]. Notice that you have to remove ",\" in the end of the line with floodplains.nc. This section becomes:

{{{
[InitialStateFiles]
List=       (${R_INIT}/SRF/${config_UserChoices_TagName}/routing.nc, .),     \
            (${R_INIT}/SRF/${config_UserChoices_TagName}/soils_param.nc, .), \
            (${R_INIT}/SRF/${config_UserChoices_TagName}/cartepente2d_15min.nc, .), \
            (${R_INIT}/SRF/${config_UserChoices_TagName}/floodplains.nc, .)
}}}

In section [!BoundaryFiles] change following:
{{{
[BoundaryFiles]
#List=  (${R_BC}/SRF/${config_UserChoices_TagName}/PFTmap_1850to2005_AR5_LUHa.rc2/PFTmap_IPCC_${year}.nc, .)
List=   ()
ListNonDel= ()
}}}

into 

{{{
[BoundaryFiles]
List=  (${R_BC}/SRF/${config_UserChoices_TagName}/PFTmap_1850to2005_AR5_LUHa.rc2/PFTmap_IPCC_${CyclicYear}.nc, PFTmap.nc)
ListNonDel= ()
}}}

Notice that you need to remove the additional "List=  ()" line. No specific treatment in sechiba.driver will now be done for the PFTmap.nc file. It is not necessary to change in sechiba.driver. 

=== PARAM/run.def ===

{{{
DRIVER_reset_time=y
}}}