From af2148ceef6a9c0672f9995c87bbc201d8af29a1 Mon Sep 17 00:00:00 2001 From: Ross Brodie Date: Sat, 20 Apr 2024 16:10:35 +1000 Subject: [PATCH] Further updates to README files --- README-Dependencies.md | 4 +-- README.md | 58 ++++++++++++++++++++++-------------------- matlab/README.md | 4 +-- python/README.md | 2 +- visualstudio/README.md | 25 +++++++++--------- 5 files changed, 48 insertions(+), 45 deletions(-) diff --git a/README-Dependencies.md b/README-Dependencies.md index 531f7e9..52f2479 100644 --- a/README-Dependencies.md +++ b/README-Dependencies.md @@ -20,7 +20,7 @@ Depending on your flavour of Linux, you are likely to need to install the packag ### Installing dependencies on Windows On Windows the packages can be downloaded and installed as outlined below. - Note that 64 bit versions are required with the include and library files. -- Note that the directory path `%LocalAppData%` is the Windows environment variable where non-administrator users can install applications for their own use and is typically located at `C:\Users\[your-username]\AppData\Local\`. +- Note that the directory path `%LocalAppData%` is the Windows environment variable where non-administrator users can install applications for their own use and is typically located at `C:\Users\\AppData\Local\`. - Note that `%LocalAppData%` can be substituted for any other suitable installation path, for example `C:\Program Files\` or `C:\Win10Dev\`. #### FFTW @@ -45,7 +45,7 @@ On Windows the packages can be downloaded and installed as outlined below. - Download the - Compiled libraries and headers - https://build2.gisinternals.com/sdk/downloads/release-1911-x64-gdal-3-0-4-mapserver-7-4-3-libs.zip. - Unzip both these into a single directory e.g. `gdal-3.7.1-mapserver-8-0-1` that should then have bin, doc, include and lib sub-directories. - Place that folder into a suitable install path, for example `%LocalAppData%\gdal-3.7.1-mapserver-8-0-1`. -- Note that earlier versions of GDAL can also be similarly used, eg. v3.0.4 - https://gisinternals.com/query2.html?content=filelist&file=release-1911-x64-gdal-3-0-4-mapserver-7-4-3.zip. +- Note that earlier versions of GDAL can also be similarly used, for example, v3.0.4 - https://gisinternals.com/query2.html?content=filelist&file=release-1911-x64-gdal-3-0-4-mapserver-7-4-3.zip. #### PETSc - Download the prebuilt PETSc 3.9.4 Windows 64 bit libraries - https://github.com/rcb547/petsc-3.9.4-vs2017-win64-libraries/releases/download/v1.0.0/petsc-3.9.4-vs2017-win64-libraries.zip diff --git a/README.md b/README.md index 2e50763..6553838 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,21 @@ # GA-AEM Source Code Repository # Description -This is a repository for Geoscience Australia's programs and utilities for forward modelling and inversion of Airborne Electromagnetic (AEM) data. It includes Matlab and Python interfaces for forward model and derivative calculations. It also includes some programs for post-processing inversion results into sections, images and grids. +GA-AEM is a repository for Geoscience Australia's C++ programs and utilities for forward modelling and inversion of Airborne Electromagnetic (AEM) data. It includes Matlab and Python interfaces for forward model and derivative calculations. It also includes some programs for post-processing inversion results into GoCAD SGrid sections, georeferenced-section images and grids. ## Authors -- Ross C Brodie, Geoscience Australia (formerly) -- Richard Taylor, Geoscience Australia (formerly) +- Dr Ross C Brodie, formerly Geoscience Australia +- Dr Richard Taylor, formerly Geoscience Australia + +## Acknowledgements +The majority of the development for this project was carried out by the authors whilst employed at Geoscience Australia. A significant part of the development was however carried out as part of a Geoscience Australia-CSIRO placement. The CSIRO Deep Earth Imaging Future Science Platform (DEI-FSP), CSIRO Discovery Program and CSIRO Research Office is acknowledged for funding and facilitating that placement. ## Languages - Mostly C++. - Some Matlab. - Some Python. -## Included content +## Included contents ### User programs - gaforwardmodeltdem.exe - 1D forward modelling program for time-domain AEM data @@ -26,9 +29,9 @@ This is a repository for Geoscience Australia's programs and utilities for forwa - ctlinedata2curtainimage.exe - (undocumented) convert inversion outputs to GA's Earth Sci curtain image format - 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 +- Examples of how to use the programs for various AEM systems. ### For Matlab users -- Matlab interface via MEX file (shared library) with examples +- 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. @@ -36,23 +39,22 @@ This is a repository for Geoscience Australia's programs and utilities for forwa ### 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. - ### User documentation -- [User Manual](docs/GA-AEM_Programs_User_Manual.pdf) -- [Theoretical details for GALEISBSTDEM](docs/GALEISBSTDEM_Inversion_Algorithm_Theoretical_Details.pdf) +- [*User Manual*](docs/GA-AEM_Programs_User_Manual.pdf). +- [*Theoretical details for GALEISBSTDEM*](docs/GALEISBSTDEM_Inversion_Algorithm_Theoretical_Details.pdf). # Cloning the repository -When initially cloning the repository in git you should use the `--recursive` option so that all of the submodules and their respective submodules are initialised and populated with code. +When initially cloning the repository in git you should use the `--recursive` option so that all of the submodules and their respective submodules are initialized and populated with code. ```bash > git clone --recursive https://github.com/GeoscienceAustralia/ga-aem.git ``` -or if you use SSH authentification, +or if you use SSH authentication, ```bash > git clone --recursive git@github.com:GeoscienceAustralia/ga-aem.git ``` ## Submodules -The ga-aem project has several source code dependencies that are included as git submodules from other open-source projects. The submodules are only required for building the programs and are not required if you are just using precompiled executables. See [*here*](./submodules/README.md) for details of how the submodules should be initialised and updated. +The ga-aem project has several source code dependencies that are included as git submodules from other open-source projects. The submodules are only required for building the programs and are not required if you are just using precompiled executables. See [*here*](./submodules/README.md) for details of how the submodules should be initialized and updated. ## Third-party library dependencies For full functionality and to build all programs the following packages are required: FFTW, MPI, NetCDF, GDAL and PETSc. @@ -61,25 +63,25 @@ For full functionality and to build all programs the following packages are requ - FFTW - required for galeisbstdem.exe, galeisbstdem-nompi.exe, garjmcmctdem.exe, galeiallatonce.exe, Matlab and Python interfaces. - MPI - - optional for galeisbstdem.exe - - required for garjmcmctdem.exe and galeiallatonce.exe + - optional for galeisbstdem.exe. + - required for garjmcmctdem.exe and galeiallatonce.exe. - NetCDF - - optional for galeisbstdem.exe and galeisbstdem-nompi.exe - - required for garjmcmctdem.exe + - optional for galeisbstdem.exe and galeisbstdem-nompi.exe. + - required for garjmcmctdem.exe. - GDAL - - required only for ctlinedata2slicegrids.exe and ctlinedata2curtainimage.exe + - required only for ctlinedata2slicegrids.exe and ctlinedata2curtainimage.exe. - PETSc - - required only for galeiallatonce.exe + - required only for galeiallatonce.exe. # Building (compiling and linking) the code - The programs can be built from source code on both Linux and Windows systems, and probably other architectures. -- The build system uses CMake (>=v3.16) software. -- Traditional Makefiles are deprecated in this release of ga-aem. -- It is typically simpler to build the code on Linux, however note that Windows users can build and run the code easily on the free [*Ubuntu 20.04*](https://www.microsoft.com/en-au/p/ubuntu-2004/9n6svws3rx71#activetab=pivot:overviewtab) emulator app available free from the Microsoft Store. -- Nevertheless, the code definitely can be built on Windows with CMake or with the Microsoft Visual Studio IDE. +- The ga-aem project make use of the [*CMake*](#building-with-cmake) (>=v3.16) software. +- It is typically simpler to build the code on Linux, however note that Windows users can build and run the code easily on the free [*Ubuntu 20.04*](https://www.microsoft.com/en-au/p/ubuntu-2004/9n6svws3rx71#activetab=pivot:overviewtab) emulator app available from the Microsoft Store. +- Nevertheless, the code definitely can be built on Windows with CMake or with the [*Microsoft Visual Studio IDE*](#building-on-windows-with-the-microsoft-visual-studio-ide). +- Traditional Makefiles are now deprecated in ga-aem. -## Building using CMake -- CMake can be downloaded from https://cmake.org/download. +## Building with CMake +- CMake can be downloaded from *https://cmake.org/download*. - The CMake program uses the file [*CMakeLists.txt*](CMakeLists.txt) to build the executables and libraries. Unless you really know what you are doing do not edit this file. - CMake involves a generate step, a build step, and an install step. - The most basic way to use CMake is as follows: @@ -146,19 +148,19 @@ This may be useful if, for example, you do not have them installed or do not nee cmake --install . --prefix %LocalAppData%\GA-AEM ``` ## Building on Windows with the Microsoft Visual Studio IDE -- On Windows systems you can build the programs with the free Microsoft Visual Studio 2019 (or later) software in a GUI based integrated development environment (IDE). This is in fact how the code has been developed. +- On Windows systems you can build the programs with the [*Microsoft Visual Studio*](https://visualstudio.microsoft.com) 2019 (or later) software in a GUI based integrated development environment (IDE). This is in fact how the code has been developed. +- Be certain to select and install the ***`Desktop development with C++`*** workload in the Visual Studio installer. - For convenience Microsoft Visual Studio project, solution and property sheet files are supplied. However some path updates will be required depending on how/where you have installed the third-party dependency libraries. -- See [*here*](visualstudio/README.md) for more details. +- See [*here*](visualstudio/README.md) for more details on how to build ga-aem using the Microsoft Visual Studio IDE. # Releases ## Release-20240424 - To be completed - ## Release-20160606 - Added Python 3.x interface for simple forward modelling and derivatives only. - Added Matlab interface for simple forward modelling and derivatives only. -- Changed how the PPM normalisation is carried out. Now PPM normalisation is by directional-component-wise with respect to the maximum primary dB/dt or B-field at the receiver for a reference system geometry (which is usually estimated on a per flight or per survey basis). Previously PPM normalisation was with respect to the system geometry for the forward model being run. +- Changed how the PPM normalization is carried out. Now PPM normalization is by directional-component-wise with respect to the maximum primary dB/dt or B-field at the receiver for a reference system geometry (which is usually estimated on a per flight or per survey basis). Previously PPM normalization was with respect to the system geometry for the forward model being run. - Added GEOTEM (1996 ppm system) and SPECTREM (ppm system) examples. - Fixed a bug in the thickness derivative of the second bottom layer. This may have effected few-layer inversions, but not multi-layer fixed-thickness inversion. ## Release-20160428 diff --git a/matlab/README.md b/matlab/README.md index 9e7aabb..d544fbf 100644 --- a/matlab/README.md +++ b/matlab/README.md @@ -1,7 +1,7 @@ # GA-AEM Matlab forward modelling interface ## 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. +The MATLAB interface consists of a C callable shared library 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. ## 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. @@ -11,7 +11,7 @@ First the shared library needs to be built with CMake. See one of the CMake bui - [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 -- [ga-aem-install-dir]/matlab/rjmcmctdem_functions contains the wrapper functions MATLAB scripts .m for handling Monte-Carlo invesrion outputs +- [ga-aem-install-dir]/matlab/rjmcmctdem_functions contains the wrapper functions MATLAB scripts .m for handling Monte-Carlo inversion outputs - [ga-aem-install-dir]/matlab/examples contains examples of how to use the gatdaem1d module # Notes diff --git a/python/README.md b/python/README.md index b61b522..b424f50 100644 --- a/python/README.md +++ b/python/README.md @@ -1,7 +1,7 @@ # 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. +The Python (>=v3.5) interface consists of a C/C++ shared library (.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. diff --git a/visualstudio/README.md b/visualstudio/README.md index c2d7eb1..0cdd177 100644 --- a/visualstudio/README.md +++ b/visualstudio/README.md @@ -1,7 +1,8 @@ -# Sub-directory visualstudio\ +# Microsoft Visual Studio projects for GA-AEM ## Description -On Windows systems you can build the programs with the free Microsoft Visual Studio 2019 (or later) software in a GUI based integrated development environment (IDE). This is in fact how the code has been developed. +On Windows systems you can build the programs with the [Microsoft Visual Studio](https://visualstudio.microsoft.com) 2019 (or later) software in a GUI based integrated development environment (IDE). This is in fact how the code has been developed. +- Be certain to select and install the ***`Desktop development with C++`*** workload in the Visual Studio installer. - The visualstudio sub-directory contains the project, solution, and property-sheet files for building the various programs and libraries with the Microsoft Visual Studio C++ compiler (MSVC). - However some path updates will be required depending on how/where you have installed the third-party dependency libraries. - The programs are known to be successfully built with VS2019 and VS2022 on Windows 11. @@ -9,7 +10,7 @@ On Windows systems you can build the programs with the free Microsoft Visual Stu - These notes only apply to Windows systems. ## Contents -The sub-directories are organised as follows: +The sub-directories are organized as follows: - bin\ - Compiled and linked 64 bit program executables. - Release versions end up in x64\Release. @@ -18,7 +19,7 @@ The sub-directories are organised as follows: - lib\ - Compiled and linked 64 bit libraries. - Release versions end up in x64\Release. - - Delease versions end up in x64\Debug. + - Release versions end up in x64\Debug. - propertysheets\ - Property sheets that help set up of the compiler paths and options for various packages. Some path updates will be required depending on how/where you have installed the third-party dependency libraries on your system. - ga-aem-all\ @@ -47,28 +48,27 @@ The following sub-folders contain the individual program/library project and sol To build all programs plus the matlab and python shared libraries. 1. Open Microsoft Visual Studio 2019 or later 2. File | Open Project -3. In the Open Project/Solution dialog box navigate to, select, and then open \visualstudio\ga-aem-all\ga-aem-all.sln +3. In the Open Project/Solution dialog box navigate to, select, and then open \visualstudio\ga-aem-all\ga-aem-all.sln 4. Choose Build | Build Solution Alternatively to build just an individual program, for example galeisbstdem 1. Open Microsoft Visual Studio 2019 or later 2. File | Open Project -3. In the Open Project/Solution dialog box navigate to, select, and then open \visualstudio\galeisbstdem\galeisbstdem.sln +3. In the Open Project/Solution dialog box navigate to, select, and then open \visualstudio\galeisbstdem\galeisbstdem.sln 4. Choose Build | Build Solution ### Note on the Matlab and Python shared library outputs - The Matlab shared library MEX file (.mexe64) will be output to the directory - - \matlab\bin\gatdaem1d.mexw64 + - \matlab\bin\gatdaem1d.mexw64 - The Python shared library (.dll) file will be output to the directory - - \python\gatdaem1d\gatdaem1d.dll + - \python\gatdaem1d\gatdaem1d.dll ### Environment variables - The Visual Studio project files rely on some environment variable to be set so that the include and library files of the external packages can be found. -- To build all programns the following variables would need to be set: FFTW_DIR, MATLAB_ROOT, MSMPI_BIN, MSMPI_INC, MSMPI_LIB64, GDAL_ROOT, GDAL_DATA, PROJ_LIB, NETCDF_ROOT, PETSC_DIR, PETSC_BIN. +- To build all programs the following variables would need to be set: FFTW_DIR, MATLAB_ROOT, MSMPI_BIN, MSMPI_INC, MSMPI_LIB64, GDAL_ROOT, GDAL_DATA, PROJ_LIB, NETCDF_ROOT, PETSC_DIR, PETSC_BIN. - For example, on the Windows 11 system used for development, the following variables were set: ```text FFTW_DIR=%LocalAppData%\fftw-3.3.5-dll64 - MATLAB_ROOT=C:\Program Files\MATLAB\R2022b MSMPI_BIN=C:\Program Files\Microsoft MPI\Bin\ MSMPI_INC=C:\Program Files (x86)\Microsoft SDKs\MPI\Include\ MSMPI_LIB64=C:\Program Files (x86)\Microsoft SDKs\MPI\Lib\x64\ @@ -78,9 +78,10 @@ Alternatively to build just an individual program, for example galeisbstdem NETCDF_ROOT=C:\Program Files\netCDF 4.9.2 PETSC_DIR=%LocalAppData%\petsc\3.9.4\vs2017 PETSC_BIN=%PETSC_DIR%\win64_release\lib + MATLAB_ROOT=C:\Program Files\MATLAB\R2022b ``` -- Generally %LocalAppData% is typically `C:\Users\\AppData\Local`. -- These need to be adjusted according where your particular packages are installed. +- Typically %LocalAppData% is located at `C:\Users\\AppData\Local`. +- These paths need to be adjusted according to where your particular packages are installed. ## Install Instructions It might be convenient to run the script ***create_package.bat*** after building the executables and libraries.