From 86048c4d077c78662d25995dac5616f6bb081f8c Mon Sep 17 00:00:00 2001
From: Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com>
Date: Sat, 23 Apr 2022 17:53:21 +0200
Subject: [PATCH 1/2] Update README with installation instructions

---
 README.md                   | 158 ++++++++++++++++++++++++++++++++++--
 examples/example_lmder1.f90 |   2 +-
 meson.build                 |  22 +++--
 3 files changed, 171 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 5d10e5a..8cd67ab 100644
--- a/README.md
+++ b/README.md
@@ -7,7 +7,7 @@ Modernized Minpack
 
 ### Description
 
-Minpack includes software for solving nonlinear equations and
+*Minpack* includes software for solving nonlinear equations and
 nonlinear least squares problems.  Five algorithmic paths each include
 a core subroutine and an easy-to-use driver.  The algorithms proceed
 either from an analytic specification of the Jacobian matrix or
@@ -16,15 +16,151 @@ systems of equations with a banded Jacobian matrix, for least squares
 problems with a large amount of data, and for checking the consistency
 of the Jacobian matrix with the functions.
 
-This version is a modernization of the original Fortran 77 code. This is a work in progress. Modifications include:
+This version is a modernization of the original Fortran 77 code.
+Modifications include:
+
 * Conversion from fixed (`.f`) to free-form (`.f90`) source.
 * Modified the tests so they can be automatically run in the [CI](https://github.com/fortran-lang/minpack/actions)
+* Implementation of C API for all procedures
+* Python bindings to the *minpack* C API
 
 Further updates are planned...
 
-### Decision trees
 
-#### Decision tree for systems of nonlinear equations
+### Installation
+
+To build this project from the source code in this repository you need to have
+a Fortran compiler supporting Fortran 2008 and one of the supported build systems:
+
+- [fpm](https://fpm.fortran-lang.org) version 0.3.0 or newer
+- [meson](https://mesonbuild.com) version 0.55 or newer, with
+  a build-system backend, *i.e.* [ninja](https://ninja-build.org) version 1.7 or newer
+
+The project is hosted on GitHub and can be obtained by cloning it with
+
+```
+git clone https://github.com/fortran-lang/minpack
+cd minpack
+```
+
+
+#### Building with fpm
+
+Invoke fpm in the project root with
+
+```
+fpm build
+```
+
+To run the testsuite use
+
+```
+fpm test
+```
+
+You can access the *minpack* program programs using the run subcommand
+
+```
+fpm run --example --list
+```
+
+To use *minpack* in your project include it as dependency in your package manifest
+
+```toml
+[dependencies]
+minpack.git = "https://github.com/fortran-lang/minpack"
+```
+
+
+#### Building with meson
+
+Optional dependencies are
+
+
+Setup a build with
+
+```
+meson setup _build
+```
+
+The following build options can be adjusted:
+
+- the Fortran compiler can be selected by setting the ``FC`` environment variable.
+- the installation location can be set with the ``--prefix=/path/to/install`` option
+- with the ``-Dpython=true`` option the Python bindings can be built
+
+  - Python 3.6  or newer is required with the CFFI package installed
+  - the actual Python version can be selected using ``-Dpython_version=/path/to/python``
+
+To compile and run the projects testsuite use
+
+```
+meson test -C _build --print-errorlogs
+```
+
+If the testsuite passes you can install with
+
+```
+meson install -C _build
+```
+
+This might require administrator access depending on the chosen install prefix.
+*Minpack* should now be available on your system, you can check by using the *pkg-config* tool
+
+```
+pkg-config --modversion minpack
+```
+
+To include *minpack* in your project add the following wrap file to your *subprojects* directory:
+
+```ini
+[wrap-git]
+directory = minpack
+url = https://github.com/fortran-lang/minpack
+revision = head
+```
+
+You can retrieve the dependency from the wrap fallback with
+
+```meson
+minpack_dep = dependency('minpack', fallback: ['minpack', 'minpack_dep'])
+```
+
+and add it as dependency to your targets.
+
+
+#### Supported compilers
+
+The following compilers are known to work with *minpack*.
+
+| Compiler | Version | Platform | Architecture | Minpack version |
+| --- | --- | --- | --- | --- |
+| GCC | 10.2 | Ubuntu 20.04 | x86\_64 | latest |
+| GCC | 10.2 | MacOS 11 | x86\_64 | latest |
+| GCC/MinGW | 10.3 | Windows Server 2022 | x86\_64 | latest |
+| Intel | 2021.5.0 | Manjaro Linux | x86\_64 | [fa4bcbd] |
+| Intel LLVM | 2022.0.0 | Manjaro Linux | x86\_64 | [fa4bcbd] |
+| NAG | 7.1 | RHEL | x86\_64 | [fa4bcbd] |
+
+[fa4bcbd]: https://github.com/fortran-lang/minpack/tree/fa4bcbdc7a926a3607e8ff5397ca356a74c50d5a
+
+The combinations annotated with *latest* are tested continuously for this project, for all other results the last commit or tag where this behavior was verified is linked.
+A list of tested compilers which are currently not working or only partially working and the respective issue are listed below.
+
+| Compiler | Version | Platform | Architecture | Status |
+| --- | --- | --- | --- | --- |
+| GCC | 11.1 | MacOS 12 | Arm64 | C-API not supported |
+| Nvidia HPC SDK | 22.3 | Manjaro Linux | x86\_64 | Unit tests are failing |
+
+Please share your experience with successful and failing builds for compiler/platform/architecture combinations not covered above.
+
+
+### Usage
+
+*Minpack* provides a series of solves for systems of nonlinear equations and nonlinear least squares problems.
+To select the approriate solver for your problem checkout the diagrams below.
+
+*Decision tree for systems of nonlinear equations*
 
 ```mermaid
 flowchart TB
@@ -37,7 +173,7 @@ flowchart TB
 	middle2--No-->b4[<a href='https://fortran-lang.github.io/minpack/proc/hybrd1.html'>hybrd1</a>]
 ```
 
-#### Decision tree for nonlinear least squares problems
+*Decision tree for nonlinear least squares problems*
 
 ```mermaid
 flowchart TB
@@ -54,14 +190,23 @@ flowchart TB
 	m2--No-->mr2[<a href='https://fortran-lang.github.io/minpack/proc/lmdif1.html'>lmdif1</a/>]
 ```
 
+In Fortran projects the above procedures can be made available by including the ``minpack_module``.
+Examples can be found in the [example](./example) directory.
+
+To use *minpack* in non-Fortran projects which are compatible with C checkout the [``minpack.h``](./include/minpack.h) header for the available symbols and callback function signatures.
+Python bindings are available and documented in the [``python``](./python) subdirectory of this project.
+
+
 ### Documentation
 
  * The API documentation for the latest default branch can be found [here](https://fortran-lang.github.io/minpack/).  This is generated by processing the source files with [FORD](https://github.com/Fortran-FOSS-Programmers/ford).
 
+
 ### License
 
 The Minpack source code and related files and documentation are distributed under a permissive free software [license](https://github.com/fortran-lang/minpack/blob/HEAD/LICENSE.txt) (BSD-style).
 
+
 ### History
 
 Minpack has been developed in 1980 by Jorge J. Moré, Burton S. Garbow, Kenneth
@@ -79,6 +224,7 @@ version to use as the community maintained fortran-lang version and decided to
 use the latter repository, which became the fortran-lang version. We have
 been porting improvements from the former repository over to the new fortran-lang repository.
 
+
 ### Contributors
 
 Many people have contributed to Minpack over the years:
@@ -91,10 +237,12 @@ Many people have contributed to Minpack over the years:
 * Jacob Williams
 * Sebastian Ehlert
 
+
 ### See also
 
   * [nlesolver-fortran](https://github.com/jacobwilliams/nlesolver-fortran)
 
+
 ### References
   * Original sourcecode from: [Netlib](https://www.netlib.org/minpack/)
   * J. J. Moré, B. S. Garbow, and K. E. Hillstrom, [User Guide for MINPACK-1](http://cds.cern.ch/record/126569/files/CM-P00068642.pdf), Argonne National Laboratory Report ANL-80-74, Argonne, Ill., 1980.
diff --git a/examples/example_lmder1.f90 b/examples/example_lmder1.f90
index 54d6467..cfa1bd4 100644
--- a/examples/example_lmder1.f90
+++ b/examples/example_lmder1.f90
@@ -56,10 +56,10 @@ subroutine fcn(m, n, x, fvec, fjac, ldfjac, iflag)
 
     integer, intent(in) :: m
     integer, intent(in) :: n
+    integer, intent(in) :: ldfjac
     real(wp), intent(in) :: x(n)
     real(wp), intent(inout) :: fvec(m)
     real(wp), intent(inout) :: fjac(ldfjac, n)
-    integer, intent(in) :: ldfjac
     integer, intent(inout) :: iflag
 
     integer :: i
diff --git a/meson.build b/meson.build
index f9d82da..5611993 100644
--- a/meson.build
+++ b/meson.build
@@ -8,8 +8,16 @@ project(
     'buildtype=debugoptimized',
   ],
 )
+
 fc_nested_functions = meson.get_compiler('fortran').run(
-  'call a(); contains; subroutine a(); print "(a)", "Nested functions supported"; end; end',
+  '''
+  call a()
+  contains
+  subroutine a()
+  print "(a)", "Nested functions supported"
+  end
+  end
+  ''',
 ).returncode() == 0
 if fc_nested_functions
   has_cc = add_languages('c', required: get_option('python'), native: false)
@@ -22,12 +30,16 @@ else
   endif
 endif
 
+srcs = files(
+  'src/minpack.f90',
+)
+if fc_nested_functions
+  srcs += files('src/minpack_capi.f90')
+endif
+
 minpack_lib = library(
   meson.project_name(),
-  sources: files(
-    'src/minpack.f90',
-    fc_nested_functions ? 'src/minpack_capi.f90' :,
-  ),
+  sources: srcs,
   install: true,
 )
 

From e39ba420550bc4a33605de41a3bc689a3e6a70e9 Mon Sep 17 00:00:00 2001
From: Sebastian Ehlert <28669218+awvwgk@users.noreply.github.com>
Date: Sat, 23 Apr 2022 22:31:20 +0200
Subject: [PATCH 2/2] Add option to enable API rather than relying on a check

---
 meson.build       | 28 ++++++----------------------
 meson_options.txt |  6 ++++++
 test/meson.build  |  2 +-
 3 files changed, 13 insertions(+), 23 deletions(-)

diff --git a/meson.build b/meson.build
index 5611993..7d5e9e8 100644
--- a/meson.build
+++ b/meson.build
@@ -8,32 +8,16 @@ project(
     'buildtype=debugoptimized',
   ],
 )
-
-fc_nested_functions = meson.get_compiler('fortran').run(
-  '''
-  call a()
-  contains
-  subroutine a()
-  print "(a)", "Nested functions supported"
-  end
-  end
-  ''',
-).returncode() == 0
-if fc_nested_functions
-  has_cc = add_languages('c', required: get_option('python'), native: false)
-else
-  has_cc = false
-  if get_option('python')
-    error('Cannot compile Python API, Fortran compiler does not support nested functions')
-  else
-    warning('Fortran compiler does not support nested functions, C API is disabled')
-  endif
+if get_option('api')
+  has_cc = add_languages('c', native: false)
+elif get_option('python')
+  error('Cannot compile Python API, Fortran compiler does not support nested functions')
 endif
 
 srcs = files(
   'src/minpack.f90',
 )
-if fc_nested_functions
+if get_option('api')
   srcs += files('src/minpack_capi.f90')
 endif
 
@@ -62,7 +46,7 @@ install_data(
   install_dir: get_option('datadir')/'licenses'/meson.project_name()
 )
 
-if fc_nested_functions
+if get_option('api')
   install_headers(
     minpack_header,
   )
diff --git a/meson_options.txt b/meson_options.txt
index df0f2b1..7fe7d71 100644
--- a/meson_options.txt
+++ b/meson_options.txt
@@ -1,3 +1,9 @@
+option(
+  'api',
+  type: 'boolean',
+  value: true,
+  description: 'Export bindings for the C API',
+)
 option(
   'python',
   type: 'boolean',
diff --git a/test/meson.build b/test/meson.build
index 1f744e6..beb611c 100644
--- a/test/meson.build
+++ b/test/meson.build
@@ -19,7 +19,7 @@ foreach t : tests
   )
 endforeach
 
-if has_cc
+if get_option('api')
   test(
     'c-api',
     executable(