MOM6
user_initialization.F90
Go to the documentation of this file.
1 !> A template of a user to code up customized initial conditions.
3 
4 ! This file is part of MOM6. See LICENSE.md for the license.
5 
9 use mom_get_input, only : directories
10 use mom_grid, only : ocean_grid_type
20 implicit none ; private
21 
22 #include <MOM_memory.h>
23 
27 
28 ! A note on unit descriptions in comments: MOM6 uses units that can be rescaled for dimensional
29 ! consistency testing. These are noted in comments with units like Z, H, L, and T, along with
30 ! their mks counterparts with notation like "a velocity [Z T-1 ~> m s-1]". If the units
31 ! vary with the Boussinesq approximation, the Boussinesq variant is given first.
32 
33 !> A module variable that should not be used.
34 !! \todo Move this module variable into a control structure.
35 logical :: first_call = .true.
36 
37 contains
38 
39 !> Set vertical coordinates.
40 subroutine user_set_coord(Rlay, g_prime, GV, US, param_file, eqn_of_state)
41  type(verticalgrid_type), intent(in) :: gv !< The ocean's vertical grid
42  !! structure.
43  real, dimension(:), intent(out) :: rlay !< Layer potential density [R ~> kg m-3].
44  real, dimension(:), intent(out) :: g_prime !< The reduced gravity at
45  !! each interface [L2 Z-1 T-2 ~> m s-2].
46  type(unit_scale_type), intent(in) :: us !< A dimensional unit scaling type
47  type(param_file_type), intent(in) :: param_file !< A structure indicating the
48  !! open file to parse for model
49  !! parameter values.
50  type(eos_type), pointer :: eqn_of_state !< Integer that selects the
51  !! equation of state.
52 
53  call mom_error(fatal, &
54  "USER_initialization.F90, USER_set_coord: " // &
55  "Unmodified user routine called - you must edit the routine to use it")
56  rlay(:) = 0.0
57  g_prime(:) = 0.0
58 
59  if (first_call) call write_user_log(param_file)
60 
61 end subroutine user_set_coord
62 
63 !> Initialize topography.
64 subroutine user_initialize_topography(D, G, param_file, max_depth, US)
65  type(dyn_horgrid_type), intent(in) :: g !< The dynamic horizontal grid type
66  real, dimension(G%isd:G%ied,G%jsd:G%jed), &
67  intent(out) :: d !< Ocean bottom depth in m or Z if US is present
68  type(param_file_type), intent(in) :: param_file !< Parameter file structure
69  real, intent(in) :: max_depth !< Maximum model depth in the units of D
70  type(unit_scale_type), optional, intent(in) :: us !< A dimensional unit scaling type
71 
72  call mom_error(fatal, &
73  "USER_initialization.F90, USER_initialize_topography: " // &
74  "Unmodified user routine called - you must edit the routine to use it")
75 
76  d(:,:) = 0.0
77 
78  if (first_call) call write_user_log(param_file)
79 
80 end subroutine user_initialize_topography
81 
82 !> initialize thicknesses.
83 subroutine user_initialize_thickness(h, G, GV, param_file, just_read_params)
84  type(ocean_grid_type), intent(in) :: g !< The ocean's grid structure.
85  type(verticalgrid_type), intent(in) :: gv !< The ocean's vertical grid structure.
86  real, dimension(SZI_(G),SZJ_(G),SZK_(GV)), &
87  intent(out) :: h !< The thicknesses being initialized [H ~> m or kg m-2].
88  type(param_file_type), intent(in) :: param_file !< A structure indicating the open
89  !! file to parse for model parameter values.
90  logical, optional, intent(in) :: just_read_params !< If present and true, this call will
91  !! only read parameters without changing h.
92 
93  logical :: just_read ! If true, just read parameters but set nothing.
94 
95  call mom_error(fatal, &
96  "USER_initialization.F90, USER_initialize_thickness: " // &
97  "Unmodified user routine called - you must edit the routine to use it")
98 
99  just_read = .false. ; if (present(just_read_params)) just_read = just_read_params
100 
101  if (just_read) return ! All run-time parameters have been read, so return.
102 
103  h(:,:,1) = 0.0 ! h should be set [H ~> m or kg m-2].
104 
105  if (first_call) call write_user_log(param_file)
106 
107 end subroutine user_initialize_thickness
108 
109 !> initialize velocities.
110 subroutine user_initialize_velocity(u, v, G, US, param_file, just_read_params)
111  type(ocean_grid_type), intent(in) :: g !< Ocean grid structure.
112  real, dimension(SZIB_(G), SZJ_(G), SZK_(G)), intent(out) :: u !< i-component of velocity [L T-1 ~> m s-1]
113  real, dimension(SZI_(G), SZJB_(G), SZK_(G)), intent(out) :: v !< j-component of velocity [L T-1 ~> m s-1]
114  type(unit_scale_type), intent(in) :: us !< A dimensional unit scaling type
115  type(param_file_type), intent(in) :: param_file !< A structure indicating the
116  !! open file to parse for model
117  !! parameter values.
118  logical, optional, intent(in) :: just_read_params !< If present and true, this call will
119  !! only read parameters without changing h.
120 
121  logical :: just_read ! If true, just read parameters but set nothing.
122 
123  call mom_error(fatal, &
124  "USER_initialization.F90, USER_initialize_velocity: " // &
125  "Unmodified user routine called - you must edit the routine to use it")
126 
127  just_read = .false. ; if (present(just_read_params)) just_read = just_read_params
128 
129  if (just_read) return ! All run-time parameters have been read, so return.
130 
131  u(:,:,1) = 0.0
132  v(:,:,1) = 0.0
133 
134  if (first_call) call write_user_log(param_file)
135 
136 end subroutine user_initialize_velocity
137 
138 !> This function puts the initial layer temperatures and salinities
139 !! into T(:,:,:) and S(:,:,:).
140 subroutine user_init_temperature_salinity(T, S, G, param_file, eqn_of_state, just_read_params)
141  type(ocean_grid_type), intent(in) :: g !< Ocean grid structure.
142  real, dimension(SZI_(G),SZJ_(G), SZK_(G)), intent(out) :: t !< Potential temperature [degC].
143  real, dimension(SZI_(G),SZJ_(G), SZK_(G)), intent(out) :: s !< Salinity [ppt].
144  type(param_file_type), intent(in) :: param_file !< A structure indicating the
145  !! open file to parse for model
146  !! parameter values.
147  type(eos_type), pointer :: eqn_of_state !< Integer that selects the
148  !! equation of state.
149  logical, optional, intent(in) :: just_read_params !< If present and true, this call will only
150  !! read parameters without changing T & S.
151 
152  logical :: just_read ! If true, just read parameters but set nothing.
153 
154  call mom_error(fatal, &
155  "USER_initialization.F90, USER_init_temperature_salinity: " // &
156  "Unmodified user routine called - you must edit the routine to use it")
157 
158  just_read = .false. ; if (present(just_read_params)) just_read = just_read_params
159 
160  if (just_read) return ! All run-time parameters have been read, so return.
161 
162  t(:,:,1) = 0.0
163  s(:,:,1) = 0.0
164 
165  if (first_call) call write_user_log(param_file)
166 
167 end subroutine user_init_temperature_salinity
168 
169 !> Set up the sponges.
170 subroutine user_initialize_sponges(G, GV, use_temp, tv, param_file, CSp, h)
171  type(ocean_grid_type), intent(in) :: g !< Ocean grid structure.
172  type(verticalgrid_type), intent(in) :: gv !< The ocean's vertical grid structure.
173  logical, intent(in) :: use_temp !< If true, temperature and salinity are state variables.
174  type(thermo_var_ptrs), intent(in) :: tv !< A structure containing pointers
175  !! to any available thermodynamic
176  !! fields, potential temperature and
177  !! salinity or mixed layer density.
178  !! Absent fields have NULL ptrs.
179  type(param_file_type), intent(in) :: param_file !< A structure indicating the
180  !! open file to parse for model
181  !! parameter values.
182  type(sponge_cs), pointer :: csp !< A pointer to the sponge control structure.
183  real, dimension(SZI_(G),SZJ_(G),SZK_(GV)), &
184  intent(in) :: h !< Layer thicknesses [H ~> m or kg m-2].
185  call mom_error(fatal, &
186  "USER_initialization.F90, USER_initialize_sponges: " // &
187  "Unmodified user routine called - you must edit the routine to use it")
188 
189  if (first_call) call write_user_log(param_file)
190 
191 end subroutine user_initialize_sponges
192 
193 !> This subroutine sets the properties of flow at open boundary conditions.
194 subroutine user_set_obc_data(OBC, tv, G, param_file, tr_Reg)
195  type(ocean_obc_type), pointer :: obc !< This open boundary condition type specifies
196  !! whether, where, and what open boundary
197  !! conditions are used.
198  type(thermo_var_ptrs), intent(in) :: tv !< A structure containing pointers to any
199  !! available thermodynamic fields, including potential
200  !! temperature and salinity or mixed layer density. Absent
201  !! fields have NULL ptrs.
202  type(ocean_grid_type), intent(in) :: g !< The ocean's grid structure.
203  type(param_file_type), intent(in) :: param_file !< A structure indicating the
204  !! open file to parse for model
205  !! parameter values.
206  type(tracer_registry_type), pointer :: tr_reg !< Tracer registry.
207 ! call MOM_error(FATAL, &
208 ! "USER_initialization.F90, USER_set_OBC_data: " // &
209 ! "Unmodified user routine called - you must edit the routine to use it")
210 
211  if (first_call) call write_user_log(param_file)
212 
213 end subroutine user_set_obc_data
214 
215 subroutine user_set_rotation(G, param_file)
216  type(ocean_grid_type), intent(inout) :: g !< The ocean's grid structure
217  type(param_file_type), intent(in) :: param_file !< A structure to parse for run-time parameters
218  call mom_error(fatal, &
219  "USER_initialization.F90, USER_set_rotation: " // &
220  "Unmodified user routine called - you must edit the routine to use it")
221 
222  if (first_call) call write_user_log(param_file)
223 
224 end subroutine user_set_rotation
225 
226 !> Write output about the parameter values being used.
227 subroutine write_user_log(param_file)
228  type(param_file_type), intent(in) :: param_file !< A structure indicating the
229  !! open file to parse for model
230  !! parameter values.
231 
232 ! This include declares and sets the variable "version".
233 #include "version_variable.h"
234  character(len=40) :: mdl = "user_initialization" ! This module's name.
235 
236  call log_version(param_file, mdl, version)
237  first_call = .false.
238 
239 end subroutine write_user_log
240 
241 !> \namespace user_initialization
242 !!
243 !! This subroutine initializes the fields for the simulations.
244 !! The one argument passed to initialize, Time, is set to the
245 !! current time of the simulation. The fields which are initialized
246 !! here are:
247 !! - u - Zonal velocity [m s-1].
248 !! - v - Meridional velocity [m s-1].
249 !! - h - Layer thickness [H ~> m or kg m-2]. (Must be positive.)
250 !! - G%bathyT - Basin depth [Z ~> m]. (Must be positive.)
251 !! - G%CoriolisBu - The Coriolis parameter [T-1 ~> s-1].
252 !! - GV%g_prime - The reduced gravity at each interface [L2 Z-1 T-2 ~> m s-2].
253 !! - GV%Rlay - Layer potential density (coordinate variable) [R ~> kg m-3].
254 !! If ENABLE_THERMODYNAMICS is defined:
255 !! - T - Temperature [degC].
256 !! - S - Salinity [psu].
257 !! If BULKMIXEDLAYER is defined:
258 !! - Rml - Mixed layer and buffer layer potential densities [kg m-3].
259 !! If SPONGE is defined:
260 !! - A series of subroutine calls are made to set up the damping
261 !! rates and reference profiles for all variables that are damped
262 !! in the sponge.
263 !!
264 !! Any user provided tracer code is also first linked through this
265 !! subroutine.
266 !!
267 !! These variables are all set in the set of subroutines (in this
268 !! file) USER_initialize_bottom_depth, USER_initialize_thickness,
269 !! USER_initialize_velocity, USER_initialize_temperature_salinity,
270 !! USER_initialize_mixed_layer_density, USER_initialize_sponges,
271 !! USER_set_coord, and USER_set_ref_profile.
272 !!
273 !! The names of these subroutines should be self-explanatory. They
274 !! start with "USER_" to indicate that they will likely have to be
275 !! modified for each simulation to set the initial conditions and
276 !! boundary conditions. Most of these take two arguments: an integer
277 !! argument specifying whether the fields are to be calculated
278 !! internally or read from a NetCDF file; and a string giving the
279 !! path to that file. If the field is initialized internally, the
280 !! path is ignored.
281 
282 end module user_initialization
user_initialization::user_initialize_sponges
subroutine, public user_initialize_sponges(G, GV, use_temp, tv, param_file, CSp, h)
Set up the sponges.
Definition: user_initialization.F90:171
mom_open_boundary::obc_direction_n
integer, parameter, public obc_direction_n
Indicates the boundary is an effective northern boundary.
Definition: MOM_open_boundary.F90:63
mom_open_boundary::obc_direction_s
integer, parameter, public obc_direction_s
Indicates the boundary is an effective southern boundary.
Definition: MOM_open_boundary.F90:64
mom_verticalgrid
Provides a transparent vertical ocean grid type and supporting routines.
Definition: MOM_verticalGrid.F90:2
user_initialization::user_initialize_thickness
subroutine, public user_initialize_thickness(h, G, GV, param_file, just_read_params)
initialize thicknesses.
Definition: user_initialization.F90:84
mom_sponge::set_up_sponge_field
subroutine, public set_up_sponge_field(sp_val, f_ptr, G, nlay, CS, sp_val_i_mean)
This subroutine stores the reference profile for the variable whose address is given by f_ptr....
Definition: MOM_sponge.F90:214
mom_file_parser::log_version
An overloaded interface to log version information about modules.
Definition: MOM_file_parser.F90:109
mom_variables::thermo_var_ptrs
Pointers to an assortment of thermodynamic fields that may be available, including potential temperat...
Definition: MOM_variables.F90:78
mom_get_input::directories
Container for paths and parameter file names.
Definition: MOM_get_input.F90:20
mom_open_boundary::obc_direction_e
integer, parameter, public obc_direction_e
Indicates the boundary is an effective eastern boundary.
Definition: MOM_open_boundary.F90:65
mom_open_boundary::obc_direction_w
integer, parameter, public obc_direction_w
Indicates the boundary is an effective western boundary.
Definition: MOM_open_boundary.F90:66
mom_open_boundary::obc_simple
integer, parameter, public obc_simple
Indicates the use of a simple inflow open boundary.
Definition: MOM_open_boundary.F90:59
mom_dyn_horgrid
Contains a shareable dynamic type for describing horizontal grids and metric data and utilty routines...
Definition: MOM_dyn_horgrid.F90:3
user_initialization::user_set_obc_data
subroutine, public user_set_obc_data(OBC, tv, G, param_file, tr_Reg)
This subroutine sets the properties of flow at open boundary conditions.
Definition: user_initialization.F90:195
user_initialization::write_user_log
subroutine write_user_log(param_file)
Write output about the parameter values being used.
Definition: user_initialization.F90:228
mom_error_handler::mom_mesg
subroutine, public mom_mesg(message, verb, all_print)
This provides a convenient interface for writing an informative comment.
Definition: MOM_error_handler.F90:53
mom_eos
Provides subroutines for quantities specific to the equation of state.
Definition: MOM_EOS.F90:2
mom_tracer_registry
This module contains the tracer_registry_type and the subroutines that handle registration of tracers...
Definition: MOM_tracer_registry.F90:5
mom_file_parser::param_file_type
A structure that can be parsed to read and document run-time parameters.
Definition: MOM_file_parser.F90:54
mom_file_parser::get_param
An overloaded interface to read and log the values of various types of parameters.
Definition: MOM_file_parser.F90:102
mom_get_input
Reads the only Fortran name list needed to boot-strap the model.
Definition: MOM_get_input.F90:6
mom_unit_scaling::unit_scale_type
Describes various unit conversion factors.
Definition: MOM_unit_scaling.F90:14
user_initialization::user_set_rotation
subroutine, public user_set_rotation(G, param_file)
Definition: user_initialization.F90:216
mom_eos::eos_type
A control structure for the equation of state.
Definition: MOM_EOS.F90:91
mom_verticalgrid::verticalgrid_type
Describes the vertical ocean grid, including unit conversion factors.
Definition: MOM_verticalGrid.F90:24
mom_variables
Provides transparent structures with groups of MOM6 variables and supporting routines.
Definition: MOM_variables.F90:2
user_initialization::user_set_coord
subroutine, public user_set_coord(Rlay, g_prime, GV, US, param_file, eqn_of_state)
Set vertical coordinates.
Definition: user_initialization.F90:41
mom_open_boundary
Controls where open boundary conditions are applied.
Definition: MOM_open_boundary.F90:2
mom_file_parser
The MOM6 facility to parse input files for runtime parameters.
Definition: MOM_file_parser.F90:2
mom_sponge
Implements sponge regions in isopycnal mode.
Definition: MOM_sponge.F90:2
user_initialization::user_initialize_topography
subroutine, public user_initialize_topography(D, G, param_file, max_depth, US)
Initialize topography.
Definition: user_initialization.F90:65
mom_eos::calculate_density_derivs
Calculate the derivatives of density with temperature and salinity from T, S, and P.
Definition: MOM_EOS.F90:70
user_initialization::user_initialize_velocity
subroutine, public user_initialize_velocity(u, v, G, US, param_file, just_read_params)
initialize velocities.
Definition: user_initialization.F90:111
mom_tracer_registry::tracer_registry_type
Type to carry basic tracer information.
Definition: MOM_tracer_registry.F90:138
mom_grid
Provides the ocean grid type.
Definition: MOM_grid.F90:2
mom_open_boundary::ocean_obc_type
Open-boundary data.
Definition: MOM_open_boundary.F90:195
mom_sponge::sponge_cs
This control structure holds memory and parameters for the MOM_sponge module.
Definition: MOM_sponge.F90:41
mom_unit_scaling
Provides a transparent unit rescaling type to facilitate dimensional consistency testing.
Definition: MOM_unit_scaling.F90:2
mom_error_handler::is_root_pe
logical function, public is_root_pe()
This returns .true. if the current PE is the root PE.
Definition: MOM_error_handler.F90:44
mom_error_handler::mom_error
subroutine, public mom_error(level, message, all_print)
This provides a convenient interface for writing an mpp_error message with run-time filter based on a...
Definition: MOM_error_handler.F90:72
user_initialization::user_init_temperature_salinity
subroutine, public user_init_temperature_salinity(T, S, G, param_file, eqn_of_state, just_read_params)
This function puts the initial layer temperatures and salinities into T(:,:,:) and S(:,...
Definition: user_initialization.F90:141
mom_open_boundary::obc_none
integer, parameter, public obc_none
Indicates the use of no open boundary.
Definition: MOM_open_boundary.F90:58
mom_sponge::initialize_sponge
subroutine, public initialize_sponge(Iresttime, int_height, G, param_file, CS, GV, Iresttime_i_mean, int_height_i_mean)
This subroutine determines the number of points which are within sponges in this computational domain...
Definition: MOM_sponge.F90:90
user_initialization::first_call
logical first_call
A module variable that should not be used.
Definition: user_initialization.F90:35
mom_error_handler
Routines for error handling and I/O management.
Definition: MOM_error_handler.F90:2
mom_dyn_horgrid::dyn_horgrid_type
Describes the horizontal ocean grid with only dynamic memory arrays.
Definition: MOM_dyn_horgrid.F90:23
mom_grid::ocean_grid_type
Ocean grid type. See mom_grid for details.
Definition: MOM_grid.F90:26
user_initialization
A template of a user to code up customized initial conditions.
Definition: user_initialization.F90:2
mom_eos::calculate_density
Calculates density of sea water from T, S and P.
Definition: MOM_EOS.F90:60