FMS  2025.04
Flexible Modeling System
data_override.F90
1 !***********************************************************************
2 !* Apache License 2.0
3 !*
4 !* This file is part of the GFDL Flexible Modeling System (FMS).
5 !*
6 !* Licensed under the Apache License, Version 2.0 (the "License");
7 !* you may not use this file except in compliance with the License.
8 !* You may obtain a copy of the License at
9 !*
10 !* http://www.apache.org/licenses/LICENSE-2.0
11 !*
12 !* FMS is distributed in the hope that it will be useful, but WITHOUT
13 !* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied;
14 !* without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
15 !* PARTICULAR PURPOSE. See the License for the specific language
16 !* governing permissions and limitations under the License.
17 !***********************************************************************
18 
19 ! data_override_r4 and data_override_r8 are not intended to be used directly -
20 ! they should be used through the data_override_mod API. The body of
21 ! data_override_r4 and data_override_r8 is contained in data_override.inc.
22 
23 module data_override_r4
24 #include "data_override_r4.fh"
25 end module data_override_r4
26 
27 module data_override_r8
28 #include "data_override_r8.fh"
29 end module data_override_r8
30 
31 !> @defgroup data_override_mod data_override_mod
32 !> @ingroup data_override
33 !! @brief Routines to get data in a file whose path is described in a user-provided data_table
34 !! and do spatial and temporal interpolation if necessary to convert data to model's grid and time.
35 !! @author Z. Liang, M.J. Harrison, M. Winton
36 !!
37 !! Before using @ref data_override a data_table must be created with the following entries:
38 !! gridname, fieldname_code, fieldname_file, file_name, ongrid, factor.
39 !!
40 !! More explainations about data_table entries can be found in the source code (defining data_type)
41 !!
42 !! If user wants to override fieldname_code with a const, set fieldname_file in data_table = ""
43 !! and factor = const
44 !!
45 !! If user wants to override fieldname_code with data from a file, set fieldname_file = name in
46 !! the netCDF data file, factor then will be for unit conversion (=1 if no conversion required)
47 !!
48 !! A field can be overridden globally (by default) or users can specify one or two regions in which
49 !! data_override will take place, field values outside the region will not be affected.
50 
51 module data_override_mod
52  use data_override_r4
53  use data_override_r8
54  use platform_mod, only: r4_kind, r8_kind
55  use mpp_mod, only: mpp_error, fatal
56  use mpp_domains_mod, only : domain2d, domainug
57  use time_manager_mod, only: time_type
58 
59 implicit none
60 private
61 
62 !> Interface for inserting and interpolating data into a file
63 !! for a model's grid and time. Data path must be described in
64 !! a user-provided data_table, see @ref data_override_mod "module description"
65 !! for more information.
66 !> @ingroup data_override_mod
67 interface data_override
68  module procedure data_override_0d_r4
69  module procedure data_override_0d_r8
70  module procedure data_override_2d_r4
71  module procedure data_override_2d_r8
72  module procedure data_override_3d_r4
73  module procedure data_override_3d_r8
74 end interface
75 
76 !> Version of @ref data_override for unstructured grids
77 !> @ingroup data_override_mod
79  module procedure data_override_ug_1d_r4
80  module procedure data_override_ug_1d_r8
81  module procedure data_override_ug_2d_r4
82  module procedure data_override_ug_2d_r8
83 end interface
84 
85 integer, parameter :: mode_r4 = 1 !> Indicates that a domain has been enabled for r4 mode
86 integer, parameter :: mode_r8 = 2 !> Indicates that a domain has been enabled for r8 mode
87 
88 integer :: atm_mode = 0 !> Atmosphere mode: possible values are 0 (uninitialized),
89  !! mode_r4, mode_r8, or ior(mode_r4, mode_r8)
90 integer :: ocn_mode = 0 !> Ocean mode: possible values are 0 (uninitialized),
91  !! mode_r4, mode_r8, or ior(mode_r4, mode_r8)
92 integer :: lnd_mode = 0 !> Land mode: possible values are 0 (uninitialized),
93  !! mode_r4, mode_r8, or ior(mode_r4, mode_r8)
94 integer :: ice_mode = 0 !> Ice mode: possible values are 0 (uninitialized),
95  !! mode_r4, mode_r8, or ior(mode_r4, mode_r8)
96 
97 !> @addtogroup data_override_mod
98 !> @{
99 
101 public :: data_override_ug
102 
103 contains
104 
105 !> @brief Initialize data_override. Users should call data_override_init before
106 !! calling data_override.
107 !!
108 !! This subroutine should be called in coupler_init after
109 !! (ocean/atmos/land/ice)_model_init have been called.
110 !!
111 !! data_override_init can be called more than once. In one call the user can pass
112 !! up to 4 domains of component models. At least one domain must be present in
113 !! any call. The real precision of initialized domains can be specified via the
114 !! optional mode argument. If no mode is specified, both r4 and r8 modes are initialized.
115 !!
116 !! Data_table is initialized with default values in DATA_OVERRIDE_INIT_IMPL_. Users should
117 !! provide "real" values that will override the default values. Real values can be
118 !! specified in either data_table or data_table.yaml. Each line of data_table contains one
119 !! data_entry. Items of data_entry are comma-separated.
120 subroutine data_override_init(Atm_domain_in, Ocean_domain_in, Ice_domain_in, Land_domain_in, Land_domainUG_in, mode)
121  type (domain2d), intent(in), optional :: atm_domain_in !< Atmosphere domain
122  type (domain2d), intent(in), optional :: ocean_domain_in !< Ocean domain
123  type (domain2d), intent(in), optional :: ice_domain_in !< Ice domain
124  type (domain2d), intent(in), optional :: land_domain_in !< Land domain
125  type(domainug) , intent(in), optional :: land_domainug_in !< Land domain, unstructured grid
126  integer, intent(in), optional :: mode !< Real precision of initialized domains. Possible values are r4_kind or
127  !! r8_kind. If omitted, both r4 and r8 modes are initialized.
128  integer :: mode_flags
129 
130  if (present(mode)) then
131  select case(mode)
132  case (r4_kind)
133  mode_flags = mode_r4
134  case (r8_kind)
135  mode_flags = mode_r8
136  case default
137  call mpp_error(fatal, "data_override_init: Unsupported mode argument")
138  end select
139  else
140  mode_flags = ior(mode_r4, mode_r8)
141  endif
142 
143  if (iand(mode_flags, mode_r4).ne.0) then
144  call data_override_init_r4(atm_domain_in, ocean_domain_in, ice_domain_in, land_domain_in, land_domainug_in)
145  endif
146 
147  if (iand(mode_flags, mode_r8).ne.0) then
148  call data_override_init_r8(atm_domain_in, ocean_domain_in, ice_domain_in, land_domain_in, land_domainug_in)
149  endif
150 
151  if (present(atm_domain_in)) atm_mode = ior(atm_mode, mode_flags)
152  if (present(ocean_domain_in)) ocn_mode = ior(ocn_mode, mode_flags)
153  if (present(ice_domain_in)) ice_mode = ior(ice_mode, mode_flags)
154  if (present(land_domain_in)) lnd_mode = ior(lnd_mode, mode_flags)
155 end subroutine data_override_init
156 
157 !> @brief Unset domains that had previously been set for use by data_override.
158 !!
159 !! This subroutine deallocates any data override domains that have been set.
160 subroutine data_override_unset_domains(unset_Atm, unset_Ocean, &
161  unset_Ice, unset_Land, must_be_set)
162  logical, intent(in), optional :: unset_atm, unset_ocean, unset_ice, unset_land !< Set to true to unset the
163  !! respective domain
164  logical, intent(in), optional :: must_be_set !< Set to false to suppress the error when attempting to unset
165  !! an uninitialized domain
166  logical :: fail_if_not_set
167 
168  fail_if_not_set = .true. ; if (present(must_be_set)) fail_if_not_set = must_be_set
169 
170  if (present(unset_atm)) then ; if (unset_atm) then
171  if (atm_mode.eq.0 .and. fail_if_not_set) call mpp_error(fatal, &
172  "data_override_unset_domains: attempted to unset an Atm_domain that has not been set.")
173 
174  if (iand(atm_mode, mode_r4).ne.0) call data_override_unset_atm_r4
175  if (iand(atm_mode, mode_r8).ne.0) call data_override_unset_atm_r8
176 
177  atm_mode = 0
178  endif ; endif
179  if (present(unset_ocean)) then ; if (unset_ocean) then
180  if (ocn_mode.eq.0 .and. fail_if_not_set) call mpp_error(fatal, &
181  "data_override_unset_domains: attempted to unset an Ocn_domain that has not been set.")
182 
183  if (iand(ocn_mode, mode_r4).ne.0) call data_override_unset_ocn_r4
184  if (iand(ocn_mode, mode_r8).ne.0) call data_override_unset_ocn_r8
185 
186  ocn_mode = 0
187  endif ; endif
188  if (present(unset_land)) then ; if (unset_land) then
189  if (lnd_mode.eq.0 .and. fail_if_not_set) call mpp_error(fatal, &
190  "data_override_unset_domains: attempted to unset an Land_domain that has not been set.")
191 
192  if (iand(lnd_mode, mode_r4).ne.0) call data_override_unset_lnd_r4
193  if (iand(lnd_mode, mode_r8).ne.0) call data_override_unset_lnd_r8
194 
195  lnd_mode = 0
196  endif ; endif
197  if (present(unset_ice)) then ; if (unset_ice) then
198  if (ice_mode.eq.0 .and. fail_if_not_set) call mpp_error(fatal, &
199  "data_override_unset_domains: attempted to unset an Ice_domain that has not been set.")
200 
201  if (iand(ice_mode, mode_r4).ne.0) call data_override_unset_ice_r4
202  if (iand(ice_mode, mode_r8).ne.0) call data_override_unset_ice_r8
203 
204  ice_mode = 0
205  endif ; endif
206 end subroutine data_override_unset_domains
207 
208 end module data_override_mod
209 !> @}
210 ! close documentation grouping
subroutine, public data_override_init(Atm_domain_in, Ocean_domain_in, Ice_domain_in, Land_domain_in, Land_domainUG_in, mode)
Initialize data_override. Users should call data_override_init before calling data_override.
subroutine, public data_override_unset_domains(unset_Atm, unset_Ocean, unset_Ice, unset_Land, must_be_set)
Unset domains that had previously been set for use by data_override.
Interface for inserting and interpolating data into a file for a model's grid and time....
Version of Data Override for unstructured grids.
The domain2D type contains all the necessary information to define the global, compute and data domai...
Domain information for managing data on unstructured grids.
Error handler.
Definition: mpp.F90:381
Type to represent amounts of time. Implemented as seconds and days to allow for larger intervals.