Merge branch 'develop' into fism

Author: aaronjridley

.gitignore

@@ -9,14 +9,15 @@
 
 # Run and build directories
 run/
-run.test/
+run*/
 build/
 
 # Doxygen generated files
 doc/generated
 
 # Python extras
 __pycache__
+.ipynb_checkpoints
 
 # autogenerated files
 tags

CMakeLists.txt

@@ -18,6 +18,7 @@ endif()
 
 # Directory variables
 file(GLOB SRC_FILES ${PROJECT_SOURCE_DIR}/src/*.cpp)
+file(GLOB TEST_FILES ${PROJECT_SOURCE_DIR}/srcTest/*.cpp)
 set(MAIN_DIR ${PROJECT_SOURCE_DIR}/src/main)
 set(TESTS_DIR ${PROJECT_SOURCE_DIR}/tests)
 set(OUT_DIR ${PROJECT_SOURCE_DIR}/src/output)
@@ -34,7 +35,7 @@ elseif(TEST_EXCHANGE)
 elseif(TEST_GRADIENT)
   add_executable(aether ${SRC_FILES} ${MSIS_FILES} ${MAIN_DIR}/main_test_gradient.cpp)
 else()
-  add_executable(aether ${SRC_FILES} ${MSIS_FILES} ${IE_FILES} ${MAIN_DIR}/main.cpp)
+  add_executable(aether ${SRC_FILES} ${TEST_FILES} ${MSIS_FILES} ${IE_FILES} ${MAIN_DIR}/main.cpp)
 endif()
 
 if(USE_DOUBLE_PRECISION)
@@ -100,6 +101,14 @@ if (USE_NETCDF)
   target_link_libraries(aether PUBLIC ${NETCDF_LIBRARIES_C})
 endif()
 
+# use_old_timing
+# cmake -DUSE_OLD_TIMING=ON ..
+option(USE_OLD_TIMING "Use old timing for performance - default is off" OFF)
+if (USE_OLD_TIMING)
+  add_definitions(-DOLD_TIMING)
+  set(OLD_TIMING "YES")
+endif()
+
 # Set up links for executable
 file(CREATE_LINK ${CMAKE_BINARY_DIR}/aether
                  ${PROJECT_SOURCE_DIR}/share/run/aether SYMBOLIC)

CONTRIBUTING.md

@@ -34,29 +34,20 @@ on WSL with Ubuntu, the command seems to be:
 
 astyle --options=.astylerc src/*.cpp
 
-#### Linting
+Astyle can also be used within VSCode as an extension. Install the "Astyle" extension (author: Chieh Yu).  Then go to settings (the "Manage" wheel on the bottom left, then click on "settings"). Under "Extensions", click on "Astyle Configuration".  Within that, you can set the location of the astylerc file. Click on "Edit in settings.json". Modify the file so it has the following line:
+    "[cpp]": {
+        "editor.defaultFormatter": "chiehyu.vscode-astyle",
+        "editor.formatOnSave": true
+    },
+    "astyle.astylerc": "${workspaceRoot}/.astylerc"
 
-For *C++* code make sure to use a static code checker like
-[cpplint](https://github.com/cpplint/cpplint) to check the code for
-any style issues before submitting.  For *Python*,
-[flake8](https://flake8.pycqa.org/en/latest/) is a good option.  Both
-of these may by installed using pip.
+This should then allow you to format the code using the defaults that we have set in the astyle file. This can be done with (Ctrl-Shift-I for Linux, Alt-Shift-F for Windows) and upon saving the file - this reformats the whole file to put it into the astyle format.
 
-To install `cpplint`
+#### Linting
 
-```sh
-# depending on your system one of these lines applies
-pip install --user cpplint
-pip install cpplint
-python3 -m pip cpplint
-python3 -m pip --user cpplint
-```
+For *Python*,
+[flake8](https://flake8.pycqa.org/en/latest/) is a good option.  This may by installed using pip.
 
-Using a linter in an editor is a good supplement, but not a replacement for the
-static linters. The linter in the 'atom' editor requires that you install the
-`linter` and `gcc-linter` packages. Atom also has additional packages
-`whitespaces` and `tabs-to-spaces` to automatically remove whitespaces at the
-end of the lines, and convert tabs to spaces.
 
 ## Commit Styling
 

README.md

@@ -19,14 +19,14 @@ developed.
 
 ## Contents
 
-- [Aether](#aether)
-  - [Contents](#contents)
-  - [Quick Start](#quick-start)
-    - [Dependencies](#dependencies)
-    - [Getting the Code](#getting-the-code)
-    - [Compiling \& Running](#compiling--running)
-  - [Code Manual](#code-manual)
-  - [Further Documentation](#further-documentation)
+- [Contents](#contents)
+- [Quick Start](#quick-start)
+  - [Dependencies](#dependencies)
+  - [Getting the Code](#getting-the-code)
+  - [Compiling \& Running](#compiling--running)
+  - [Inputs](#inputs)
+- [Code Manual](#code-manual)
+- [Further Documentation](#further-documentation)
 
 ## Quick Start
 
@@ -141,9 +141,16 @@ structure like this:
 cd ..
 cp -R share/run ./run.test
 cd run.test
-./aether
+mpirun -np 4 ./aether
 ```
 
+This will run the default configuration of Aether, which requires four MPI processors.
+The default grids are `sphere4` and `dipole4` for the neutrals and ions (respectively),
+which both require four "root nodes", or MPI workers. To read more about root nodes and
+the available grids, please see [this page in the documentation](doc/internals/grid.md).
+
+### Inputs
+
 There are essentially two input files that specify the settings in the code.
 When you are in a run directory, they are:
 

doc/README.md

@@ -32,6 +32,7 @@ Contents within `doc`:
   - [Ensembles](internals/ensembles.md)
   - [Indices](internals/indices.md)
   - [The Grid](internals/grid.md)
+  - [Coordinate Systems](internals/coordinates.md)
 - [Doxyfile](Doxyfile)
 - [README (this page)](README.md)
 - [Citations](citations.md)

doc/installation/dependencies.md

@@ -21,28 +21,35 @@ If a path is printed, `cmake` is installed. To check the version, run `cmake
 The layout of this page is as follows:
 
 - [Installing Dependencies](#installing-dependencies)
-  - [Install gcc](#install-gcc)
+  - [Install Compiler](#install-compiler)
   - [Install cmake](#install-cmake)
   - [Install JSON libraries](#install-json-libraries)
   - [Install Armadillo (and boost)](#install-armadillo-and-boost)
   - [Install NetCDF (optional)](#install-netcdf-optional)
 
-## Install gcc
+## Install Compiler
 
-This comes installed by default on Ubuntu. On MacOS this can be installed, for
-example, using:
+On MacOS this can be installed, for example, using:
 
 ```bash
-sudo port install gcc11
+sudo port install g++
 ```
 
-> As development began, gcc11 was the latest version; there are newer versions
-> of `gcc` available now (latest version is gcc14), which have not yet been
-> validated.
+> NOTE: On Macos, cmake will default to using clang instead of gcc.
+You need to set an environmental variable to tell cmake to use g++ instead. 
+Do this with `export CXX=/opt/local/bin/g++`,
+and replace the path if it is placed somewhere different.
+
+On Ubuntu, `gcc` (the C-compiler) is pre-installed, but the C++ compiler is not. This 
+can be installed with (subsituting your machine's package manager command):
+
+```bash
+sudo apt install g++
+```
 
 ## Install cmake
 
-Aether uses [CMake](https://cmake.org/) instead of `make`. If you don't have it
+Aether uses [CMake](https://cmake.org/) instead of GNU make. If you don't have it
 installed, you need it.
 
 For MacOS, this can be installed with:
@@ -57,7 +64,7 @@ For Ubuntu/Debian Linux:
 sudo apt install cmake
 ```
 
-This can be done on RedHat using yum also.
+This can be done on RedHat using `yum` also.
 
 ## Install JSON libraries
 
@@ -100,7 +107,7 @@ sudo port install lapack
 sudo port install OpenBLAS
 sudo port install boost
 sudo port install armadillo
-sudo port install openmpi-bin libopenmpi-dev
+sudo port install openmpi
  ```
 
 ## Install NetCDF (optional)
@@ -119,7 +126,7 @@ sudo port install netcdf-cxx4
 If you want the gcc version of netcdf, then:
 
 ```bash
-sudo port install netcdf-cxx4 +gcc10
+sudo port install netcdf-cxx4
 ```
 
 On Ubuntu, gcc is the default compiler, it seems like you can probably just do:

doc/installation/installation.md

@@ -97,10 +97,10 @@ Here `FLAG` is a flag name and `VALUE` is the desired value (note the `-D`).  A
 more complete discussion of the available compilation flags can be found on the
 [Compilation Options](build_opts.md) page.
 
-If your default compiler isn't a GCC compiler, you will likely need to specify
-the desired GCC compiler at this step using:
+> If your default compiler isn't a GCC compiler, you will likely need to specify
+the desired GCC compiler at this step using the environmental variable `$CXX`, or:
 
-```bash
+> ```bash
 cmake -DCMAKE_CXX_COMPILER=<gcc or mpi executable with full path>
 ```
 

doc/internals/coordinates.md

@@ -20,15 +20,16 @@
 
 ## Dipole Coordinates
 - Longitude (radians) - radians east of the meridian that contains the north magnetic pole and north rotation axis
-- P (?) - Identifies the field line, related to L-shell
-- Q (meters?) - The distance along the field line from some reference point, related to magnetic latitude.
+- P (meters) - Identifies the field line. This is the same as L-shell and is constant along wach field line.
+- Q (dimensionless) - parameterizes the distance along the field line, related to magnetic latitude & radius. This varies along the field line, but the values are idential for all field lines within each node. q=0 at the equator, and approaches positive (negative) infinity as theta points towards the north (south) pole. Thus, q values will be negative in the southern hemisphere and the change in q "upwards" will be negative in the northern hemisphere. See [../../edu/examples/Dipole](../../edu/examples/Dipole) for more information.
 
 ## More Dipole Coordinates
 - L-shell (Planetary Radii) - The distance from the planet's center at which the magnetic field encounters the dipole's equatorial plane
-- Magnetic Latitude (radians) - angle between the dipole's equatorial plane and the point.
-- Invariant Latitude (degrees) - angle between the dipole's equatorial plane and the point at which the field-line passes through a reference radius of the planet.  This is constant along the field-line and is related to the L-Shell.
+- Magnetic Latitude (radians) - angle between the dipole's equatorial plane and a point.
+- Invariant Latitude (radians) - angle between the dipole's equatorial plane and the point at which the field-line passes through a reference radius of the planet ([specified in the inputs](../internals/grid.md#inputs)).  This is constant along the field-line and is related to the L-Shell.
 - Magnetic Local Time (hours) - Angle between the sun, the north magnetic pole, and the point. Explicitly, this is done in PSE XY coordinates, ignoring the Z coorinate.
 
+> The dipole `(i,j,k)` coordinates are (magnetic longitude, p, q).
 
 # Coordinates in Aether
 
@@ -46,12 +47,15 @@ Because Aether considers gravity to be a function of radius and explicitly inclu
 
 ## i, j, k Coordinates
 
-As described in the grid.md file, Aether uses a logical '(i, j, k)' 3D grid structure.  Therefore, we refer to the 'primary' coordinates as the ijk coordinate system.  What this means is that the i-coordinate is in the i-direction, the j-coordinate is in the j-direction, and the k-coordinate is in the k-direction.  
+As described in the grid.md file, Aether uses a logical `(i, j, k)` 3D grid structure.  Therefore, we refer to the 'primary' coordinates as the ijk coordinate system.  What this means is that the i-coordinate is in the i-direction, the j-coordinate is in the j-direction, and the k-coordinate is in the k-direction.  
 
 For the (perfectly) spherical grid, the i-coordinate is longitude, the j-coordinate is latitude, and the k-coordinate is radius.
 
 For the Cubedsphere grid, the i-coordinate is RIGHT, the j-coodinate is UP, and the k-coordinate is radius.  Each face of the cubedsphere has the same coordinate system, but only with reference to that face.  This means that if each face is looked at independently, the lower left corner is at (about) i = -45, j = -45 deg, while the upper right corner is at i = +45, j = +45 deg. Radius is treated the same as in a spherical grid.
 
+For the dipole coordinate system, the i-coordinate is magnetic longitude, the j-coordinate is L-shell, and the k-coordinate is Q: a dimensionless parameter, normalized to the planet radius, representing diatance along a magnetic field line. The dipole is orthogonal to a dipolar magnetic field.
+
+
 Should the official coordinates be in the native coordinates (which could be different for each system), or should the coordinates be in meters, such that when gradients are taken, they are in /m?
 
 Maybe we could have:
@@ -69,6 +73,6 @@ Locations:
 All locations should be described in the following coordinates:
 - i, j, k
 - lon, lat, radius (+alt)
-- magnetic lon, invariant lat?
+- magnetic lon, invariant lat (only the dipole magnetic grid then has magnetic latitude)