MODFLOW 6 version 6.9.0.dev0
USGS Modular Hydrologic Model
Loading...
Searching...
No Matches
meshdisvmodelmodule Module Reference

This module contains the MeshDisvModelModule. More...

Data Types

type  mesh2ddisvexporttype

Functions/Subroutines

subroutine disv_export_init (this, modelname, modeltype, modelfname, nc_fname, disenum, nctype, iout)
 netcdf export disv init
subroutine disv_export_destroy (this)
 netcdf export disv destroy
subroutine df (this)
 netcdf export define
subroutine step (this)
 netcdf export step
subroutine package_step (this, export_pkg)
 netcdf export package dynamic input
subroutine export_input_array (this, pkgtype, pkgname, mempath, idt)
 netcdf export an input array
subroutine define_dim (this)
 netcdf export define dimensions
subroutine add_mesh_data (this)
 netcdf export add mesh information
subroutine nc_export_int1d (p_mem, ncid, dim_ids, var_ids, disv, idt, mempath, nc_tag, pkgname, gridmap_name, deflate, shuffle, chunk_face, iper, nc_fname)
 netcdf export 1D integer array
subroutine nc_export_int2d (p_mem, ncid, dim_ids, var_ids, disv, idt, mempath, nc_tag, pkgname, gridmap_name, deflate, shuffle, chunk_face, nc_fname)
 netcdf export 2D integer array
subroutine nc_export_dbl1d (p_mem, ncid, dim_ids, var_ids, disv, idt, mempath, nc_tag, pkgname, gridmap_name, deflate, shuffle, chunk_face, iper, iaux, nc_fname)
 netcdf export 1D double array
subroutine nc_export_dbl2d (p_mem, ncid, dim_ids, var_ids, disv, idt, mempath, nc_tag, pkgname, gridmap_name, deflate, shuffle, chunk_face, nc_fname)
 netcdf export 2D double array

Detailed Description

This module defines UGRID layered mesh compliant netcdf export type for DISV models. It is dependent on netcdf libraries.

Function/Subroutine Documentation

◆ add_mesh_data()

subroutine meshdisvmodelmodule::add_mesh_data ( class(mesh2ddisvexporttype), intent(inout) this)
private

Definition at line 473 of file DisvNCMesh.f90.

475 class(Mesh2dDisvExportType), intent(inout) :: this
476 integer(I4B), dimension(:), contiguous, pointer :: ncvert => null()
477 integer(I4B), dimension(:), contiguous, pointer :: icvert => null()
478 real(DP), dimension(:), contiguous, pointer :: cell_xt => null()
479 real(DP), dimension(:), contiguous, pointer :: cell_yt => null()
480 real(DP), dimension(:), contiguous, pointer :: vert_xt => null()
481 real(DP), dimension(:), contiguous, pointer :: vert_yt => null()
482 real(DP) :: x_transform, y_transform
483 integer(I4B) :: n, m, idx, cnt, iv, maxvert, k
484 integer(I4B), dimension(:), allocatable :: verts, layers
485 real(DP), dimension(:), allocatable :: bnds
486 real(DP), dimension(:), allocatable :: elev_face
487 integer(I4B) :: istop
488
489 ! set pointers to input context
490 call mem_setptr(ncvert, 'NCVERT', this%dis_mempath)
491 call mem_setptr(icvert, 'ICVERT', this%dis_mempath)
492
493 ! allocate x, y transform arrays
494 allocate (cell_xt(this%disv%ncpl))
495 allocate (cell_yt(this%disv%ncpl))
496 allocate (vert_xt(this%disv%nvert))
497 allocate (vert_yt(this%disv%nvert))
498
499 ! set mesh container variable value to 1
500 call nf_verify(nf90_put_var(this%ncid, this%var_ids%mesh, 1), &
501 this%nc_fname)
502
503 ! write layer coordinate data
504 allocate (layers(this%nlay))
505 do k = 1, this%nlay
506 layers(k) = k
507 end do
508 call nf_verify(nf90_put_var(this%ncid, this%var_ids%layer, layers), &
509 this%nc_fname)
510 deallocate (layers)
511
512 ! transform vert x and y
513 do n = 1, this%disv%nvert
514 call dis_transform_xy(this%disv%vertices(1, n), this%disv%vertices(2, n), &
515 this%disv%xorigin, &
516 this%disv%yorigin, &
517 this%disv%angrot, &
518 x_transform, y_transform)
519 vert_xt(n) = x_transform
520 vert_yt(n) = y_transform
521 end do
522
523 ! transform cell x and y
524 do n = 1, this%disv%ncpl
525 call dis_transform_xy(this%disv%cellxy(1, n), this%disv%cellxy(2, n), &
526 this%disv%xorigin, &
527 this%disv%yorigin, &
528 this%disv%angrot, &
529 x_transform, y_transform)
530 cell_xt(n) = x_transform
531 cell_yt(n) = y_transform
532 end do
533
534 ! write node_x and node_y arrays to netcdf file
535 call nf_verify(nf90_put_var(this%ncid, this%var_ids%mesh_node_x, &
536 vert_xt), this%nc_fname)
537 call nf_verify(nf90_put_var(this%ncid, this%var_ids%mesh_node_y, &
538 vert_yt), this%nc_fname)
539
540 ! write face_x and face_y arrays to netcdf file
541 call nf_verify(nf90_put_var(this%ncid, this%var_ids%mesh_face_x, &
542 cell_xt), this%nc_fname)
543 call nf_verify(nf90_put_var(this%ncid, this%var_ids%mesh_face_y, &
544 cell_yt), this%nc_fname)
545
546 ! set and write z_l1, z_l2, ... cell center elevation arrays -- already
547 ! face-indexed (ncpl), no flattening needed, unlike DIS-mesh
548 allocate (elev_face(this%disv%ncpl))
549 do k = 1, this%nlay
550 if (k == 1) then
551 elev_face(:) = (this%disv%top1d(:) + this%disv%bot2d(:, k)) * dhalf
552 else
553 elev_face(:) = (this%disv%bot2d(:, k - 1) + &
554 this%disv%bot2d(:, k)) * dhalf
555 end if
556 call nf_verify(nf90_put_var(this%ncid, this%var_ids%elevation(k), &
557 elev_face), this%nc_fname)
558 end do
559 deallocate (elev_face)
560
561 ! initialize max vertices required to define cell
562 maxvert = maxval(ncvert)
563
564 ! allocate temporary arrays
565 allocate (verts(maxvert))
566 allocate (bnds(maxvert))
567
568 ! set face nodes array
569 cnt = 0
570 do n = 1, this%disv%ncpl
571 verts = nf90_fill_int
572 idx = cnt + ncvert(n)
573 iv = 0
574 istop = cnt + 1
575 do m = idx, istop, -1
576 cnt = cnt + 1
577 iv = iv + 1
578 verts(iv) = icvert(m)
579 end do
580
581 ! don't close the cell
582 if (verts(iv) == verts(1)) verts(iv) = nf90_fill_int
583
584 ! write face nodes array to netcdf file
585 call nf_verify(nf90_put_var(this%ncid, this%var_ids%mesh_face_nodes, &
586 verts, start=(/1, n/), &
587 count=(/maxvert, 1/)), &
588 this%nc_fname)
589
590 ! set face y bounds array
591 bnds = nf90_fill_double
592 do m = 1, size(bnds)
593 if (verts(m) /= nf90_fill_int) then
594 bnds(m) = vert_yt(verts(m))
595 end if
596 ! write face y bounds array to netcdf file
597 call nf_verify(nf90_put_var(this%ncid, this%var_ids%mesh_face_ybnds, &
598 bnds, start=(/1, n/), &
599 count=(/maxvert, 1/)), &
600 this%nc_fname)
601 end do
602
603 ! set face x bounds array
604 bnds = nf90_fill_double
605 do m = 1, size(bnds)
606 if (verts(m) /= nf90_fill_int) then
607 bnds(m) = vert_xt(verts(m))
608 end if
609 ! write face x bounds array to netcdf file
610 call nf_verify(nf90_put_var(this%ncid, this%var_ids%mesh_face_xbnds, &
611 bnds, start=(/1, n/), &
612 count=(/maxvert, 1/)), &
613 this%nc_fname)
614 end do
615 end do
616
617 ! cleanup
618 deallocate (bnds)
619 deallocate (verts)
620 deallocate (cell_xt)
621 deallocate (cell_yt)
622 deallocate (vert_xt)
623 deallocate (vert_yt)
subroutine, public dis_transform_xy(x, y, xorigin, yorigin, angrot, xglo, yglo)
Get global (x, y) coordinates from cell-local coordinates.
Here is the call graph for this function:

◆ define_dim()

subroutine meshdisvmodelmodule::define_dim ( class(mesh2ddisvexporttype), intent(inout) this)
private

Definition at line 374 of file DisvNCMesh.f90.

375 use constantsmodule, only: mvalidate
377 class(Mesh2dDisvExportType), intent(inout) :: this
378 integer(I4B), dimension(:), contiguous, pointer :: ncvert
379 integer(I4B) :: k
380 character(len=LINELENGTH) :: varname
381 character(len=LINELENGTH) :: elev_longname
382
383 ! set pointers to input context
384 call mem_setptr(ncvert, 'NCVERT', this%dis_mempath)
385
386 if (isim_mode /= mvalidate .or. this%pkglist%Count() > 0) then
387 ! time
388 call nf_verify(nf90_def_dim(this%ncid, 'time', this%totnstp, &
389 this%dim_ids%time), this%nc_fname)
390 call nf_verify(nf90_def_var(this%ncid, 'time', nf90_double, &
391 this%dim_ids%time, this%var_ids%time), &
392 this%nc_fname)
393 call nf_verify(nf90_put_att(this%ncid, this%var_ids%time, 'calendar', &
394 'standard'), this%nc_fname)
395 call nf_verify(nf90_put_att(this%ncid, this%var_ids%time, 'units', &
396 this%datetime), this%nc_fname)
397 call nf_verify(nf90_put_att(this%ncid, this%var_ids%time, 'axis', 'T'), &
398 this%nc_fname)
399 call nf_verify(nf90_put_att(this%ncid, this%var_ids%time, 'standard_name', &
400 'time'), this%nc_fname)
401 call nf_verify(nf90_put_att(this%ncid, this%var_ids%time, 'long_name', &
402 'time'), this%nc_fname)
403 ! stress period bounds of the time coordinate (CF-1.13 7.1)
404 if (isim_mode == mvalidate) then
405 call nf_verify(nf90_def_dim(this%ncid, 'bnd', 2, this%dim_ids%bnd), &
406 this%nc_fname)
407 call nf_verify(nf90_put_att(this%ncid, this%var_ids%time, 'bounds', &
408 'time_bnds'), this%nc_fname)
409 call nf_verify(nf90_def_var(this%ncid, 'time_bnds', nf90_double, &
410 (/this%dim_ids%bnd, this%dim_ids%time/), &
411 this%var_ids%time_bnds), this%nc_fname)
412 end if
413 end if
414
415 ! mesh
416 call nf_verify(nf90_def_dim(this%ncid, 'nmesh_node', this%disv%nvert, &
417 this%dim_ids%nmesh_node), this%nc_fname)
418 call nf_verify(nf90_def_dim(this%ncid, 'nmesh_face', this%disv%ncpl, &
419 this%dim_ids%nmesh_face), this%nc_fname)
420 call nf_verify(nf90_def_dim(this%ncid, 'max_nmesh_face_nodes', &
421 maxval(ncvert), &
422 this%dim_ids%max_nmesh_face_nodes), &
423 this%nc_fname)
424
425 ! layer
426 call nf_verify(nf90_def_dim(this%ncid, 'layer', this%nlay, &
427 this%dim_ids%layer), this%nc_fname)
428 call nf_verify(nf90_def_var(this%ncid, 'layer', nf90_int, &
429 this%dim_ids%layer, this%var_ids%layer), &
430 this%nc_fname)
431 call nf_verify(nf90_put_att(this%ncid, this%var_ids%layer, 'units', '1'), &
432 this%nc_fname)
433 call nf_verify(nf90_put_att(this%ncid, this%var_ids%layer, 'axis', 'Z'), &
434 this%nc_fname)
435 call nf_verify(nf90_put_att(this%ncid, this%var_ids%layer, 'positive', &
436 'down'), this%nc_fname)
437 call nf_verify(nf90_put_att(this%ncid, this%var_ids%layer, 'long_name', &
438 'model layer'), this%nc_fname)
439
440 ! z_l1, z_l2, ... : per-layer cell center elevation auxiliary
441 ! coordinates -- real vertical position, unlike the discrete layer
442 ! index. Always written, independent of CRS/NCF configuration; split
443 ! per layer since face-indexed variables carry no layer dimension to
444 ! legally reference a combined z(layer, nmesh_face) coordinate
445 ! (CF-1.13 5.2).
446 allocate (this%var_ids%elevation(this%nlay))
447 do k = 1, this%nlay
448 write (varname, '(a,i0)') 'z_l', k
449 call nf_verify(nf90_def_var(this%ncid, trim(varname), nf90_double, &
450 (/this%dim_ids%nmesh_face/), &
451 this%var_ids%elevation(k)), this%nc_fname)
452 call ncvar_chunk(this%ncid, this%var_ids%elevation(k), this%chunk_face, &
453 this%nc_fname)
454 call ncvar_deflate(this%ncid, this%var_ids%elevation(k), this%deflate, &
455 this%shuffle, this%nc_fname)
456 call nf_verify(nf90_put_att(this%ncid, this%var_ids%elevation(k), &
457 'units', this%lenunits), this%nc_fname)
458 call nf_verify(nf90_put_att(this%ncid, this%var_ids%elevation(k), &
459 'standard_name', 'altitude'), this%nc_fname)
460 call nf_verify(nf90_put_att(this%ncid, this%var_ids%elevation(k), &
461 'positive', 'up'), this%nc_fname)
462 write (elev_longname, '(a,i0,a)') 'cell center elevation (layer ', &
463 k, ')'
464 call nf_verify(nf90_put_att(this%ncid, this%var_ids%elevation(k), &
465 'long_name', trim(elev_longname)), &
466 this%nc_fname)
467 call ncvar_layer(this%ncid, this%var_ids%elevation(k), k, this%nc_fname)
468 end do
This module contains simulation constants.
Definition Constants.f90:9
@ mvalidate
validation mode - do not run time steps
This module contains simulation variables.
integer(i4b) isim_mode
simulation mode
Here is the call graph for this function:

◆ df()

subroutine meshdisvmodelmodule::df ( class(mesh2ddisvexporttype), intent(inout) this)
private

Definition at line 84 of file DisvNCMesh.f90.

85 use constantsmodule, only: mvalidate
87 class(Mesh2dDisvExportType), intent(inout) :: this
88 ! put root group file scope attributes
89 call this%add_global_att()
90 ! define root group dimensions and coordinate variables
91 call this%define_dim()
92 ! define mesh variables
93 call this%create_mesh()
94 if (isim_mode == mvalidate) then
95 ! define period input arrays
96 call this%df_export()
97 else
98 ! define the dependent variable
99 call this%define_dependent()
100 end if
101 ! exit define mode
102 call nf_verify(nf90_enddef(this%ncid), this%nc_fname)
103 ! create mesh
104 call this%add_mesh_data()
105 if (isim_mode == mvalidate) then
106 ! define and set package input griddata
107 call this%add_pkg_data()
108 end if
109 ! define and set gridmap variable
110 call this%define_gridmap()
111 ! synchronize file
112 call nf_verify(nf90_sync(this%ncid), this%nc_fname)
Here is the call graph for this function:

◆ disv_export_destroy()

subroutine meshdisvmodelmodule::disv_export_destroy ( class(mesh2ddisvexporttype), intent(inout) this)
private

Definition at line 74 of file DisvNCMesh.f90.

75 class(Mesh2dDisvExportType), intent(inout) :: this
76 deallocate (this%var_ids%dependent)
77 ! destroy base class
78 call this%mesh_destroy()
79 call this%NCModelExportType%destroy()

◆ disv_export_init()

subroutine meshdisvmodelmodule::disv_export_init ( class(mesh2ddisvexporttype), intent(inout) this,
character(len=*), intent(in) modelname,
character(len=*), intent(in) modeltype,
character(len=*), intent(in) modelfname,
character(len=*), intent(in) nc_fname,
integer(i4b), intent(in) disenum,
integer(i4b), intent(in) nctype,
integer(i4b), intent(in) iout )

Definition at line 48 of file DisvNCMesh.f90.

51 class(Mesh2dDisvExportType), intent(inout) :: this
52 character(len=*), intent(in) :: modelname
53 character(len=*), intent(in) :: modeltype
54 character(len=*), intent(in) :: modelfname
55 character(len=*), intent(in) :: nc_fname
56 integer(I4B), intent(in) :: disenum
57 integer(I4B), intent(in) :: nctype
58 integer(I4B), intent(in) :: iout
59
60 ! set nlay
61 this%nlay = this%disv%nlay
62
63 ! allocate var_id arrays
64 allocate (this%var_ids%dependent(this%nlay))
65 allocate (this%var_ids%export(this%nlay))
66
67 ! initialize base class
68 call this%mesh_init(modelname, modeltype, modelfname, nc_fname, disenum, &
69 nctype, this%disv%lenuni, iout)

◆ export_input_array()

subroutine meshdisvmodelmodule::export_input_array ( class(mesh2ddisvexporttype), intent(inout) this,
character(len=*), intent(in) pkgtype,
character(len=*), intent(in) pkgname,
character(len=*), intent(in) mempath,
type(inputparamdefinitiontype), intent(in), pointer idt )
private

Definition at line 323 of file DisvNCMesh.f90.

324 class(Mesh2dDisvExportType), intent(inout) :: this
325 character(len=*), intent(in) :: pkgtype
326 character(len=*), intent(in) :: pkgname
327 character(len=*), intent(in) :: mempath
328 type(InputParamDefinitionType), pointer, intent(in) :: idt
329 integer(I4B), dimension(:), pointer, contiguous :: int1d
330 integer(I4B), dimension(:, :), pointer, contiguous :: int2d
331 real(DP), dimension(:), pointer, contiguous :: dbl1d
332 real(DP), dimension(:, :), pointer, contiguous :: dbl2d
333 character(len=LINELENGTH) :: nc_tag
334 integer(I4B) :: iper, iaux
335
336 iper = 0
337 iaux = 0
338
339 ! set variable input tag
340 nc_tag = this%input_attribute(pkgname, idt)
341
342 select case (idt%datatype)
343 case ('INTEGER1D')
344 call mem_setptr(int1d, idt%mf6varname, mempath)
345 call nc_export_int1d(int1d, this%ncid, this%dim_ids, this%var_ids, &
346 this%disv, idt, mempath, nc_tag, pkgname, &
347 this%gridmap_name, this%deflate, this%shuffle, &
348 this%chunk_face, iper, this%nc_fname)
349 case ('INTEGER2D')
350 call mem_setptr(int2d, idt%mf6varname, mempath)
351 call nc_export_int2d(int2d, this%ncid, this%dim_ids, this%var_ids, &
352 this%disv, idt, mempath, nc_tag, pkgname, &
353 this%gridmap_name, this%deflate, this%shuffle, &
354 this%chunk_face, this%nc_fname)
355 case ('DOUBLE1D')
356 call mem_setptr(dbl1d, idt%mf6varname, mempath)
357 call nc_export_dbl1d(dbl1d, this%ncid, this%dim_ids, this%var_ids, &
358 this%disv, idt, mempath, nc_tag, pkgname, &
359 this%gridmap_name, this%deflate, this%shuffle, &
360 this%chunk_face, iper, iaux, this%nc_fname)
361 case ('DOUBLE2D')
362 call mem_setptr(dbl2d, idt%mf6varname, mempath)
363 call nc_export_dbl2d(dbl2d, this%ncid, this%dim_ids, this%var_ids, &
364 this%disv, idt, mempath, nc_tag, pkgname, &
365 this%gridmap_name, this%deflate, this%shuffle, &
366 this%chunk_face, this%nc_fname)
367 case default
368 ! no-op, no other datatypes exported
369 end select
Here is the call graph for this function:

◆ nc_export_dbl1d()

subroutine meshdisvmodelmodule::nc_export_dbl1d ( real(dp), dimension(:), intent(in), pointer, contiguous p_mem,
integer(i4b), intent(in) ncid,
type(meshncdimidtype), intent(inout) dim_ids,
type(meshncvaridtype), intent(inout) var_ids,
type(disvtype), intent(in), pointer disv,
type(inputparamdefinitiontype), pointer idt,
character(len=*), intent(in) mempath,
character(len=*), intent(in) nc_tag,
character(len=*), intent(in) pkgname,
character(len=*), intent(in) gridmap_name,
integer(i4b), intent(in) deflate,
integer(i4b), intent(in) shuffle,
integer(i4b), intent(in) chunk_face,
integer(i4b), intent(in) iper,
integer(i4b), intent(in) iaux,
character(len=*), intent(in) nc_fname )
private

Definition at line 823 of file DisvNCMesh.f90.

826 use tdismodule, only: kper
827 real(DP), dimension(:), pointer, contiguous, intent(in) :: p_mem
828 integer(I4B), intent(in) :: ncid
829 type(MeshNCDimIdType), intent(inout) :: dim_ids
830 type(MeshNCVarIdType), intent(inout) :: var_ids
831 type(DisvType), pointer, intent(in) :: disv
832 type(InputParamDefinitionType), pointer :: idt
833 character(len=*), intent(in) :: mempath
834 character(len=*), intent(in) :: nc_tag
835 character(len=*), intent(in) :: pkgname
836 character(len=*), intent(in) :: gridmap_name
837 integer(I4B), intent(in) :: deflate
838 integer(I4B), intent(in) :: shuffle
839 integer(I4B), intent(in) :: chunk_face
840 integer(I4B), intent(in) :: iper
841 integer(I4B), intent(in) :: iaux
842 character(len=*), intent(in) :: nc_fname
843 real(DP), dimension(:), pointer, contiguous :: dbl1d
844 real(DP), dimension(:, :), pointer, contiguous :: dbl2d
845 integer(I4B) :: axis_sz, k
846 integer(I4B), dimension(:), allocatable :: var_id
847 character(len=LINELENGTH) :: longname, varname
848
849 if (idt%shape == 'NCPL' .or. &
850 idt%shape == 'NAUX NCPL') then
851
852 if (iper == 0) then
853 ! set names
854 varname = export_varname(pkgname, idt%tagname, mempath, &
855 iaux=iaux)
856 longname = export_longname(idt%longname, pkgname, idt%tagname, &
857 mempath, iaux=iaux, &
858 component_type=idt%component_type, &
859 subcomponent_type=idt%subcomponent_type)
860
861 allocate (var_id(1))
862 axis_sz = dim_ids%nmesh_face
863
864 ! reenter define mode and create variable
865 call nf_verify(nf90_redef(ncid), nc_fname)
866 call nf_verify(nf90_def_var(ncid, varname, nf90_double, &
867 (/axis_sz/), var_id(1)), &
868 nc_fname)
869
870 ! apply chunking parameters
871 call ncvar_chunk(ncid, var_id(1), chunk_face, nc_fname)
872 ! deflate and shuffle
873 call ncvar_deflate(ncid, var_id(1), deflate, shuffle, nc_fname)
874
875 ! put attr
876 call nf_verify(nf90_put_att(ncid, var_id(1), '_FillValue', &
877 (/nf90_fill_double/)), nc_fname)
878 call nf_verify(nf90_put_att(ncid, var_id(1), 'long_name', &
879 longname), nc_fname)
880
881 ! add grid mapping and mf6 attr
882 call ncvar_gridmap(ncid, var_id(1), gridmap_name, 0, nc_fname)
883 call ncvar_mf6attr(ncid, var_id(1), 0, iaux, nc_tag, nc_fname)
884
885 ! exit define mode and write data
886 call nf_verify(nf90_enddef(ncid), nc_fname)
887 call nf_verify(nf90_put_var(ncid, var_id(1), p_mem), &
888 nc_fname)
889 else
890 ! timeseries
891 call nf_verify(nf90_put_var(ncid, &
892 var_ids%export(1), p_mem, &
893 start=(/1, kper/), &
894 count=(/disv%ncpl, 1/)), nc_fname)
895 end if
896
897 else
898
899 dbl2d(1:disv%ncpl, 1:disv%nlay) => p_mem(1:disv%nodesuser)
900
901 if (iper == 0) then
902 allocate (var_id(disv%nlay))
903
904 ! reenter define mode and create variable
905 call nf_verify(nf90_redef(ncid), nc_fname)
906 do k = 1, disv%nlay
907 ! set names
908 varname = export_varname(pkgname, idt%tagname, mempath, layer=k, &
909 iaux=iaux)
910 longname = export_longname(idt%longname, pkgname, idt%tagname, &
911 mempath, layer=k, iaux=iaux, &
912 component_type=idt%component_type, &
913 subcomponent_type=idt%subcomponent_type)
914
915 call nf_verify(nf90_def_var(ncid, varname, nf90_double, &
916 (/dim_ids%nmesh_face/), var_id(k)), &
917 nc_fname)
918
919 ! apply chunking parameters
920 call ncvar_chunk(ncid, var_id(k), chunk_face, nc_fname)
921 ! deflate and shuffle
922 call ncvar_deflate(ncid, var_id(k), deflate, shuffle, nc_fname)
923
924 ! put attr
925 call nf_verify(nf90_put_att(ncid, var_id(k), '_FillValue', &
926 (/nf90_fill_double/)), nc_fname)
927 call nf_verify(nf90_put_att(ncid, var_id(k), 'long_name', &
928 longname), nc_fname)
929
930 ! add grid mapping and mf6 attr
931 call ncvar_gridmap(ncid, var_id(k), gridmap_name, k, nc_fname)
932 call ncvar_mf6attr(ncid, var_id(k), k, iaux, nc_tag, nc_fname)
933 end do
934
935 ! exit define mode and write data
936 call nf_verify(nf90_enddef(ncid), nc_fname)
937 do k = 1, disv%nlay
938 call nf_verify(nf90_put_var(ncid, var_id(k), dbl2d(:, k)), nc_fname)
939 end do
940
941 ! cleanup
942 deallocate (var_id)
943 else
944 ! timeseries, add period data
945 do k = 1, disv%nlay
946 dbl1d(1:disv%ncpl) => dbl2d(:, k)
947 call nf_verify(nf90_put_var(ncid, &
948 var_ids%export(k), dbl1d, &
949 start=(/1, kper/), &
950 count=(/disv%ncpl, 1/)), nc_fname)
951 end do
952 end if
953 end if
integer(i4b), pointer, public kper
current stress period number
Definition tdis.f90:26
Here is the call graph for this function:
Here is the caller graph for this function:

◆ nc_export_dbl2d()

subroutine meshdisvmodelmodule::nc_export_dbl2d ( real(dp), dimension(:, :), intent(in), pointer, contiguous p_mem,
integer(i4b), intent(in) ncid,
type(meshncdimidtype), intent(inout) dim_ids,
type(meshncvaridtype), intent(inout) var_ids,
type(disvtype), intent(in), pointer disv,
type(inputparamdefinitiontype), pointer idt,
character(len=*), intent(in) mempath,
character(len=*), intent(in) nc_tag,
character(len=*), intent(in) pkgname,
character(len=*), intent(in) gridmap_name,
integer(i4b), intent(in) deflate,
integer(i4b), intent(in) shuffle,
integer(i4b), intent(in) chunk_face,
character(len=*), intent(in) nc_fname )
private

Definition at line 958 of file DisvNCMesh.f90.

961 real(DP), dimension(:, :), pointer, contiguous, intent(in) :: p_mem
962 integer(I4B), intent(in) :: ncid
963 type(MeshNCDimIdType), intent(inout) :: dim_ids
964 type(MeshNCVarIdType), intent(inout) :: var_ids
965 type(DisvType), pointer, intent(in) :: disv
966 type(InputParamDefinitionType), pointer :: idt
967 character(len=*), intent(in) :: mempath
968 character(len=*), intent(in) :: nc_tag
969 character(len=*), intent(in) :: pkgname
970 character(len=*), intent(in) :: gridmap_name
971 integer(I4B), intent(in) :: deflate
972 integer(I4B), intent(in) :: shuffle
973 integer(I4B), intent(in) :: chunk_face
974 character(len=*), intent(in) :: nc_fname
975 integer(I4B), dimension(:), allocatable :: var_id
976 character(len=LINELENGTH) :: longname, varname
977 integer(I4B) :: k
978
979 allocate (var_id(disv%nlay))
980
981 ! reenter define mode and create variable
982 call nf_verify(nf90_redef(ncid), nc_fname)
983 do k = 1, disv%nlay
984 ! set names
985 varname = export_varname(pkgname, idt%tagname, mempath, layer=k)
986 longname = export_longname(idt%longname, pkgname, idt%tagname, &
987 mempath, layer=k, &
988 component_type=idt%component_type, &
989 subcomponent_type=idt%subcomponent_type)
990
991 call nf_verify(nf90_def_var(ncid, varname, nf90_double, &
992 (/dim_ids%nmesh_face/), var_id(k)), &
993 nc_fname)
994
995 ! apply chunking parameters
996 call ncvar_chunk(ncid, var_id(k), chunk_face, nc_fname)
997 ! deflate and shuffle
998 call ncvar_deflate(ncid, var_id(k), deflate, shuffle, nc_fname)
999
1000 ! put attr
1001 call nf_verify(nf90_put_att(ncid, var_id(k), '_FillValue', &
1002 (/nf90_fill_double/)), nc_fname)
1003 call nf_verify(nf90_put_att(ncid, var_id(k), 'long_name', &
1004 longname), nc_fname)
1005
1006 ! add grid mapping and mf6 attr
1007 call ncvar_gridmap(ncid, var_id(k), gridmap_name, k, nc_fname)
1008 call ncvar_mf6attr(ncid, var_id(k), k, 0, nc_tag, nc_fname)
1009 end do
1010
1011 ! exit define mode and write data
1012 call nf_verify(nf90_enddef(ncid), nc_fname)
1013 do k = 1, disv%nlay
1014 call nf_verify(nf90_put_var(ncid, var_id(k), p_mem(:, k)), nc_fname)
1015 end do
1016
1017 deallocate (var_id)
Here is the call graph for this function:
Here is the caller graph for this function:

◆ nc_export_int1d()

subroutine meshdisvmodelmodule::nc_export_int1d ( integer(i4b), dimension(:), intent(in), pointer, contiguous p_mem,
integer(i4b), intent(in) ncid,
type(meshncdimidtype), intent(inout) dim_ids,
type(meshncvaridtype), intent(inout) var_ids,
type(disvtype), intent(in), pointer disv,
type(inputparamdefinitiontype), pointer idt,
character(len=*), intent(in) mempath,
character(len=*), intent(in) nc_tag,
character(len=*), intent(in) pkgname,
character(len=*), intent(in) gridmap_name,
integer(i4b), intent(in) deflate,
integer(i4b), intent(in) shuffle,
integer(i4b), intent(in) chunk_face,
integer(i4b), intent(in) iper,
character(len=*), intent(in) nc_fname )
private

Definition at line 628 of file DisvNCMesh.f90.

631 use tdismodule, only: kper
632 integer(I4B), dimension(:), pointer, contiguous, intent(in) :: p_mem
633 integer(I4B), intent(in) :: ncid
634 type(MeshNCDimIdType), intent(inout) :: dim_ids
635 type(MeshNCVarIdType), intent(inout) :: var_ids
636 type(DisvType), pointer, intent(in) :: disv
637 type(InputParamDefinitionType), pointer :: idt
638 character(len=*), intent(in) :: mempath
639 character(len=*), intent(in) :: nc_tag
640 character(len=*), intent(in) :: pkgname
641 character(len=*), intent(in) :: gridmap_name
642 integer(I4B), intent(in) :: deflate
643 integer(I4B), intent(in) :: shuffle
644 integer(I4B), intent(in) :: chunk_face
645 integer(I4B), intent(in) :: iper
646 character(len=*), intent(in) :: nc_fname
647 integer(I4B), dimension(:), pointer, contiguous :: int1d
648 integer(I4B), dimension(:, :), pointer, contiguous :: int2d
649 integer(I4B) :: axis_sz, k
650 integer(I4B), dimension(:), allocatable :: var_id
651 character(len=LINELENGTH) :: longname, varname
652
653 if (idt%shape == 'NCPL' .or. &
654 idt%shape == 'NAUX NCPL') then
655
656 if (iper == 0) then
657 ! set names
658 varname = export_varname(pkgname, idt%tagname, mempath)
659 longname = export_longname(idt%longname, pkgname, idt%tagname, mempath, &
660 component_type=idt%component_type, &
661 subcomponent_type=idt%subcomponent_type)
662
663 allocate (var_id(1))
664 axis_sz = dim_ids%nmesh_face
665
666 ! reenter define mode and create variable
667 call nf_verify(nf90_redef(ncid), nc_fname)
668 call nf_verify(nf90_def_var(ncid, varname, nf90_int, &
669 (/axis_sz/), var_id(1)), &
670 nc_fname)
671
672 ! apply chunking parameters
673 call ncvar_chunk(ncid, var_id(1), chunk_face, nc_fname)
674 ! deflate and shuffle
675 call ncvar_deflate(ncid, var_id(1), deflate, shuffle, nc_fname)
676
677 ! put attr
678 call nf_verify(nf90_put_att(ncid, var_id(1), '_FillValue', &
679 (/nf90_fill_int/)), nc_fname)
680 call nf_verify(nf90_put_att(ncid, var_id(1), 'long_name', &
681 longname), nc_fname)
682
683 ! add grid mapping and mf6 attr
684 call ncvar_gridmap(ncid, var_id(1), gridmap_name, 0, nc_fname)
685 call ncvar_mf6attr(ncid, var_id(1), 0, 0, nc_tag, nc_fname)
686
687 ! exit define mode and write data
688 call nf_verify(nf90_enddef(ncid), nc_fname)
689 call nf_verify(nf90_put_var(ncid, var_id(1), p_mem), &
690 nc_fname)
691 else
692 ! timeseries
693 call nf_verify(nf90_put_var(ncid, &
694 var_ids%export(1), p_mem, &
695 start=(/1, kper/), &
696 count=(/disv%ncpl, 1/)), nc_fname)
697 end if
698
699 else
700
701 int2d(1:disv%ncpl, 1:disv%nlay) => p_mem(1:disv%nodesuser)
702
703 if (iper == 0) then
704 allocate (var_id(disv%nlay))
705
706 ! reenter define mode and create variable
707 call nf_verify(nf90_redef(ncid), nc_fname)
708 do k = 1, disv%nlay
709 ! set names
710 varname = export_varname(pkgname, idt%tagname, mempath, layer=k)
711 longname = export_longname(idt%longname, pkgname, idt%tagname, &
712 mempath, layer=k, &
713 component_type=idt%component_type, &
714 subcomponent_type=idt%subcomponent_type)
715
716 call nf_verify(nf90_def_var(ncid, varname, nf90_int, &
717 (/dim_ids%nmesh_face/), var_id(k)), &
718 nc_fname)
719
720 ! apply chunking parameters
721 call ncvar_chunk(ncid, var_id(k), chunk_face, nc_fname)
722 ! deflate and shuffle
723 call ncvar_deflate(ncid, var_id(k), deflate, shuffle, nc_fname)
724
725 ! put attr
726 call nf_verify(nf90_put_att(ncid, var_id(k), '_FillValue', &
727 (/nf90_fill_int/)), nc_fname)
728 call nf_verify(nf90_put_att(ncid, var_id(k), 'long_name', &
729 longname), nc_fname)
730
731 ! add grid mapping and mf6 attr
732 call ncvar_gridmap(ncid, var_id(k), gridmap_name, k, nc_fname)
733 call ncvar_mf6attr(ncid, var_id(k), k, 0, nc_tag, nc_fname)
734 end do
735
736 ! exit define mode and write data
737 call nf_verify(nf90_enddef(ncid), nc_fname)
738 do k = 1, disv%nlay
739 call nf_verify(nf90_put_var(ncid, var_id(k), int2d(:, k)), nc_fname)
740 end do
741
742 ! cleanup
743 deallocate (var_id)
744 else
745 ! timeseries, add period data
746 do k = 1, disv%nlay
747 int1d(1:disv%ncpl) => int2d(:, k)
748 call nf_verify(nf90_put_var(ncid, &
749 var_ids%export(k), int1d, &
750 start=(/1, kper/), &
751 count=(/disv%ncpl, 1/)), nc_fname)
752 end do
753 end if
754 end if
Here is the call graph for this function:
Here is the caller graph for this function:

◆ nc_export_int2d()

subroutine meshdisvmodelmodule::nc_export_int2d ( integer(i4b), dimension(:, :), intent(in), pointer, contiguous p_mem,
integer(i4b), intent(in) ncid,
type(meshncdimidtype), intent(inout) dim_ids,
type(meshncvaridtype), intent(inout) var_ids,
type(disvtype), intent(in), pointer disv,
type(inputparamdefinitiontype), pointer idt,
character(len=*), intent(in) mempath,
character(len=*), intent(in) nc_tag,
character(len=*), intent(in) pkgname,
character(len=*), intent(in) gridmap_name,
integer(i4b), intent(in) deflate,
integer(i4b), intent(in) shuffle,
integer(i4b), intent(in) chunk_face,
character(len=*), intent(in) nc_fname )
private

Definition at line 759 of file DisvNCMesh.f90.

762 integer(I4B), dimension(:, :), pointer, contiguous, intent(in) :: p_mem
763 integer(I4B), intent(in) :: ncid
764 type(MeshNCDimIdType), intent(inout) :: dim_ids
765 type(MeshNCVarIdType), intent(inout) :: var_ids
766 type(DisvType), pointer, intent(in) :: disv
767 type(InputParamDefinitionType), pointer :: idt
768 character(len=*), intent(in) :: mempath
769 character(len=*), intent(in) :: nc_tag
770 character(len=*), intent(in) :: pkgname
771 character(len=*), intent(in) :: gridmap_name
772 integer(I4B), intent(in) :: deflate
773 integer(I4B), intent(in) :: shuffle
774 integer(I4B), intent(in) :: chunk_face
775 character(len=*), intent(in) :: nc_fname
776 integer(I4B), dimension(:), allocatable :: var_id
777 character(len=LINELENGTH) :: longname, varname
778 integer(I4B) :: k
779
780 allocate (var_id(disv%nlay))
781
782 ! reenter define mode and create variable
783 call nf_verify(nf90_redef(ncid), nc_fname)
784 do k = 1, disv%nlay
785 ! set names
786 varname = export_varname(pkgname, idt%tagname, mempath, layer=k)
787 longname = export_longname(idt%longname, pkgname, idt%tagname, &
788 mempath, layer=k, &
789 component_type=idt%component_type, &
790 subcomponent_type=idt%subcomponent_type)
791
792 call nf_verify(nf90_def_var(ncid, varname, nf90_int, &
793 (/dim_ids%nmesh_face/), var_id(k)), &
794 nc_fname)
795
796 ! apply chunking parameters
797 call ncvar_chunk(ncid, var_id(k), chunk_face, nc_fname)
798 ! deflate and shuffle
799 call ncvar_deflate(ncid, var_id(k), deflate, shuffle, nc_fname)
800
801 ! put attr
802 call nf_verify(nf90_put_att(ncid, var_id(k), '_FillValue', &
803 (/nf90_fill_int/)), nc_fname)
804 call nf_verify(nf90_put_att(ncid, var_id(k), 'long_name', &
805 longname), nc_fname)
806
807 ! add grid mapping and mf6 attr
808 call ncvar_gridmap(ncid, var_id(k), gridmap_name, k, nc_fname)
809 call ncvar_mf6attr(ncid, var_id(k), k, 0, nc_tag, nc_fname)
810 end do
811
812 ! exit define mode and write data
813 call nf_verify(nf90_enddef(ncid), nc_fname)
814 do k = 1, disv%nlay
815 call nf_verify(nf90_put_var(ncid, var_id(k), p_mem(:, k)), nc_fname)
816 end do
817
818 deallocate (var_id)
Here is the call graph for this function:
Here is the caller graph for this function:

◆ package_step()

subroutine meshdisvmodelmodule::package_step ( class(mesh2ddisvexporttype), intent(inout) this,
class(exportpackagetype), intent(in), pointer export_pkg )
private

Definition at line 184 of file DisvNCMesh.f90.

185 use tdismodule, only: totim, kper, perlen
188 class(Mesh2dDisvExportType), intent(inout) :: this
189 class(ExportPackageType), pointer, intent(in) :: export_pkg
190 type(InputParamDefinitionType), pointer :: idt
191 integer(I4B), dimension(:), pointer, contiguous :: int1d
192 real(DP), dimension(:), pointer, contiguous :: dbl1d, nodes
193 real(DP), dimension(:, :), pointer, contiguous :: dbl2d
194 character(len=LINELENGTH) :: nc_tag
195 integer(I4B) :: iaux, iparam, nvals
196 integer(I4B) :: k, n
197
198 ! initialize
199 iaux = 0
200
201 ! update input in effect for this period
202 call export_pkg%update_state()
203
204 ! export period input in effect
205 do iparam = 1, export_pkg%nparam
206 ! check if variable has input in effect
207 if (.not. export_pkg%param_state(iparam)) cycle
208
209 ! set input definition
210 idt => &
211 get_param_definition_type(export_pkg%mf6_input%param_dfns, &
212 export_pkg%mf6_input%component_type, &
213 export_pkg%mf6_input%subcomponent_type, &
214 'PERIOD', export_pkg%param_names(iparam), '')
215
216 ! set variable input tag
217 nc_tag = this%input_attribute(export_pkg%mf6_input%subcomponent_name, &
218 idt)
219
220 ! export arrays
221 select case (idt%datatype)
222 case ('INTEGER1D')
223 call mem_setptr(int1d, idt%mf6varname, export_pkg%mf6_input%mempath)
224 this%var_ids%export(1) = export_pkg%varids_param(iparam, 1)
225 call nc_export_int1d(int1d, this%ncid, this%dim_ids, this%var_ids, &
226 this%disv, idt, export_pkg%mf6_input%mempath, &
227 nc_tag, export_pkg%mf6_input%subcomponent_name, &
228 this%gridmap_name, this%deflate, this%shuffle, &
229 this%chunk_face, kper, this%nc_fname)
230 case ('DOUBLE1D')
231 call mem_setptr(dbl1d, idt%mf6varname, export_pkg%mf6_input%mempath)
232 select case (idt%shape)
233 case ('NCPL')
234 this%var_ids%export(1) = export_pkg%varids_param(iparam, 1)
235 call nc_export_dbl1d(dbl1d, this%ncid, this%dim_ids, this%var_ids, &
236 this%disv, idt, export_pkg%mf6_input%mempath, &
237 nc_tag, export_pkg%mf6_input%subcomponent_name, &
238 this%gridmap_name, this%deflate, this%shuffle, &
239 this%chunk_face, kper, iaux, this%nc_fname)
240 case ('NODES')
241 nvals = this%disv%nodesuser
242 allocate (nodes(nvals))
243 nodes = dnodata
244 do k = 1, this%disv%nlay
245 this%var_ids%export(k) = export_pkg%varids_param(iparam, k)
246 end do
247 call mem_setptr(dbl1d, idt%mf6varname, export_pkg%mf6_input%mempath)
248 call export_pkg%user_nodes(dbl1d, nodes)
249 call nc_export_dbl1d(nodes, this%ncid, this%dim_ids, this%var_ids, &
250 this%disv, idt, export_pkg%mf6_input%mempath, &
251 nc_tag, export_pkg%mf6_input%subcomponent_name, &
252 this%gridmap_name, this%deflate, this%shuffle, &
253 this%chunk_face, kper, iaux, this%nc_fname)
254 deallocate (nodes)
255 case default
256 end select
257 case ('DOUBLE2D')
258 call mem_setptr(dbl2d, idt%mf6varname, export_pkg%mf6_input%mempath)
259 select case (idt%shape)
260 case ('NAUX NCPL')
261 nvals = this%disv%ncpl
262 allocate (nodes(nvals))
263 do iaux = 1, size(dbl2d, dim=1) !naux
264 if (.not. export_pkg%aux_state(iaux)) cycle
265 this%var_ids%export(1) = export_pkg%varids_aux(iaux, 1)
266 do n = 1, nvals
267 nodes(n) = dbl2d(iaux, n)
268 end do
269 call nc_export_dbl1d(nodes, this%ncid, this%dim_ids, this%var_ids, &
270 this%disv, idt, export_pkg%mf6_input%mempath, &
271 nc_tag, export_pkg%mf6_input%subcomponent_name, &
272 this%gridmap_name, this%deflate, this%shuffle, &
273 this%chunk_face, kper, iaux, this%nc_fname)
274 end do
275 deallocate (nodes)
276 case ('NAUX NODES')
277 nvals = this%disv%nodesuser
278 allocate (nodes(nvals))
279 do iaux = 1, size(dbl2d, dim=1) ! naux
280 if (.not. export_pkg%aux_state(iaux)) cycle
281 nodes = dnodata
282 do k = 1, this%disv%nlay
283 this%var_ids%export(k) = export_pkg%varids_aux(iaux, k)
284 end do
285 call export_pkg%user_nodes(dbl2d(iaux, :), nodes)
286 call nc_export_dbl1d(nodes, this%ncid, this%dim_ids, this%var_ids, &
287 this%disv, idt, export_pkg%mf6_input%mempath, &
288 nc_tag, export_pkg%mf6_input%subcomponent_name, &
289 this%gridmap_name, this%deflate, this%shuffle, &
290 this%chunk_face, kper, iaux, this%nc_fname)
291 end do
292 deallocate (nodes)
293 case default
294 end select
295 case default
296 ! no-op, no other datatypes exported
297 end select
298 end do
299
300 ! write to time coordinate variable
301 call nf_verify(nf90_put_var(this%ncid, this%var_ids%time, &
302 totim, start=(/kper/)), &
303 this%nc_fname)
304
305 ! write stress period time bounds; the period start is also the end
306 ! of the previous period
307 call nf_verify(nf90_put_var(this%ncid, this%var_ids%time_bnds, &
308 (/totim, totim + perlen(kper)/), &
309 start=(/1, kper/), count=(/2, 1/)), &
310 this%nc_fname)
311 if (kper > 1) then
312 call nf_verify(nf90_put_var(this%ncid, this%var_ids%time_bnds, &
313 totim, start=(/2, kper - 1/)), &
314 this%nc_fname)
315 end if
316
317 ! synchronize file
318 call nf_verify(nf90_sync(this%ncid), this%nc_fname)
This module contains the DefinitionSelectModule.
type(inputparamdefinitiontype) function, pointer, public get_param_definition_type(input_definition_types, component_type, subcomponent_type, blockname, tagname, filename, found)
Return parameter definition.
This module contains the NCModelExportModule.
Definition NCModel.f90:8
real(dp), dimension(:), pointer, public, contiguous perlen
length of each stress period
Definition tdis.f90:41
real(dp), pointer, public totim
time relative to start of simulation
Definition tdis.f90:35
Here is the call graph for this function:

◆ step()

subroutine meshdisvmodelmodule::step ( class(mesh2ddisvexporttype), intent(inout) this)
private

Definition at line 117 of file DisvNCMesh.f90.

118 use constantsmodule, only: dhnoflo
119 use tdismodule, only: totim
120 class(Mesh2dDisvExportType), intent(inout) :: this
121 real(DP), dimension(:), pointer, contiguous :: dbl1d
122 integer(I4B) :: n, k, nvals, istp
123 integer(I4B), dimension(2) :: dis_shape
124 real(DP), dimension(:, :), pointer, contiguous :: dbl2d
125
126 ! initialize
127 nullify (dbl1d)
128 nullify (dbl2d)
129
130 ! set global step index
131 istp = this%istp()
132
133 dis_shape(1) = this%disv%ncpl
134 dis_shape(2) = this%disv%nlay
135
136 nvals = product(dis_shape)
137
138 ! add data to dependent variable
139 if (size(this%disv%nodeuser) < &
140 size(this%disv%nodereduced)) then
141 ! allocate nodereduced size 1d array
142 allocate (dbl1d(size(this%disv%nodereduced)))
143
144 ! initialize DHNOFLO for non-active cells
145 dbl1d = dhnoflo
146
147 ! update active cells
148 do n = 1, size(this%disv%nodereduced)
149 if (this%disv%nodereduced(n) > 0) then
150 dbl1d(n) = this%x(this%disv%nodereduced(n))
151 end if
152 end do
153
154 dbl2d(1:dis_shape(1), 1:dis_shape(2)) => dbl1d(1:nvals)
155 else
156 dbl2d(1:dis_shape(1), 1:dis_shape(2)) => this%x(1:nvals)
157 end if
158
159 do k = 1, this%disv%nlay
160 ! extend array with step data
161 call nf_verify(nf90_put_var(this%ncid, &
162 this%var_ids%dependent(k), dbl2d(:, k), &
163 start=(/1, istp/), &
164 count=(/this%disv%ncpl, 1/)), &
165 this%nc_fname)
166 end do
167
168 ! write to time coordinate variable
169 call nf_verify(nf90_put_var(this%ncid, this%var_ids%time, &
170 totim, start=(/istp/)), &
171 this%nc_fname)
172
173 ! update file
174 call nf_verify(nf90_sync(this%ncid), this%nc_fname)
175
176 ! cleanup
177 if (associated(dbl1d)) deallocate (dbl1d)
178 nullify (dbl1d)
179 nullify (dbl2d)
real(dp), parameter dhnoflo
real no flow constant
Definition Constants.f90:93
Here is the call graph for this function: