Further updates to the READMEs

CMakeLists.txt

@@ -275,9 +275,18 @@ install(DIRECTORY matlab/ DESTINATION matlab
 if(UNIX)
 	install(DIRECTORY scripts/ DESTINATION scripts
 			MESSAGE_NEVER
+			FILES_MATCHING PATTERN "*.sh"
 			PATTERN "*.sh" PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_EXECUTE GROUP_READ)
 else()
 	install(DIRECTORY scripts/ DESTINATION scripts
 			MESSAGE_NEVER
+			FILES_MATCHING PATTERN "*.bat"
 			PATTERN "*.bat" PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ GROUP_EXECUTE GROUP_READ)
 endif()
+
+# Install certain root directory files
+install(FILES README.md DESTINATION .)
+install(FILES README-Dependencies.md DESTINATION .)
+install(FILES COPYRIGHT.txt DESTINATION .)
+install(FILES LICENCE.txt DESTINATION .)
+

COPYRIGHT.txt

@@ -1,8 +1,5 @@
-With the exception of the Template Numerical Toolkit (TNT) Linear Algebra Module (located in repository directory ./third_party/tnt), developed at the National Institute of Standards and Technology, which is incorporated into this package and belongs to the public domain, the remainder of the code is licensed under the GNU GPL Version 2.0 Licence by the following copyright holders:
+The code is licensed under the GNU GPL Version 2.0 Licence by the following copyright holders:
 
-Crown Copyright Commonwealth of Australia (Geoscience Australia) 2015.
-FFTW http://www.fftw.org (located in repository directory ./third_party/fftw3.2.2.dlls)
-Copyright (c) 2003, 2007-8 Matteo Frigo
-Copyright (c) 2003, 2007-8 Massachusetts Institute of Technology
+Crown Copyright Commonwealth of Australia (Geoscience Australia) 2024.
 
 The GNU GPL 2.0 licence is available at: http://www.gnu.org/licenses/gpl-2.0.html. If you require a paper copy of the GNU GPL 2.0 Licence, please write to Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

LICENCE.txt

@@ -1,8 +1,5 @@
-With the exception of the Template Numerical Toolkit (TNT) Linear Algebra Module (located in repository directory ./third_party/tnt), developed at the National Institute of Standards and Technology, which is incorporated into this package and belongs to the public domain, the remainder of the code is licensed under the GNU GPL Version 2.0 Licence by the following copyright holders:
+The code is licensed under the GNU GPL Version 2.0 Licence by the following copyright holders:
 
-Crown Copyright Commonwealth of Australia (Geoscience Australia) 2015.
-FFTW http://www.fftw.org (located in repository directory ./third_party/fftw3.2.2.dlls)
-Copyright (c) 2003, 2007-8 Matteo Frigo
-Copyright (c) 2003, 2007-8 Massachusetts Institute of Technology
+Crown Copyright Commonwealth of Australia (Geoscience Australia) 2024.
 
 The GNU GPL 2.0 licence is available at: http://www.gnu.org/licenses/gpl-2.0.html. If you require a paper copy of the GNU GPL 2.0 Licence, please write to Free Software Foundation, Inc. 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

README.md

@@ -27,9 +27,12 @@ This is a repository for Geoscience Australia's programs and utilities for forwa
 - removelog10conductivityfromsgrid.exe - legacy program for removing the log10 conductivity from GoCAD SGrids
 ### User examples
 - Examples of how to use the programs for various AEM systems
-### For Matlab and Python users
-- Matlab interface via MEX file (shared library) with examples 
-- Python interface via shared library with examples 
+### For Matlab users
+- Matlab interface via MEX file (shared library) with examples
+- See [*here*](matlab/README.md) for details.
+### For Python users
+- Python interface via shared library with examples.
+- See [*here*](python/README.md) for details.
 ### For developers/coders
 - example_forward_model.exe - (for developers) simple C++ language example of how to use the code in C++ to run a forward models.
 - example_forward_model_c.exe - (for developers) simple C language example of how to use the code in C++ to run a forward models.
@@ -85,7 +88,7 @@ For full functionality and to build all programs the following packages are requ
 > mkdir <build-dir>                                // <build-dir> is a temporary directory for building
 > cd <build-dir>                                   // change to the <build-dir>
 > cmake -DCMAKE_BUILD_TYPE=Release ..              // generate the cache using ../CMakeLists.txt in the directory above
-> cmake --build . --target all                     // build all targets
+> cmake --build .                                  // build all targets
 > cmake --install . --prefix <install-dir>         // install the executables, libraries, headers, docs and Matlab and Python into <install-dir>
 ```
 - The above should work on Linux if you have a C and C++ compiler installed along with all the dependencies.

cmake_build_script_gadi-gnu.sh

@@ -24,7 +24,7 @@ mkdir $BUILD_DIR
 cd $BUILD_DIR
 
 cmake -Wno-dev -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_BUILD_TYPE=Release ..
-cmake --build . --target all
+cmake --build . 
 cmake --install . --prefix $INSTALL_DIR
 
 #cmake --build . --target galeisbstdem
@@ -36,8 +36,11 @@ cmake --install . --prefix $INSTALL_DIR
 #cmake --build . --target gaforwardmodeltdem
 #cmake --build . --target example_forward_model
 #cmake --build . --target example_forward_model_c
+
 #cmake --build . --target gatdaem1d-static
 #cmake --build . --target gatdaem1d-shared
+#cmake --build . --target matlab-bindings
+#cmake --build . --target python-bindings
 
 #cmake --build . --target ctlinedata2sgrid
 #cmake --build . --target ctlinedata2slicegrids

cmake_build_script_gadi-intel.sh

@@ -26,7 +26,7 @@ mkdir $BUILD_DIR
 cd $BUILD_DIR
 
 cmake -Wno-dev -DCMAKE_C_COMPILER=icx -DCMAKE_CXX_COMPILER=icpx -DCMAKE_BUILD_TYPE=Release ..
-cmake --build . --target all
+cmake --build . 
 cmake --install . --prefix $INSTALL_DIR
 
 #cmake --build . --target galeisbstdem
@@ -37,8 +37,11 @@ cmake --install . --prefix $INSTALL_DIR
 #cmake --build . --target gaforwardmodeltdem
 #cmake --build . --target example_forward_model
 #cmake --build . --target example_forward_model_c
+
 #cmake --build . --target gatdaem1d-static
 #cmake --build . --target gatdaem1d-shared
+#cmake --build . --target matlab-bindings
+#cmake --build . --target python-bindings
 
 #cmake --build . --target ctlinedata2sgrid
 #cmake --build . --target ctlinedata2slicegrids

cmake_build_script_ubuntu.sh

@@ -19,7 +19,7 @@ cd $BUILD_DIR
 
 #Example for the GNU compilers
 cmake -Wno-dev -DCMAKE_C_COMPILER=gcc -DCMAKE_CXX_COMPILER=g++ -DCMAKE_BUILD_TYPE=Release ..
-cmake --build . --target all
+cmake --build . 
 cmake --install . --prefix $INSTALL_DIR
 
 # Or alternatively ...
@@ -33,8 +33,11 @@ cmake --install . --prefix $INSTALL_DIR
 #cmake --build . --target gaforwardmodeltdem
 #cmake --build . --target example_forward_model
 #cmake --build . --target example_forward_model_c
+
 #cmake --build . --target gatdaem1d-static
 #cmake --build . --target gatdaem1d-shared
+#cmake --build . --target matlab-bindings --config=Release
+#cmake --build . --target python-bindings --config=Release
 
 #cmake --build . --target ctlinedata2sgrid
 #cmake --build . --target ctlinedata2slicegrids
@@ -43,3 +46,4 @@ cmake --install . --prefix $INSTALL_DIR
 ## Windows only ctlinedata2curtainimage
 
 
+

cmake_build_script_windows-vs2022.bat

@@ -44,7 +44,7 @@ REM 	-DWITH_PETSC=OFF
 REM cmake -G "Visual Studio 17 2022" -A x64 -Wno-dev -DCMAKE_CXX_COMPILER=msvc -DCMAKE_BUILD_TYPE=Release -DWITH_MPI=OFF -DWITH_NETCDF=OFF -DWITH_GDAL=OFF -DWITH_PETSC=OFF ..
 
 REM Build and install everything
-cmake --build . --target all --config=Release
+cmake --build . --config=Release
 cmake --install . --prefix %INSTALL_DIR%
 
 REM Or alternatively ...
@@ -58,10 +58,11 @@ REM cmake --build . --target galeiallatonce --config=Release
 REM cmake --build . --target gaforwardmodeltdem --config=Release
 REM cmake --build . --target example_forward_model --config=Release
 REM cmake --build . --target example_forward_model_c --config=Release
-REM cmake --build . --target gatdaem1d-static --config=Release
 
-REM gatdaem1d-shared is required FOR python and matlab interfaces
+REM cmake --build . --target gatdaem1d-static --config=Release
 REM cmake --build . --target gatdaem1d-shared --config=Release
+REM cmake --build . --target matlab-bindings --config=Release
+REM cmake --build . --target python-bindings --config=Release
 
 REM cmake --build . --target ctlinedata2sgrid --config=Release
 REM cmake --build . --target ctlinedata2slicegrids --config=Release

matlab/README.md

@@ -1,8 +1,13 @@
-# Matlab
+# GA-AEM Matlab forward modelling interface
 
-Directory for the MATLAB interface module (C callable shared libarary) gatdaem1d which contains time domain forward modelling and derivative functions.
+## Description
+The MATLAB interface consists of a C callable shared libarary gatdaem1d which contains time domain forward modelling and derivative functions which are called by the Matlab interpreter, and a series of .m wrapper function scripts.
 
-# Contents
+## Compiling and installing the C/C++ shared libraries
+First the shared library needs to be built with CMake.  See one of the CMake build scripts in the root directory of the ga-aem source code repository.  If you are only interested in the Matlab interface, you need only build the ***`matlab_bindings`*** target.
+
+## Install directory contents
+- After being built successfully the install directory should contain,
 - [ga-aem-install-dir]/matlab/bin/libgatdaem1d.so is the time-domain Linux shared library
 - [ga-aem-install-dir]/matlab/bin/gatdaem1d.mexw64 is the time-domain 64-Bit Windows shared library (it is a dll that MATLAB can call)
 - [ga-aem-install-dir]/matlab/gatdaem1d_functions contains the wrapper functions MATLAB scripts .m
@@ -17,15 +22,15 @@ Directory for the MATLAB interface module (C callable shared libarary) gatdaem1d
 	- make sure that the directory containing your installed FFTW libraries (e.g. %LocalAppData%\fftw-3.3.5-dll64) is in your PATH environment variable before running the examples.  That folder will contain libfftw3-3.dll.
 3. In your Matlab environment add the following directories to your Matlab search path:
 	- [ga-aem-install-dir]/matlab/bin
-	- [ga-aem install dir]/gatdaem1d_functions
-	- [ga-aem install dir]/rjmcmctdem_functions
+	- [ga-aem-install-dir]/gatdaem1d_functions
+	- [ga-aem-install-dir]/rjmcmctdem_functions
 
 # Examples
-There are several example of how to use the Matlab interface in the directory [ga-aem-install-dir]\matlab\examples
-- The examples have paths setup to be run as if your Matlab current working directory is [ga-aem-install-dir]\matlab\examples
+There are several example of how to use the Matlab interface in the directory [ga-aem-install-dir]/matlab/examples
+- The examples have paths setup to be run as if your Matlab current working directory is [ga-aem-install-dir]/matlab/examples
 - If they are not already added in your Matlab startup.m script, you may need to add the gatdaem1d wrapper function (.m) files and the shared library to you Matlab path at the beginning of each script, for example you may need to uncomment and alter these lines,
 ```matlab
-	addpath('..\bin');
-	addpath('..\gatdaem1d_functions');
-	addpath('C:\fftw-3.3.5-dll64');
+	addpath('../bin');
+	addpath('../gatdaem1d_functions');
+	addpath('%LocalAppData%/fftw-3.3.5-dll64');
 ```

python/README.md

@@ -1,27 +1,26 @@
-# Python
-Directory containing the Python(3) interface files package.
+# GA-AEM Python forward modelling interface
 
 ## Description
-The Python (>=v3.5) interface consists of a C/C++ shared libarary (.so on Linux or .dll on Windows) called gatdaem1d which contains time domain forward modelling and derivative functions which are called by the Python interpreter.
-- [ga-aem-install-dir]/python contains the package set up or installation function setup.py.
-- [ga-aem-install-dir]/python/gatdaem1d contains the file \_\_init\_\_.py which is the package's Python classes and function code.  It is also where the compiled shared library will reside after compilation.
-- [ga-aem-install-dir]/python/examples/ contains example Python usage code.
-
-## Compiling the C/C++ shared libraries
-- First the shared library needs to be built with CMAKE.  See one of the installation scripts in the root directory of the repository.
-- After being built successfully,
-	- The shared library are written to [ga-aem-install-dir]/python/gatdaem1d.
+The Python (>=v3.5) interface consists of a C/C++ shared libarary (.so on Linux or .dll on Windows) called gatdaem1d which contains time-domain forward modelling and derivative functions which are called by the Python interpreter.
+
+## Compiling and installing the C/C++ shared libraries
+First the shared library needs to be built with CMake.  See one of the CMake build scripts in the root directory of the ga-aem source code repository. If you are only interested in the Python interface, you need only build the ***`python_bindings`*** target.
+
+## Install directory contents
+After being built successfully the install directory should contain,
+- [ga-aem-install-dir]/python contains the package set up or installation function `setup.py`.
+- [ga-aem-install-dir]/python/gatdaem1d contains the file `__init__.py` which is the package's Python classes and function code. It is also where the compiled shared library will reside after compilation.
 	- On Linux the shared library is [ga-aem-install-dir]/python/gatdaem1d/gatdaem1d.so.
 	- On Windows the shared library is [ga-aem-install-dir]/python/gatdaem1d/gatdaem1d.dll.
-	- On Windows a 64 bit Winodws dll is included in the repository and may work out of the box if you are using a 64 bit Python interpreter.
+- [ga-aem-install-dir]/python/examples contains example Python usage code.
 
-## Installation of the Python package
-- To install the package you can then,
+## PIP install of the Python package
+- To install as a python package you can then,
 ```bash
 	cd [ga-aem-install-dir]/python
 	python -m pip install .
 ```
-- Note that "python" may need to be "python3" on your system.
+- Note that **`python`** may need to be **`python3`** on your system.
 
 ## Examples
 - The directory [ga-aem-install-dir]/python/examples contains an example of how to use the gatdaem1d package.

scripts/ga-aem_vars.bat

@@ -1,6 +1,6 @@
-@ECHO ---------------------------------------------------------------------------
+@ECHO ===========================================================================
 @ECHO Adding GA-AEM programs and dependencies to the PATH environment variable
-@ECHO ---------------------------------------------------------------------------
+@ECHO ===========================================================================
 
 @ECHO OFF
 REM Add executable and library directories to your search path
@@ -12,13 +12,11 @@ set path=%GA-AEM_ROOT%\bin;%PATH%
 REM FFTW NOT required for the ctlinedata* programs
 set path=%LocalAppData%\fftw-3.3.5-dll64;%PATH%
 
-REM NetCDF only required for galeisbstdem.exe, galeisbstdem-nompi.exe, garjmcmctdem.exe
+REM NetCDF only optionally required for galeisbstdem.exe, galeisbstdem-nompi.exe, garjmcmctdem.exe
 set path=C:\Program Files\netCDF 4.9.2\bin;%PATH%
 
-REM GDAL only required for ctlinedata2georefimage.exe and ctlinedata2curtainimage.exe
-set path=%LocalAppData%\gdal-3.0.4\bin;%PATH%
-REM set path=%LocalAppData%\%LocalAppData%\gdal-3.7.1-mapserver-8-0-1;%PATH%
+REM GDAL only required for ctlinedata2slicegrids.exe and ctlinedata2curtainimage.exe
+set path=%LocalAppData%\gdal-3.7.1-mapserver-8-0-1\bin;%PATH%
 
 REM PETSc only required for galeiallatonce.exe
 SET path=%LocalAppData%\petsc\3.9.4\vs2017\win64_release\lib;%PATH%
-

scripts/test_ga-aem_paths.bat

@@ -9,15 +9,19 @@ set GA-AEM_ROOT=%LocalAppData%\GA-AEM
 REM Call batch script to setup the GA-AEM programs and dependency paths
 CALL %GA-AEM_ROOT%\scripts\ga-aem_vars.bat
 
-ECHO "-----------------"
+ECHO ==========================================================================
+ECHO GA-AEM_ROOT=%GA-AEM_ROOT%
+ECHO PATH=%PATH%
+
+ECHO ==========================================================================
 galeisbstdem.exe
-ECHO "-----------------"
+ECHO ==========================================================================
 galeiallatonce.exe
-ECHO "-----------------"
-ctlinedata2sgrid.exe
-ECHO "-----------------"
+ECHO ==========================================================================
+ctlinedata2curtainimage.exe
+ECHO ==========================================================================
 ctlinedata2slicegrids.exe
-ECHO "-----------------"
+ECHO ==========================================================================
 
 pause
 

submodules/README.md

@@ -1,7 +1,7 @@
 # Submodules for ga-aem
 
 # Description
-Git submodules are used in ga-aem git project. They contain utility and third party source code. Depending on what you are doing, you may not need all the submodules. They are not required if you just want to run the precompiled Windows executables.
+Git submodules are used in the ga-aem git project. They contain utility and third party source code. Depending on what you are doing, you may not need all the submodules. They are not required if you just want to run the precompiled Windows executables.
 
 # Initialisation and updating
 By default, when the ga-aem repository is initially cloned the submodule directories will not be populated with code/files. To populate them, you need to issue the `git submodule init` and `git submodule update --recursive` commands to initialise and populate each submodule with the (correct commit/version) of each repository.  The `--recursive` switch is required because some submodules have their own submodules.  For example,