Assumed-shape vs explicit-shape arrays when calling Fortran code

[Andris-R]

Dear AMReX community,

I am new to AMReX, having previously worked with PARAMESH for CFD applications, and I am currently evaluating AMReX as a potential alternative framework. I’ve been going through the AMReX Fortran interface documentation and tutorial examples, and I had a question about a design choice that I’m trying to understand better.

In many routines, instead of using assumed-shape arrays in modern Fortran, AMReX passes both the data pointer and explicit index bounds (including bounds with and without ghost cells). . For example, in the HeatEquation_EX1_F tutorial:

  call amrex_mfiter_build(mfi, old_phi, tiling=.true.)
  do while (mfi%next())
     bx = mfi%tilebox()
     po => old_phi%dataptr(mfi)
     pn => new_phi%dataptr(mfi)
     plo = lbound(po)
     phi = ubound(po)
     select case (amrex_spacedim)
     case (2)
        call update_phi_2d(bx%lo, bx%hi, po, pn, plo, phi, dx, dt)
     case (3)
        call update_phi_3d(bx%lo, bx%hi, po, pn, plo, phi, dx, dt)
     end select
  end do
  call amrex_mfiter_destroy(mfi)

and the corresponding subroutine:

subroutine update_phi_2d (lo, hi, pold, pnew, plo, phi, dx, dt)
  integer, intent(in) :: lo(2), hi(2), plo(2), phi(2)
  real(amrex_real), intent(in   ) :: pold(plo(1):phi(1), plo(2):phi(2))
  real(amrex_real), intent(inout) :: pnew(plo(1):phi(1), plo(2):phi(2))
  real(amrex_real), intent(in) :: dx, dt
  ...
end subroutine update_phi_2d

My question is: what is the rationale for preferring explicit-shape arrays with explicitly passed bounds over assumed-shape arrays ((:,:)) in this context? Is this mainly due to interoperability constraints (bind(C)) with the C++ AMReX data structures (e.g., Box, Array4, FArrayBox), or are there additional considerations such as performance, compiler behavior, or control over array descriptors and aliasing?

I understand that some form of bounds information (e.g., n, nguard) would need to be passed regardless in a box-based AMR setting, so the question is specifically about why the explicit-shape/explicit-bound Fortran interface is preferred over assumed-shape arrays.

Any insight into the design choice would be appreciated.

[WeiqunZhang]

We tend to use explicit-shape arrays because (1) a lot of functions were called from C++ side (2) many functions were initially written before assumed-shape array was introduced in Fortran (3) its performance advantage in certain cases.

[Andris-R]

Thanks for the quick reply!

Comments on your points:

1. This makes perfect sense, because assumed-shape arrays are not interoperable with C/C++.
2. Assumed-shape arrays were introduced in Fortran 90. I assume that by “functions” you mean application codes such as FVM or FEM codes written in F77.
3. Could you elaborate on which cases you are referring to?

[WeiqunZhang]

This is just my personal opinion. Assumed-shape array lacks transparency and it makes it harder for a programmer to know what's happening. So I would avoid it by default.

When it sees a function with an assumed-shape array argument, the compiler cannot assume the array has unit stride. So it makes vectorization difficult. One could add contiguous to the argument to force the compiler to treat it as contiguous. The compiler might also do that even without the contiguous keyword. But the consequence of that is the compiler will silently do deep-copy if your provided array is not contiguous.

[Andris-R]

One approach using modern Fortran would be to use assumed-shape arrays with remapped lower bounds, so that the physical region (spanning from lo to hi) always starts at index 1. The following example demonstrates this, under two assumptions:

1. pold and pnew have the same number of guard cells ngx and ngy
2. There are equal numbers of guard cells on both sides in the x and y directions, respectively

subroutine update_phi_2d(ngx, ngy, dx, dt, pold, pnew)

  use fvheat__const_mod, RWP => fvheat_RWP
    !! Precision defined in public module and set to amrex_real at compile time

  implicit none

  integer, intent(in) :: ngx, ngy
  real(RWP), intent(in) :: dx, dt

  real(RWP), intent(in)    :: pold(1-ngx:, 1-ngy:)
  real(RWP), intent(inout) :: pnew(1-ngx:, 1-ngy:)

  integer :: nx, ny
  integer :: i, j

  nx = size(pnew, 1) - 2*ngx
  ny = size(pnew, 2) - 2*ngy

  do j = 1, ny
    do i = 1, nx
      ! update stencil here
    end do
  end do

  ...

end subroutine update_phi_2d

This can also be generalized to cases where the assumptions above do not hold. In such cases, additional information about the guard-cell layout would need to be passed explicitly:

• For pold: ngx_pold_lo, ngx_pold_hi, ngy_pold_lo, ngy_pold_hi
• For pnew: ngx_pnew_lo, ngx_pnew_hi, ngy_pnew_lo, ngy_pnew_hi

For C interoperability, one option would be to first write a wrapper subroutine with the bind(C) attribute using explicit-shape arrays, as shown in the relevant tutorials. That wrapper could then call an inner subroutine using assumed-shape arrays, which is generally the preferred style in modern Fortran — it avoids the need to pass array dimensions explicitly and lets the compiler handle bounds checking more effectively.

I'm curious whether others here prefer to keep the assumed-shape version as the "real" implementation and treat the bind(C) wrapper as just a thin interop layer, or whether you tend to collapse everything into the explicit-shape version.

[WeiqunZhang]

One approach using modern Fortran would be to use assumed-shape arrays with remapped lower bounds, so that the physical region (spanning from lo to hi) always starts at index 1.

I don't think this requires assumed-shape arrays or modern Fortran. You can do that with explicit-shape arrays. In stead of a(lo:hi,...), you can do a(lo+offset,hi+offset,...), where offset can be arbitrary.

[Andris-R]

Thanks for your comments!

I am not a compiler expert, but I have read that modern compilers are very good at optimizing for assumed-shape arrays; It was on the Intel Forum, if I am not mistaken.

For me personally, working primarily with Fortran 90 and newer, the assumed-shape version is more intuitive, maintainable, and less error-prone compared to the explicit-shape version. I will keep in mind the potential tradeoffs regarding deep copies and performance losses.