Merge berkeleylab fork upstream

.github/workflows/CI.yml

@@ -7,13 +7,13 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        os: [macos-12, ubuntu-24.04]
+        os: [macos-13, ubuntu-24.04]
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v1
+      uses: actions/checkout@v4
 
-    - uses: fortran-lang/setup-fpm@v4
+    - uses: fortran-lang/setup-fpm@v6.0.1
       with:
         github-token: ${{ secrets.GITHUB_TOKEN }}
 
@@ -23,11 +23,6 @@ jobs:
         sudo apt update
         sudo apt install -y build-essential gfortran-14 g++-14
 
-    - name: Install Dependencies on macOS
-      if: contains(matrix.os, 'macos')
-      run: |
-        brew install gfortran
-
     - name: Build and Run unit tests
       run: |
         fpm test --compiler gfortran-14

.github/workflows/build-with-flang.yml

@@ -0,0 +1,32 @@
+name: Build with LLVM Flang
+
+on: [push, pull_request]
+
+
+jobs:
+  Build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-24.04]
+      fail-fast: true
+    container: gmao/llvm-flang:latest
+    env:
+      FC: flang-new
+
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+
+    - uses: fortran-lang/[email protected]
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+
+    - name: Build and Test with LLVM Flang
+      if: contains(matrix.os, 'ubuntu')
+      run: |
+        fpm --version
+        $FC --version
+        export FPM_FC=$FC
+        export FPM_FFLAGS="-mmlir -allow-assumed-rank -O3"
+        fpm test

.github/workflows/deploy-docs.yml

@@ -8,7 +8,7 @@ jobs:
 
     steps:
     - name: Checkout code
-      uses: actions/checkout@v2
+      uses: actions/checkout@v4
 
     - name: Install Dependencies Ubuntu
       run: |
@@ -21,7 +21,7 @@ jobs:
         ford ford.md
 
     - name: Upload Documentation
-      uses: actions/upload-artifact@v2
+      uses: actions/upload-artifact@v4
       with:
         name: documentation
         path: doc/html

.gitignore

@@ -1,3 +1,4 @@
+*.smod
 *.mod
 *.o
 a.out

README.md

@@ -25,11 +25,12 @@ fpm test --compiler nagfor --flag -fpp
 ```
 
 ### LLVM Flang
-**Experimental**
 ```
-fpm test --compiler flang-new --flag "-mmlir -allow-assumed-rank"
+export FPM_FC=flang-new
+export FPM_FFLAGS="-mmlir -allow-assumed-rank"
+fpm test # Warning: Do not override the FPM_FC or FPM_FFLAGS variables with --compiler or --flag
 ```
-where the flags `-mmlir -allow-assumed-rank` turn on LLVM Flang's experimental support for Fortran's assumed-rank dummy arguments.
+where the flags turn on LLVM Flang's experimental support for Fortran assumed-rank dummy arguments.
 Flang's capabilities are evolving rapidly so we recommend building a recent version of the main branch of llvm-project.
 A script that might be helpful for doing so is in the [handy-dandy] repository.
 

doc/uml/class-diagram.md

@@ -0,0 +1,39 @@
+Julienne Unit Testing Classes
+-----------------------------
+```mermaid
+classDiagram
+
+test_t --> test_result_t : produces
+test_description_t --> test_diagnosis_t : "uses to construct test_result_t"
+test_result_t --> test_diagnosis_t : "accepts as constructor argument"
+
+class test_t{
+  <<abstract>>
+    + subject() character *
+    + results() test_result_t *
+    + report(passes : integer, tests : integer)
+}
+
+class test_result_t{
+    - description_ : character
+    - diagnostics_ : character
+    - passed : logical
+    + test_result_t(description : character, passed : test_diagnosis_t) test_result_t
+    + characterize() : character
+    + description_contains(character) : logical
+    + passed() : logical
+}
+
+class test_diagnosis_t{
+    - test_passed_ : logical
+    - diagnostics_string_ : character
+    + test_diagnosis_t(test_passed : logical, diagnostics_string : character) test_diagnosis_t
+}
+
+class test_description_t{
+    - description_ : character
+    - diagnosis_function : procecure(diagnosis_function_i), pointer
+    + test_description_t(description : character, diagnosis_function : procedure(diagnosis_function_i))
+    + run() test_result_t
+    + contains_text(character) logical
+}

doc/uml/sequence-diagram.md

@@ -0,0 +1,13 @@
+Example Sequence Diagram
+------------------------
+```mermaid
+sequenceDiagram
+    main->>specimen_test_t: report(passes, tests)
+    test_t ->>command_line_t: flag_value("--contains")
+    command_line_t ->> specimen_test_t : test_description_substring
+    test_t ->> test_t : subject
+    test_t ->> test_t : results
+    test_t ->> test_description_t : construct
+    test_t ->> test_result_t : construct
+    test_t ->> test_result_t : characterize
+    test_t ->> test_result_t : passed

example/example-test-suite/main.F90

@@ -0,0 +1,51 @@
+! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! Terms of use are as specified in LICENSE.txt
+
+#include "language-support.F90"
+
+program main
+  !! Example test main program to demonstrate the printing of diagnostic output when a test fails
+  use julienne_m, only : command_line_t
+  use specimen_test_m, only : specimen_test_t
+  implicit none
+
+  type(specimen_test_t) specimen_test
+  integer :: passes=0, tests=0
+
+  call print_usage_and_stop_if_help_requested
+  call specimen_test%report(passes, tests)
+  call report_tally_and_error_stop_if_test_fails
+
+contains
+
+  subroutine print_usage_and_stop_if_help_requested
+    type(command_line_t) command_line
+    if (command_line%argument_present([character(len=len("--help"))::"--help","-h"]))  then
+      print *
+      print '(a)', 'Usage: fpm run --example main -- [--help] | [--contains <substring>]'
+      print *
+      print '(a)', 'where square brackets ([]) denote optional arguments, a pipe (|) separates alternative arguments,'
+      print '(a)', 'angular brackets (<>) denote a user-provided value, and passing a substring limits execution to'
+      print '(a)', 'the tests with test subjects or test descriptions containing the user-specified substring.'
+      stop
+    else
+      print * 
+      print "(a)", "Append '-- --help' or '-- -h' to your `fpm test` command to display usage information."
+    end if
+  end subroutine
+
+  subroutine report_tally_and_error_stop_if_test_fails
+
+#if HAVE_MULTI_IMAGE_SUPPORT
+    if (this_image()==1) then
+#endif
+      print *
+      print '(*(a,:,g0))', "_________ In total, ",passes," of ",tests, " tests pass. _________"
+      if (passes /= tests) error stop "Some tests failed."
+#if HAVE_MULTI_IMAGE_SUPPORT
+    end if
+#endif
+
+  end subroutine
+
+end program

example/example-test-suite/specimen_m.F90

@@ -0,0 +1,19 @@
+! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! Terms of use are as specified in LICENSE.txt
+module specimen_m
+  !! Example test specimen corresponding to the test defined in specimen_test_m.F90
+  implicit none
+
+  type specimen_t
+  contains
+    procedure, nopass :: zero
+  end type
+
+contains
+
+  pure function zero() result(incorrect_value)
+    integer incorrect_value
+    incorrect_value = 1
+  end function
+
+end module

example/example-test-suite/specimen_test_m.F90

@@ -0,0 +1,80 @@
+! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! Terms of use are as specified in LICENSE.txt
+
+#include "language-support.F90"
+
+module specimen_test_m
+  !! Example unit test for the specimen_t test subject
+  use specimen_m, only : specimen_t
+  use julienne_m, only : &
+    string_t, &
+    test_t, &
+    test_result_t, &
+    test_description_t, &
+    test_description_substring, &
+    test_diagnosis_t
+#if ! HAVE_PROCEDURE_ACTUAL_FOR_POINTER_DUMMY
+  use julienne_m, only : diagnosis_function_i ! work around gfortran's missing Fortran 2008 feature
+#endif
+
+  implicit none
+
+  private
+  public :: specimen_test_t
+
+  type, extends(test_t) :: specimen_test_t
+  contains
+    procedure, nopass :: subject
+    procedure, nopass :: results
+  end type
+
+contains
+
+  pure function subject() result(specimen_description)
+    character(len=:), allocatable :: specimen_description
+    specimen_description = "A specimen_t object" 
+  end function
+
+  function results() result(test_results)
+    type(test_result_t), allocatable :: test_results(:)
+    type(test_description_t), allocatable :: test_descriptions(:)
+
+#if HAVE_PROCEDURE_ACTUAL_FOR_POINTER_DUMMY
+    test_descriptions = [ & 
+      test_description_t("the type-bound function zero() producing a result of 0", check_zero) &
+    ]   
+#else 
+    ! work around gfortran's missing Fortran 2008 feature
+    procedure(diagnosis_function_i), pointer :: check_zero_ptr
+    check_zero_ptr => check_zero
+
+    test_descriptions = [ & 
+      test_description_t("the type-bound function zero() producing a result of 0", check_zero_ptr) &
+    ]   
+#endif
+#ifndef __GFORTRAN__
+    associate(test_subset => pack(test_descriptions, test_descriptions%contains_text(test_description_substring) .or. index(subject(), test_description_substring)/=0))
+      test_results = test_subset%run()
+    end associate
+#else 
+
+    test_descriptions = pack(test_descriptions, test_descriptions%contains_text(test_description_substring) .or. index(subject(), test_description_substring)/=0)
+    test_results = test_descriptions%run()
+#endif
+
+  end function
+
+  function check_zero() result(test_diagnosis)
+    type(test_diagnosis_t) test_diagnosis
+    type(specimen_t) specimen
+    integer, parameter :: expected_value = 0
+
+    associate(actual_value => specimen%zero())
+      test_diagnosis = test_diagnosis_t( &
+         test_passed = actual_value == expected_value &
+        ,diagnostics_string = "expected value " // string_t(expected_value) //", actual value " // string_t(actual_value) &
+      )
+    end associate
+  end function
+
+end module

fpm.toml

@@ -1,12 +1,12 @@
 name = "julienne"
-version = "1.3.0"
+version = "1.5.3"
 license = "license"
 author = "Damian Rouson, Brad Richardson, Patrick Raynaud, Katherine Rasmussen"
 maintainer = "[email protected]"
 copyright = "Copyright 2024, Sourcery Institute and Berkeley Lab"
 
 [dependencies]
-assert = {git = "https://github.com/sourceryinstitute/assert", tag = "1.7.0"}
+assert = {git = "https://github.com/sourceryinstitute/assert", tag = "2.0.0"}
 
 [install]
 library = true

include/language-support.F90

@@ -0,0 +1,33 @@
+! Copyright (c), The Regents of the University of California
+! Terms of use are as specified in LICENSE.txt
+
+#ifndef HAVE_SELECTED_LOGICAL_KIND
+  ! Define whether the compiler supports standard intrinsic function selected_logical_kind(),
+  ! a feature introduced in Fortran 2023 clause 16.9.182.
+#if defined(_CRAYFTN) || defined(NAGFOR) || defined(__flang__)
+#define HAVE_SELECTED_LOGICAL_KIND 1
+#else
+#define HAVE_SELECTED_LOGICAL_KIND 0
+#endif
+#endif
+
+#ifndef HAVE_PROCEDURE_ACTUAL_FOR_POINTER_DUMMY
+  ! Define whether the compiler supports associating a procedure pointer dummy argument with an
+  ! actual argument that is a valid target for the pointer dummy in a procedure assignment, a
+  ! feature introduced in Fortran 2008 and described in Fortran 2023 clause 15.5.2.10 paragraph 5.
+#if defined(_CRAYFTN) || defined(__INTEL_COMPILER) || defined(NAGFOR) || defined(__flang__)
+#define HAVE_PROCEDURE_ACTUAL_FOR_POINTER_DUMMY 1
+#else
+#define HAVE_PROCEDURE_ACTUAL_FOR_POINTER_DUMMY 0
+#endif
+#endif
+
+#ifndef HAVE_MULTI_IMAGE_SUPPORT
+  ! Define whether the compiler supports the statements and intrinsic procedures that support
+  ! multi-image execution, e.g., this_image(), sync all, etc.
+#if defined(_CRAYFTN) || defined(__INTEL_COMPILER) || defined(NAGFOR) || defined(__GFORTRAN__)
+#define HAVE_MULTI_IMAGE_SUPPORT 1
+#else
+#define HAVE_MULTI_IMAGE_SUPPORT 0
+#endif
+#endif

src/julienne/julienne_bin_m.f90

@@ -1,3 +1,5 @@
+! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! Terms of use are as specified in LICENSE.txt
 module julienne_bin_m
   !! distribute item numbers across bins such that the number of items differs by at most 1 between any two bins
   implicit none

src/julienne/julienne_bin_s.f90

@@ -1,3 +1,5 @@
+! Copyright (c) 2024, The Regents of the University of California and Sourcery Institute
+! Terms of use are as specified in LICENSE.txt
 submodule(julienne_bin_m) julienne_bin_s
   use assert_m, only : assert, intrinsic_array_t
   implicit none

src/julienne/julienne_command_line_m.f90

@@ -26,7 +26,8 @@ module function argument_present(acceptable_argument) result(found)
     end function
 
     module function flag_value(flag)
-      !! result is the value passed adjacent to a command-line flag
+      !! result = { the value passed immediately after a command-line flag if the flag is present or
+      !!          { an empty string otherwise.
       implicit none
       character(len=*), intent(in) :: flag
       character(len=:), allocatable :: flag_value