NamelistOptions

MC-KPP Namelist Options

This page describes the available MC-KPP namelist options. The namelist is called 3D_ocn.nml. Namelist options are organised into groups. The following tables show, for each group, the available options, possible settings and a brief explanation of each.

Most options that users will want to change are in the NAME_TIMES, NAME_FORCING, NAME_COUPLE and NAME_OUTPUT groups. Those changing the model horizontal domain will need to alter the options in NAME_DOMAIN.

Use these links to jump quickly to a particular namelist group:

• NAME_TIMES - Controls simulation start and end time, as well as the model timestep
• NAME_COUPLE - Controls coupling to an atmospheric model
• NAME_ADVEC - Controls advection, including temperature and salinity corrections
• NAME_FORCING - Controls forcing data, including reference SSTs and sea ice
• NAME_OUTPUT - Controls diagnostic output
• NAME_DOMAIN - Controls the horizontal and vertical domain (but not the number of gridpoints, which much be specified at compile time)
• NAME_START - Controls the initial conditions and checkpointing
• NAME_PARAS - Controls optical properties of seawater
• NAME_LANDSEA - Controls land/sea fraction and bathymetry
• NAME_CONSTANTS - Controls physical constants
• NAME_PROCSWIT - Controls physical processes in the model

NAME_TIMES

Namelist Option	Type	*Default value *	Description
dtsec	Real	Undefined	Time (in seconds) between updates to the surface forcing data. In coupled mode, this is the coupling frequency. In forced mode, this is the frequency at which the surface forcing is updated from the netCDF file.
startt	Real	Undefined	Time (in days) at which the integration begins. Normally, zero refers to 1 January of the first year of the simulation. The convention must agree with the time convention in the ancillary files.
finalt	Real	Undefined	Time (in days) at which the integration ends. Normally, zero refers to 1 January of the first year of the simulation. The convention must agree with the time convention in the ancillary files.
ndtocn	Integer	1	The number of model timesteps per dtsec. The timestep is dtsec divided by ndtocn.

NAME_COUPLE

Namelist Option	Type	*Default value *	Description
L_COUPLE	Logical	None	Run the model in coupled mode. If compiled in coupled mode, default is TRUE; otherwise, default is FALSE.
ifirst	Integer	Undefined	The position (in gridpoints, not degrees) of the first coupled longitude point on the grid of the atmospheric model to which MC-KPP is coupled.
ilast	Integer	Undefined	The position (in gridpoints, not degrees) of the last coupled longitude point on the grid of the atmospheric model.
jfirst	Integer	Undefined	The position (in gridpoints, not degrees) of the first coupled latitude point on the grid of the atmospheric model.
jlast	Integer	Undefined	The position (in gridpoints, not degrees) of the last coupled latitude point on the grid of the atmospheric model.
L_CPLWGHT	Logical	False	Use a netCDF file to define coupling weight (the weight applied to the MC-KPP SST). If FALSE, the coupling weight is set to 1.0 at every coupled gridpoint.
cplwght_file	String	Undefined	Local path to the netCDF file containing the coupling weights
L_OUTKELVIN	Logical	False	Return SST to atmospheric model in Kelvin (TRUE) rather than degrees Celsius (FALSE)
L_UPDCLIM	Logical	False	Deprecated
L_CLIMSST	Logical	False	Use a netCDF file to specify a reference SST. Reference SSTs are applied outside the coupling region, everywhere that the coupling weight is less than 1.0. They are also used when relaxing only the SST to climatology (L_RELAX).
sstin_file	String	Undefined	Local path to the netCDF file containing the reference SSTs
L_UPD_CLIMSST	Logical	False	Update the reference SSTs during the simulation (i.e., use time-varying reference SSTs).
ndtupdsst	Integer	Undefined	Number of ocean model timesteps between updates to the reference SSTs
L_PERIODIC_CLIMSST	Logical	False	Reference SSTs are periodic in time (period specified by climsst_period below)
climsst_period	Integer	Undefined	Period (in days) at which to cycle the reference SST
L_CLIMICE	Logical	False	Use a netCDF file to specify sea-ice concentrations. MC-KPP does not modify this reference concentration; it merely returns it to the atmosphere. If you want to have any sea ice in your coupled model, regardless of the coupling domain, you must specify TRUE and see the options below.
icein_file	String	Undefined	Local path to the netCDF file containing the sea-ice concentrations
L_UPD_CLIMICE	Logical	False	Update the sea-ice concentrations during the simulation (i.e., use time-varying sea-ice concentrations).
ndtupdice	Integer	Undefined	Number of ocean model timesteps between updates to the sea-ice concentrations
L_PERIODIC_CLIMICE	Logical	False	Sea-ice concentrations are periodic in time (period specified by climice_period below)
climice_period	Integer	False	Period (in days) at which to cycle the sea-ice concentrations
L_CLIM_ICE_DEPTH	Logical	False	Use a netCDF file to specify sea-ice depths. If FALSE, the sea-ice depth will be set to two metres everywhere there is sea ice. Ice depths will be read from the same file, and updated with the same frequency, as the sea-ice concentrations.
L_CLIM_SNOW_ON_ICE	Logical	False	Use a netCDF file to specify the amount of snow on sea ice. If FALSE, MC-KPP assumes there is no snow on the sea ice. The amount of snow will be read from the same file, and updated with the same frequency, as the sea-ice concentrations.
L_COUPLE_CURRENTS	Logical	False	Return the MC-KPP surface currents to the atmospheric model. If FALSE, MC-KPP returns zero currents. The currents are modified by the same coupling weights as the SSTs, blended with either climatological values (if specified) or zero if the coupling weight is less than 1.0.
L_CLIMCURR	Logical	False	Use a netCDF file to specify reference surface currents. If FALSE, the reference current is set to zero.
currin_file	String	Undefined	Local path to the netCDF file containing reference zonal and meridional surface currents
L_UPD_CLIMCURR	Logical	False	Update the reference surface currents during the simulation (i.e., use time-varying reference surface currents)
ndtupdcurr	Integer	Undefined	Number of ocean model timesteps between updates to the reference surface currents
L_DIST_RUNOFF	Logical	False	Enables distribution of river runoff to coupled gridpoints. River runoff passed from the atmosphere is accumulated over the coupled domain, then returned to all coupled ocean gridpoints equally as an increment to the freshwater flux.

NAME_ADVEC

Namelist Option	Type	*Default value *	Description
L_ADVECT	Logical	False	Use a netCDF file to specify horizontal advection terms
advect_file	String	Undefined	Local path to the netCDF file containing horizontal advection terms
L_RELAX_SST	Logical	False	Linearly relax MC-KPP SSTs towards a reference SST, specified by sstin_file in NAME_COUPLE. The relaxation corrects the entire model-diagnosed mixed-layer depth by the bias in the SST.
relax_sst_in	Integer(NY)	0	Timescale (in days) for the linear relaxation of the MC-KPP SST towards a reference SST. You must specify one value per latitude band in MC-KPP. Use Fortran namelist syntax (e.g., 520,1030 would give the first five bands a 20 day timescale and the next 10 a 30-day timescale). Specify 0 for no relaxation in that latitude band.
L_RELAX_CALCONLY	Logical	False	Calculate the SST relaxation terms, but do not apply them. Warning: This will allow the model to drift; the output values will not be same as if L_RELAX_SST and L_RELAX_SST is specified and interactive relaxation is applied.
L_RELAX_OCNT	Logical	False	Linearly relax the full MC-KPP temperature profile towards a reference profile, specified by ocnt_file in NAME_FORCING
relax_ocnt_in	Integer(NY)	0	Timescale (in days) for the linear relaxation of the MC-KPP temperature profile towards a reference profile. You must specify one value per latitude band in MC-KPP.
L_RELAX_SAL	Logical	False	Linearly relax the full MC-KPP salinity profile towards a reference profile, specified by sal_file in NAME_FORCING
relax_sal_in	Integer(NY)	0	Timescale (in days) for the linear relaxation of the MC-KPP salinity profile towards a reference profile. You must specify one value per latitude band in MC-KPP.

NAME_FORCING

Namelist Option	Type	*Default value *	Description
L_FLUXDATA	Logical	False	Use a netCDF file for surface forcing data. You must set this to TRUE if you are performing a forced-ocean simulation.
forcing_file	String	Undefined	Local path to the netCDF file containing surface forcing data. Forcing data will be updated every dtsec seconds during the simulation.
ocnt_file	String	Undefined	Local path to the netCDF file containing reference temperature profiles for computing 4D (x,y,z,t) temperature corrections. For use with L_RELAX_OCNT in NAME_ADVEC.
L_UPD_OCNT	Logical	False	Update the reference temperature profiles during the simulation.
ndtupdocnt	Integer	Undefined	The frequency (in timesteps) with which to update the reference temperature profiles
L_PERIODIC_OCNT	Logical	False	Reference temperature profiles are periodic in time (period specified by ocnt_period below).
ocnt_period	Integer	Undefined	The period (in days) at which to cycle the reference temperature profiles.
sal_file	String	Undefined	Local path to the netCDF file containing reference salinity profiles for computing 4D (x,y,z,t) salinity corrections. For use with L_RELAX_SAL in NAME_ADVEC.
L_UPD_SAL	Logical	False	Update the reference salinity profiles during the simulation.
ndtupdsal	Integer	Undefined	The frequency (in timesteps) with which to update the reference salinity profiles
L_PERIODIC_SAL	Logical	False	Reference salinity profiles are periodic in time (period specified by sal_period below).
sal_period	Integer	Undefined	The period (in days) at which to cycle the reference salinity profiles.
L_FCORR	Logical	False	Use a netCDF file containing 3D (x,y,t) temperature corrections, used to constrain the mixed-layer temperature only (i.e., from L_RELAX_SST in NAME_ADVEC)
L_FCORR_WITHZ	Logical	False	Use a netCDF file containing 4D (x,y,z,t) temperature corrections, used to constrain the entire temperature profile (i.e., from L_RELAX_OCNT in NAME_ADVEC)
fcorrin_file	String	Undefined	Local path to the netCDF file containing either 3D or 4D temperature corrections. Only one method (i.e., 3D or 4D) may be applied in any given simulation.
L_UPD_FCORR	Logical	False	Update the temperature corrections (3D or 4D) during the simulation.
ndtupdfcorr	Integer	Undefined	The frequency (in timesteps) with which to update the temperature corrections (3D or 4D)
L_PERIODIC_FCORR	Logical	False	The temperature corrections (3D or 4D) are periodic in time (period specified by fcorr_period below)
fcorr_period	Integer	Undefined	The period (in days) at which to cycle the temperature corrections (3D or 4D)
L_SFCORR_WITHZ	Logical	False	Use a netCDF file containing 4D (x,y,z,t) salinity corrections, used to constrain the entire salinity profile (i.e., from L_RELAX_SAL in NAME_ADVEC).
sfcorrin_file	String	Undefined	Local path to the netCDF file containing 4D salinity corrections.
L_UPD_SFCORR	Logical	False	Update the 4D salinity corrections during the simulation.
ndtupdsfcorr	Integer	Undefined	The frequency (in timesteps) with which to update the 4D salinity corrections
L_PERIODIC_SFCORR	Logical	False	The 4D salinity corrections are periodic in time (period specified by sfcorr_period below)
sfcorr_period	Integer	Undefined	The period (in days) at which to cycle the 4D salinity corrections
L_VARY_BOTTOM_TEMP	Logical	False	Use a netCDF file to specify the temperature of the bottom-most point in MC-KPP, equivalent to a no-flux boundary condition.
bottomin_file	String	Undefined	Local path to the netCDF file containing the bottom-point temperatures
L_UPD_BOTTOM_TEMP	Logical	False	Update the bottom-point temperatures during the simulation.
ndtupdbottom	Integer	Undefined	The frequency (in timesteps) with which to update the bottom-point temperatures
L_PERIODIC_BOTTOM_TEMP	Logical	False	The bottom-point temperature are periodic in time (period specified by bottom_temp_period below)
bottom_temp_period	Integer	Undefined	The period (in days) at which to cycle the bottom-point temperatures
L_DAMP_CURR	Logical	False	Damp the MC-KPP currents at all levels to zero, using a non-linear relaxation. Recommended for climate-length simulations.
dtuvdamp	Integer	Undefined	Timescale for the non-linear current damping. A value of 360 days is recommended for climate-length simulations.
L_NO_FREEZE	Logical	False	Prevent MC-KPP temperatures from dropping below -1.8C. Any temperature anywhere in any profile below -1.8C is automatically set to -1.8C. If triggered, the amount of heat added to raise the temperature to -1.8C is included in the temperature-increment diagnostic output (see DiagnosticList).
L_NO_ISOTHERM	Logical	False	Prevent isothermal layers from developing over a specified range of vertical gridpoints (see below). This is an advanced option for debugging and testing that is not normally required. If triggered, the point is reset to climatology (if available through ocnt_file and sal_file) or to the initial conditions.
isotherm_bottom	Integer	Undefined	The number of the bottom point to use for the isothermal-layer detection routine. The top point is always the first vertical point.
isotherm_threshold	Real	Undefined	The threshold difference (in degrees Celsius) between the top and bottom point to use for the isothermal-detection routine.
L_FCORR_NSOL	Logical	False	Relax the model SST toward the target SST climatology (specified by sstin_file in NAME_COUPLE) by adjusting the non-solar heat flux into the ocean, using a relaxation coefficient specified either as a global constant through a namelist option (fcorr_nsol_coeff below) or as a spatially varying field using a netCDF file (fcorr_nsol_file). Implemented for DCPP simulations.
fcorr_nsol_coeff	Real	0.0	Relaxation coefficient for non-solar heat flux correction above, in units of W m^-2^ K^-1^.
L_FCORR_NSOL_FILE	Logical	False	Switch to specify the non-solar heat flux correction coefficient using a netCDF file.
fcorr_nsol_file	String	Undefined	Location of the netCDF file containing a spatially varying relaxation coefficient for the non-solar heat flux correction.

NAME_OUTPUT

Namelist Option	Type	*Default value *	Description
L_OUTPUT_INST	Logical	True	Output instantaneous diagnostics to netCDF files called KPPocean_[time].nc, where [time] is the day of the last output time in the file.
ndt_varout_inst	Integer(N_VAROUTS)	0	Frequency (in timesteps) at which to output instantaneous four-dimensional (x,y,z,t) diagnostics. You must specify one value for each diagnostic; specify 0 for any diagnostics you do not wish to output. See the DiagnosticList for the list of diagnostics.
ndt_singout_inst	Integer(N_SINGOUTS)	0	Frequency (in timesteps) at which to output instantaneous three-dimensional (x,y,t) diagnostics. You must specify one value for each diagnostic; specify 0 for any diagnostics you do not wish to output. See the DiagnosticList for the list of diagnostics.
L_OUTPUT_MEAN	Logical	False	Output time-mean diagnostics for netCDF files called KPPocean_[time]_means.nc, where [time] is the day of the last output time in the file.
ndt_varout_mean	Integer(N_VAROUTS)	0	As ndt_varout_inst, but for time-mean diagnostics. The output and meaning frequencies are identical.
ndt_singout_mean	Integer(N_SINGOUTS)	0	As ndt_singout_inst, but for time-mean diagnostics. The output and meaning frequencies are identical.
L_OUTPUT_RANGE	Logical	False	Output minima and maxima of diagnostics over a specified window to netCDF files called KPPocean_[time]min.nc and KPPocean[time]_max.nc, respectively. You must specify one value for each diagnostic; specify 0 for any diagnostics you do not wish to output. See the DiagnosticList for the list of diagnostics.
ndt_varout_range	Integer(N_VAROUTS)	0	As ndt_varout_inst, but for minima and maxima. The windows for minima and maxima are identical.
ndt_singout_range	Integer(N_SINGOUTS)	0	As ndt_singout_inst, but for minima and maxima. The windows for minima and maxima are identical.
zprofs	Integer(NZP1,N_ZPROFS_MAX)	0	Up to 5 lists of MC-KPP vertical levels on which output is desired. This allows the user to specify a reduced set of vertical levels for diagnostic output. Each list must be NZP1 (number of vertical points in the model) long. The items in the list must be integer numbers of the levels desired. After the last level desired, specify zeros for the remainder of the list. This can be shortened with Fortran notation (e.g., 60*0 is 60 zeroes).
zprofs_varout_inst	Integer(N_VAROUTS)	1	The number of the vertical profile (zprofs) used to define the output vertical grid for each instantaneous diagnostic, as defined using the lists above. You must specify one value for each diagnostic; any diagnostics that are not being output (for which ndt_varout_inst is 0) are ignored, but must still be included in the list. A value of 0 specifies all vertical levels.
zprofs_varout_mean	Integer(N_VAROUTS)	1	As zprofs_varout_inst, but for each time-mean diagnostic.
zprofs_varout_range	Integer(N_VAROUTS)	1	As zprofs_varout_range, but for the minima and maxima of each diagnostic.
ndt_per_file	Integer	120	The number of ocean timesteps after which the output files are rotated (i.e., the current set of files are closed and a new set are opened.). All types of output file use the same rotation period.
L_RESTARTW	Logical	True	Write a restart file at the end of the simulation that can be used to reinitialize the model.
restart_outfile	String	KPP.restart.[time]	Filename for the restart outfile. [time] is replaced with the day number of the time at which the restart file is written.
ndt_per_restart	Integer	The length of the simulation	The frequency (in timesteps) at which restart files are written.

NAME_DOMAIN

Namelist Option	Type	*Default value *	Description
dmax	Real	0.0 m	Depth of the ocean column (positive only)
L_STRETCHGRID	Logical	False	Use a stretched vertical grid, defined by dscale
dscale	Real	0.0	Exponent for the vertical stretched grid, higher values are more stacked towards the surface (positive only)
L_VGRID_FILE	Logical	False	Define the vertical grid using a netCDF file. Overrides L_STRETCHGRID and dscale.
vgrid_file	String	Undefined	Local path to the netCDF file containing the vertical grid
alat	Real	0.0	Latitude of the bottom-left corner of the horizontal domain. Must be defined regardless of L_REGGRID setting.
alon	Real	0.0	Longitude of the bottom-left corner of the horizontal domain. Must be defined regardless of L_REGRRID setting.
L_REGGRID	Logical	True	Use a regularly spaced horizontal domain, defined by delta_lat and delta_lon. If FALSE, grid is read from land/sea mask file.
delta_lat	Real	2.50	Spacing in latitude between grid points
delta_lon	Real	3.75	Spacing in longitude between grid points
L_SLAB	Logical	False	Run as a slab ocean (single layer)
slab_depth	Real	30	Depth of slab ocean (in metres)

NAME_START

Namelist Option	Type	*Default value *	Description
L_INITDATA	Logical	True	Read initial conditions from netCDF file. Must be TRUE unless performing a restart run with L_RESTART.
initdata_file	String	None	Local path to the netCDF file containing the initial conditions
L_INTERPINIT	Logical	True	Interpolate initial conditions onto the KPP vertical grid
L_RESTART	Logical	False	Restart the simulation from a previous integration
restart_infile	String	fort.30	Local path to the Fortran output file containing the restart dump

NAME_PARAS

Namelist Option	Type	*Default value *	Description
L_JERLOV	Logical	True	Use a netCDF file containing Jerlov water types (optical properties of sea water). If FALSE, then all gridpoints use a Jerlov water type of IB.
paras_file	String	3D_ocnparas.nc	Local path to the netCDF file containing the Jerlov water types at each KPP horizontal gridpoint.
max_ekman_depth	Real	0.0	Maximum depth (positive down) of Ekman layer allowed for vertical Ekman pumping. Ekman depths deeper than this depth will have zero Ekman pumping. Suggested value 500 metres.
max_ekadv_depth	Real	0.0	Maximum depth for imposed vertical Ekman pumping. Profile of Ekman advection is a sinusoidal decay from the diagnosed Ekman depth, to zero at the surface and to zero at this maximum depth. Suggested value 750 metres.

NAME_LANDSEA

Namelist Option	Type	*Default value *	Description
L_LANDSEA	Logical	False	Use a netCDF file to specify the land/sea fraction and the ocean bathymetry. If FALSE, all points are assumed to be entirely ocean; the bathymetry is assumed to be equal to the depth of the MC-KPP water column.
landsea_file	String	Undefined	Local path to the netCDF file containing the land/sea fraction and the ocean bathymetry.

NAME_CONSTANTS

Namelist Option	Type	Default value	Description
grav	Real	9.816 m s^-2^	Acceleration due to gravity
vonk	Real	0.4	Von Karman's constant
sbc	Real	5.67x10^-8^ W m^-2^ K^-4^	Stefan-Boltsmann constant
twopi	Real	8 [tan^-1^(1.0)]	Twice the value of Pi to machine precision
onepi	Real	twopi/2.0	The value of Pi to machine precision
TK0	Real	273.15K	The value of 0^o^C in Kelvin
spd	Real	86400.0 s	The number of seconds per day
dpy	Real	360.0 days	The number of days per year (not currently used)
epsw	Real	1.0	Correction factor for the departure of water from a black body
albocn	Real	0.06	Albedo of sea water
EL	Real	2.5x10^6^ J kg^-1^	Latent heat of evaporation for water
SL	Real	2.5122x10^6^ J kg^-1^	Latent heat of evaporation for ice
FL	Real	3.34x10^5^ J kg^-1^	Latent heat of fusion for ice
FLSN	Real	3.34x10^5^ J kg^-1^	Latent heat of fusion for snow

NAME_PROCSWIT

Namelist Option	Type	Default value	Description
LKPP	Logical	True	Enables KPP boundary-layer mixing scheme
LRI	Logical	True	Enables Richardson-number mixing scheme below the diagnosed mixing depth
LDD	Logical	False	Enables double-diffusion calculations (greatly increases run time)
LICE	Logical	False	Enables simple sea-ice submodel (not implemented)
LNBFLX	Logical	False	Enables a no-flux boundary condition (no diffusion or viscosity) for the bottom of the column
L_SSref	Logical	True	Calculate the surface salinity as an offset from a reference value, taken from the initial condition
L_EKMAN_PUMP	Logical	False	Enables vertical Ekman advection (pumping) by the curl of the surface wind stress. Advection can be tuned by adjusting max_ekman_depth and max_ekadv_depth in NAME_PARAS.