From 6f93ad0db71411608cc4c3d1abc0d06620ab1635 Mon Sep 17 00:00:00 2001 From: Ross Brodie Date: Thu, 18 Apr 2024 21:37:49 +1000 Subject: [PATCH] Further updates to the READMEs --- CMakeLists.txt | 9 +++++++++ COPYRIGHT.txt | 7 ++----- LICENCE.txt | 7 ++----- README.md | 11 ++++++---- cmake_build_script_gadi-gnu.sh | 5 ++++- cmake_build_script_gadi-intel.sh | 5 ++++- cmake_build_script_ubuntu.sh | 6 +++++- cmake_build_script_windows-vs2022.bat | 7 ++++--- docs/README.md | 5 ----- examples/README.md | 5 ----- matlab/README.md | 25 ++++++++++++++--------- python/README.md | 29 +++++++++++++-------------- scripts/ga-aem_vars.bat | 12 +++++------ scripts/test_ga-aem_paths.bat | 16 +++++++++------ src/README.md | 5 ----- submodules/README.md | 2 +- 16 files changed, 82 insertions(+), 74 deletions(-) delete mode 100644 docs/README.md delete mode 100644 examples/README.md delete mode 100644 src/README.md diff --git a/CMakeLists.txt b/CMakeLists.txt index aebb0a6..c05ae8e 100644 --- a/CMakeLists.txt +++ b/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 .) + diff --git a/COPYRIGHT.txt b/COPYRIGHT.txt index 3aa1b8e..c5d83e2 100644 --- a/COPYRIGHT.txt +++ b/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. diff --git a/LICENCE.txt b/LICENCE.txt index 3aa1b8e..c5d83e2 100644 --- a/LICENCE.txt +++ b/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. diff --git a/README.md b/README.md index 0e38111..2e50763 100644 --- a/README.md +++ b/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 // is a temporary directory for building > cd // change to the > 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 the executables, libraries, headers, docs and Matlab and Python into ``` - The above should work on Linux if you have a C and C++ compiler installed along with all the dependencies. diff --git a/cmake_build_script_gadi-gnu.sh b/cmake_build_script_gadi-gnu.sh index d4e1e86..b773e44 100755 --- a/cmake_build_script_gadi-gnu.sh +++ b/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 diff --git a/cmake_build_script_gadi-intel.sh b/cmake_build_script_gadi-intel.sh index 1911c82..d0fce96 100755 --- a/cmake_build_script_gadi-intel.sh +++ b/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 diff --git a/cmake_build_script_ubuntu.sh b/cmake_build_script_ubuntu.sh index cdceebc..3dc632d 100644 --- a/cmake_build_script_ubuntu.sh +++ b/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 + diff --git a/cmake_build_script_windows-vs2022.bat b/cmake_build_script_windows-vs2022.bat index ee52df8..8e93bdc 100644 --- a/cmake_build_script_windows-vs2022.bat +++ b/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 diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index f55beda..0000000 --- a/docs/README.md +++ /dev/null @@ -1,5 +0,0 @@ -docs -==== - -Directory for documentation - diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index b27a388..0000000 --- a/examples/README.md +++ /dev/null @@ -1,5 +0,0 @@ -examples -======== - -Directory for examples - diff --git a/matlab/README.md b/matlab/README.md index 1d80416..9e7aabb 100644 --- a/matlab/README.md +++ b/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'); ``` \ No newline at end of file diff --git a/python/README.md b/python/README.md index 7fa8ec1..b61b522 100644 --- a/python/README.md +++ b/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. diff --git a/scripts/ga-aem_vars.bat b/scripts/ga-aem_vars.bat index 3652915..88e7ee1 100644 --- a/scripts/ga-aem_vars.bat +++ b/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% - diff --git a/scripts/test_ga-aem_paths.bat b/scripts/test_ga-aem_paths.bat index 02e38b5..6c2ce47 100644 --- a/scripts/test_ga-aem_paths.bat +++ b/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 diff --git a/src/README.md b/src/README.md deleted file mode 100644 index 4b3ec4c..0000000 --- a/src/README.md +++ /dev/null @@ -1,5 +0,0 @@ -src -=== - -Directory for C++ source and headers files - diff --git a/submodules/README.md b/submodules/README.md index 85df933..be30f58 100644 --- a/submodules/README.md +++ b/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,