FMS  2024.03
Flexible Modeling System
fms_io_unstructured_read.inc
1 !***********************************************************************
2 !* GNU Lesser General Public License
3 !*
4 !* This file is part of the GFDL Flexible Modeling System (FMS).
5 !*
6 !* FMS is free software: you can redistribute it and/or modify it under
7 !* the terms of the GNU Lesser General Public License as published by
8 !* the Free Software Foundation, either version 3 of the License, or (at
9 !* your option) any later version.
10 !*
11 !* FMS is distributed in the hope that it will be useful, but WITHOUT
12 !* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 !* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 !* for more details.
15 !*
16 !* You should have received a copy of the GNU Lesser General Public
17 !* License along with FMS. If not, see <http://www.gnu.org/licenses/>.
18 !***********************************************************************
19 !----------
20 !ug support
21 !> @ingroup fms_io_mod
22 !> @{
23 
24 !------------------------------------------------------------------------------
25 !>Read in a scalar field from a file associated with an unstructured mpp
26 !!domain.
27 subroutine fms_io_unstructured_read_r_scalar(filename, &
28  fieldname, &
29  fdata, &
30  domain, &
31  timelevel, &
32  start, &
33  nread, &
34  threading)
35 
36  !Inputs/Outputs
37  character(len=*),intent(in) :: filename !<The name of a file.
38  character(len=*),intent(in) :: fieldname !<The name of field in the input file.
39  real,intent(inout) :: fdata !<Data to be read in from the file.
40  type(domainug),intent(in) :: domain !<Unstructured mpp domain associated with the input file.
41  integer,intent(in),optional :: timelevel !<Time level at which the data is read in.
42  integer,dimension(:),intent(in),optional :: start !<NetCDF "Corner" indices for the data.
43  integer,dimension(:),intent(in),optional :: nread !<NetCDF "edge lengths" for the data.
44  integer,intent(in),optional :: threading !<Threading flag.
45 
46  !Local variables
47  real,dimension(1) :: tmp !<Dummy variable.
48  integer :: tlevel !<Dummy variable.
49 
50  !Use the 1D case.
51  if (present(timelevel)) then
52  if (tlevel .le. 0) then
53  call mpp_error(fatal, &
54  "fms_io_unstructured_read_r_scalar:" &
55  //" the inputted time level must be at" &
56  //" least one.")
57  endif
58  tlevel = timelevel
59  else
60  tlevel = 1
61  endif
62  call fms_io_unstructured_read_r_1d(filename, &
63  fieldname, &
64  tmp, &
65  domain, &
66  tlevel, &
67  start, &
68  nread, &
69  threading)
70  fdata = tmp(1)
71 
72  return
73 end subroutine fms_io_unstructured_read_r_scalar
74 
75 !------------------------------------------------------------------------------
76 !>Read in a one dimensional "compressed" field from a file associated with
77 !!an unstructured mpp domain.
78 subroutine fms_io_unstructured_read_r_1d(filename, &
79  fieldname, &
80  fdata, &
81  domain, &
82  timelevel, &
83  start, &
84  nread, &
85  threading)
86 
87  !Inputs/Outputs
88  character(len=*),intent(in) :: filename !<The name of a file.
89  character(len=*),intent(in) :: fieldname !<The name of field in the input file.
90  real,dimension(:),intent(inout) :: fdata !<Data to be read in from the file.
91  type(domainug),intent(in) :: domain !<Unstructured mpp domain associated with the input file.
92  integer,intent(in),optional :: timelevel !<Time level at which the data is read in.
93  integer,dimension(:),intent(in),optional :: start !<NetCDF "Corner" indices for the data.
94  integer,dimension(:),intent(in),optional :: nread !<NetCDF "edge lengths" for the data.
95  integer,intent(in),optional :: threading !<Threading flag.
96 
97  !Local variables
98  logical(INT_KIND) :: found_file !<Flag telling if the input file or any of its variants exist.
99  character(len=256) :: fname !<Name of file that is actually found.
100  logical(INT_KIND) :: read_dist !<Flag telling if the file is "distributed" (has I/O
101  !! domain tile id appended onto the end).
102  integer(INT_KIND) :: funit !<File unit for the inputted file.
103  integer(INT_KIND) :: file_index !<Index of the inputted file in the "files_read" module array.
104  integer(INT_KIND) :: index_field !<Index of the inputted field in the files_read(file_index)%var array.
105 
106  !Make sure that the module has been initialized.
107  if (.not. module_is_initialized) then
108  call mpp_error(fatal, &
109  "fms_io_unstructured_read_r_1D:" &
110  //" you must first call fms_io_init.")
111  endif
112 
113  !Get the full name of the input file.
114  found_file = fms_io_unstructured_get_file_name(filename, &
115  fname, &
116  read_dist, &
117  domain)
118 
119  !If the file does not exit, then throw a fatal error.
120  if (.not. found_file) then
121  call mpp_error(fatal, &
122  "fms_io_unstructured_read_r_1D:" &
123  //" file "//trim(filename) &
124  //" (with the consideration of the domain tile ids)" &
125  //" was not found.")
126  endif
127 
128  !Get the file unit and in the index of the file in the "files_read" module
129  !array.
130  call fms_io_unstructured_get_file_unit(fname, &
131  funit, &
132  file_index, &
133  read_dist, &
134  domain)
135 
136  !Get the index of the inputted field in the files_read(file_index)%var
137  !array.
138  call get_field_id(funit, &
139  file_index, &
140  fieldname, &
141  index_field, &
142  .false., &
143  .false.)
144 
145  !Read in the field data.
146  if (files_read(file_index)%var(index_field)%is_dimvar) then
147  call mpp_get_axis_data(files_read(file_index)%var(index_field)%axis, &
148  fdata)
149  else
150  call mpp_io_unstructured_read(funit, &
151  files_read(file_index)%var(index_field)%field, &
152  domain, &
153  fdata, &
154  timelevel, &
155  start, &
156  nread, &
157  threading)
158  endif
159 
160  return
161 end subroutine fms_io_unstructured_read_r_1d
162 
163 !------------------------------------------------------------------------------
164 !>Read in a two dimensional "compressed" field from a file associated with
165 !!an unstructured mpp domain.
166 subroutine fms_io_unstructured_read_r_2d(filename, &
167  fieldname, &
168  fdata, &
169  domain, &
170  timelevel, &
171  start, &
172  nread, &
173  threading)
174 
175  !Inputs/Outputs
176  character(len=*),intent(in) :: filename !<The name of a file.
177  character(len=*),intent(in) :: fieldname !<The name of field in the input file.
178  real,dimension(:,:),intent(inout) :: fdata !<Data to be read in from the file.
179  type(domainug),intent(in) :: domain !<Unstructured mpp domain associated with the input file.
180  integer,intent(in),optional :: timelevel !<Time level at which the data is read in.
181  integer,dimension(:),intent(in),optional :: start !<NetCDF "Corner" indices for the data.
182  integer,dimension(:),intent(in),optional :: nread !<NetCDF "edge lengths" for the data.
183  integer,intent(in),optional :: threading !<Threading flag.
184 
185  !Local variables
186  logical(INT_KIND) :: found_file !<Flag telling if the input file or any of its variants exist.
187  character(len=256) :: fname !<Name of file that is actually found.
188  logical(INT_KIND) :: read_dist !<Flag telling if the file is "distributed" (has I/O
189  !! domain tile id appended onto the end).
190  integer(INT_KIND) :: funit !<File unit for the inputted file.
191  integer(INT_KIND) :: file_index !<Index of the inputted file in the "files_read" module array.
192  integer(INT_KIND) :: index_field !<Index of the inputted field in the files_read(file_index)%var array.
193 
194  !Make sure that the module has been initialized.
195  if (.not. module_is_initialized) then
196  call mpp_error(fatal, &
197  "fms_io_unstructured_read_r_2D:" &
198  //" you must first call fms_io_init.")
199  endif
200 
201  !Get the full name of the input file.
202  found_file = fms_io_unstructured_get_file_name(filename, &
203  fname, &
204  read_dist, &
205  domain)
206 
207  !If the file does not exit, then throw a fatal error.
208  if (.not. found_file) then
209  call mpp_error(fatal, &
210  "fms_io_unstructured_read_r_2D:" &
211  //" file "//trim(filename) &
212  //" (with the consideration of the domain tile ids)" &
213  //" was not found.")
214  endif
215 
216  !Get the file unit and in the index of the file in the "files_read" module
217  !array.
218  call fms_io_unstructured_get_file_unit(fname, &
219  funit, &
220  file_index, &
221  read_dist, &
222  domain)
223 
224  !Get the index of the inputted field in the files_read(file_index)%var
225  !array.
226  call get_field_id(funit, &
227  file_index, &
228  fieldname, &
229  index_field, &
230  .false., &
231  .false.)
232 
233  !Read in the field data.
234  if (files_read(file_index)%var(index_field)%is_dimvar) then
235  call mpp_get_axis_data(files_read(file_index)%var(index_field)%axis, &
236  fdata(:,1))
237  else
238  call mpp_io_unstructured_read(funit, &
239  files_read(file_index)%var(index_field)%field, &
240  domain, &
241  fdata, &
242  timelevel, &
243  start, &
244  nread, &
245  threading)
246  endif
247 
248  return
249 end subroutine fms_io_unstructured_read_r_2d
250 
251 !------------------------------------------------------------------------------
252 !>Read in a three dimensional "compressed" field from a file associated with
253 !!an unstructured mpp domain.
254 subroutine fms_io_unstructured_read_r_3d(filename, &
255  fieldname, &
256  fdata, &
257  domain, &
258  timelevel, &
259  start, &
260  nread, &
261  threading)
262 
263  !Inputs/Outputs
264  character(len=*),intent(in) :: filename !<The name of a file.
265  character(len=*),intent(in) :: fieldname !<The name of field in the input file.
266  real,dimension(:,:,:),intent(inout) :: fdata !<Data to be read in from the file.
267  type(domainug),intent(in) :: domain !<Unstructured mpp domain associated with the input file.
268  integer,intent(in),optional :: timelevel !<Time level at which the data is read in.
269  integer,dimension(:),intent(in),optional :: start !<NetCDF "Corner" indices for the data.
270  integer,dimension(:),intent(in),optional :: nread !<NetCDF "edge lengths" for the data.
271  integer,intent(in),optional :: threading !<Threading flag.
272 
273  !Local variables
274  logical(INT_KIND) :: found_file !<Flag telling if the input file or any of its variants exist.
275  character(len=256) :: fname !<Name of file that is actually found.
276  logical(INT_KIND) :: read_dist !<Flag telling if the file is "distributed" (has I/O
277  !! domain tile id appended onto the end).
278  integer(INT_KIND) :: funit !<File unit for the inputted file.
279  integer(INT_KIND) :: file_index !<Index of the inputted file in the "files_read" module array.
280  integer(INT_KIND) :: index_field !<Index of the inputted field in the files_read(file_index)%var array.
281 
282  !Make sure that the module has been initialized.
283  if (.not. module_is_initialized) then
284  call mpp_error(fatal, &
285  "fms_io_unstructured_read_r_3D:" &
286  //" you must first call fms_io_init.")
287  endif
288 
289  !Get the full name of the input file.
290  found_file = fms_io_unstructured_get_file_name(filename, &
291  fname, &
292  read_dist, &
293  domain)
294 
295  !If the file does not exit, then throw a fatal error.
296  if (.not. found_file) then
297  call mpp_error(fatal, &
298  "fms_io_unstructured_read_r_3D:" &
299  //" file "//trim(filename) &
300  //" (with the consideration of the domain tile ids)" &
301  //" was not found.")
302  endif
303 
304  !Get the file unit and in the index of the file in the "files_read" module
305  !array.
306  call fms_io_unstructured_get_file_unit(fname, &
307  funit, &
308  file_index, &
309  read_dist, &
310  domain)
311 
312  !Get the index of the inputted field in the files_read(file_index)%var
313  !array.
314  call get_field_id(funit, &
315  file_index, &
316  fieldname, &
317  index_field, &
318  .false., &
319  .false.)
320 
321  !Read in the field data.
322  if (files_read(file_index)%var(index_field)%is_dimvar) then
323  call mpp_get_axis_data(files_read(file_index)%var(index_field)%axis, &
324  fdata(:,1,1))
325  else
326  call mpp_io_unstructured_read(funit, &
327  files_read(file_index)%var(index_field)%field, &
328  domain, &
329  fdata, &
330  timelevel, &
331  start, &
332  nread, &
333  threading)
334  endif
335 
336  return
337 end subroutine fms_io_unstructured_read_r_3d
338 
339 !------------------------------------------------------------------------------
340 !>Read in a scalar field from a file associated with an unstructured mpp
341 !!domain.
342 subroutine fms_io_unstructured_read_i_scalar(filename, &
343  fieldname, &
344  fdata, &
345  domain, &
346  timelevel, &
347  start, &
348  nread, &
349  threading)
350 
351  !Inputs/Outputs
352  character(len=*),intent(in) :: filename !<The name of a file.
353  character(len=*),intent(in) :: fieldname !<The name of field in the input file.
354  integer,intent(inout) :: fdata !<Data to be read in from the file.
355  type(domainug),intent(in) :: domain !<Unstructured mpp domain associated with the input file.
356  integer,intent(in),optional :: timelevel !<Time level at which the data is read in.
357  integer,dimension(:),intent(in),optional :: start !<NetCDF "Corner" indices for the data.
358  integer,dimension(:),intent(in),optional :: nread !<NetCDF "edge lengths" for the data.
359  integer,intent(in),optional :: threading !<Threading flag.
360 
361  !Local variables
362  real,dimension(1) :: tmp !<Dummy variable.
363  integer :: tlevel !<Dummy variable.
364 
365  !Read in the data.
366  if (present(timelevel)) then
367  if (tlevel .le. 0) then
368  call mpp_error(fatal, &
369  "fms_io_unstructured_read_i_scalar:" &
370  //" the inputted time level must be at" &
371  //" least one.")
372  endif
373  tlevel = timelevel
374  else
375  tlevel = 1
376  endif
377  call fms_io_unstructured_read_r_1d(filename, &
378  fieldname, &
379  tmp, &
380  domain, &
381  tlevel, &
382  start, &
383  nread, &
384  threading)
385  fdata = ceiling(tmp(1))
386 
387  return
388 end subroutine fms_io_unstructured_read_i_scalar
389 
390 !------------------------------------------------------------------------------
391 !>Read in a one dimensional "compressed" field from a file associated with
392 !!an unstructured mpp domain.
393 subroutine fms_io_unstructured_read_i_1d(filename, &
394  fieldname, &
395  fdata, &
396  domain, &
397  timelevel, &
398  start, &
399  nread, &
400  threading)
401 
402  !Inputs/Outputs
403  character(len=*),intent(in) :: filename !<The name of a file.
404  character(len=*),intent(in) :: fieldname !<The name of field in the input file.
405  integer,dimension(:),intent(inout) :: fdata !<Data to be read in from the file.
406  type(domainug),intent(in) :: domain !<Unstructured mpp domain associated with the input file.
407  integer,intent(in),optional :: timelevel !<Time level at which the data is read in.
408  integer,dimension(:),intent(in),optional :: start !<NetCDF "Corner" indices for the data.
409  integer,dimension(:),intent(in),optional :: nread !<NetCDF "edge lengths" for the data.
410  integer,intent(in),optional :: threading !<Threading flag.
411 
412  !Local variables
413  real,dimension(size(fdata)) :: tmp !<Dummy variable.
414  integer(INT_KIND) :: i !<Loop variable.
415 
416  !Read in the data.
417  call fms_io_unstructured_read_r_1d(filename, &
418  fieldname, &
419  tmp, &
420  domain, &
421  timelevel, &
422  start, &
423  nread, &
424  threading)
425  do i = 1,size(fdata)
426  fdata(i) = ceiling(tmp(i))
427  enddo
428 
429  return
430 end subroutine fms_io_unstructured_read_i_1d
431 
432 !------------------------------------------------------------------------------
433 !>Read in a two dimensional "compressed" field from a file associated with
434 !!an unstructured mpp domain.
435 subroutine fms_io_unstructured_read_i_2d(filename, &
436  fieldname, &
437  fdata, &
438  domain, &
439  timelevel, &
440  start, &
441  nread, &
442  threading)
443 
444  !Inputs/Outputs
445  character(len=*),intent(in) :: filename !<The name of a file.
446  character(len=*),intent(in) :: fieldname !<The name of field in the input file.
447  integer,dimension(:,:),intent(inout) :: fdata !<Data to be read in from the file.
448  type(domainug),intent(in) :: domain !<Unstructured mpp domain associated with the input file.
449  integer,intent(in),optional :: timelevel !<Time level at which the data is read in.
450  integer,dimension(:),intent(in),optional :: start !<NetCDF "Corner" indices for the data.
451  integer,dimension(:),intent(in),optional :: nread !<NetCDF "edge lengths" for the data.
452  integer,intent(in),optional :: threading !<Threading flag.
453 
454  !Local variables
455  real,dimension(size(fdata,1),size(fdata,2)) :: tmp !<Dummy variable.
456  integer(INT_KIND) :: i !<Loop variable.
457  integer(INT_KIND) :: j !<Loop variable.
458 
459  !Read in the data.
460  call fms_io_unstructured_read_r_2d(filename, &
461  fieldname, &
462  tmp, &
463  domain, &
464  timelevel, &
465  start, &
466  nread, &
467  threading)
468  do i = 1,size(fdata,2)
469  do j = 1,size(fdata,1)
470  fdata(j,i) = ceiling(tmp(j,i))
471  enddo
472  enddo
473 
474  return
475 end subroutine fms_io_unstructured_read_i_2d
476 !> @}
fms_io_unstructured_read_r_2d
subroutine fms_io_unstructured_read_r_2d(filename, fieldname, fdata, domain, timelevel, start, nread, threading)
Read in a two dimensional "compressed" field from a file associated with an unstructured mpp domain.
Definition: fms_io_unstructured_read.inc:174
fms_io_unstructured_read_i_scalar
subroutine fms_io_unstructured_read_i_scalar(filename, fieldname, fdata, domain, timelevel, start, nread, threading)
Read in a scalar field from a file associated with an unstructured mpp domain.
Definition: fms_io_unstructured_read.inc:350
fms_io_unstructured_read_r_1d
subroutine fms_io_unstructured_read_r_1d(filename, fieldname, fdata, domain, timelevel, start, nread, threading)
Read in a one dimensional "compressed" field from a file associated with an unstructured mpp domain.
Definition: fms_io_unstructured_read.inc:86
fms_io_unstructured_get_file_name
logical(int_kind) function fms_io_unstructured_get_file_name(orig_file, actual_file, read_dist, domain)
For an inputted file name, check if it or any of its variants exist. For a file named "foo",...
Definition: fms_io_unstructured_get_file_name.inc:50
fms_io_unstructured_read_r_scalar
subroutine fms_io_unstructured_read_r_scalar(filename, fieldname, fdata, domain, timelevel, start, nread, threading)
Read in a scalar field from a file associated with an unstructured mpp domain.
Definition: fms_io_unstructured_read.inc:35
fms_io_unstructured_read_i_2d
subroutine fms_io_unstructured_read_i_2d(filename, fieldname, fdata, domain, timelevel, start, nread, threading)
Read in a two dimensional "compressed" field from a file associated with an unstructured mpp domain.
Definition: fms_io_unstructured_read.inc:443
fms_io_unstructured_get_file_unit
subroutine fms_io_unstructured_get_file_unit(filename, funit, index_file, read_dist, domain)
Return the file unit and index in the "files_read" module array for the inputted file....
Definition: fms_io_unstructured_get_file_unit.inc:32
fms_io_unstructured_read_r_3d
subroutine fms_io_unstructured_read_r_3d(filename, fieldname, fdata, domain, timelevel, start, nread, threading)
Read in a three dimensional "compressed" field from a file associated with an unstructured mpp domain...
Definition: fms_io_unstructured_read.inc:262
fms_io_unstructured_read_i_1d
subroutine fms_io_unstructured_read_i_1d(filename, fieldname, fdata, domain, timelevel, start, nread, threading)
Read in a one dimensional "compressed" field from a file associated with an unstructured mpp domain.
Definition: fms_io_unstructured_read.inc:401