Update documentation for 3.5 release

README.md

@@ -18,7 +18,7 @@ In addition, GridPACK is also a framework to simplify the development of new app
 See the [instructions](docs/markdown/BASIC_INSTALL.md) for installing GridPACK, prerequisite software, and installation notes for different platforms.
 
 ## Usage
-See [User manual](docs/user_manual/GridPACK.pdf) for a deep dive on GridPACK internals and/or refer to the [tutorials](docs/markdown/TUTORIALS.md) for more info. 
+See the PDF [User manual](docs/user_manual/GridPACK.pdf) for a deep dive on GridPACK internals and/or refer to the [tutorials](docs/markdown/TUTORIALS.md) for more info.  There is also an online version of the user manual available at [https://github.com/GridOPTICS/GridPACK/tree/feature/documentation-3.5/docs/user_manual/web/GridPACK.html](https://github.com/GridOPTICS/GridPACK/tree/feature/documentation-3.5/docs/user_manual/web/GridPACK.html).
 
 - Quick Guide (To do)
 

docs/markdown/BASIC_INSTALL.md

@@ -1,8 +1,24 @@
-# GridPACK step=by-step installation instructions
+# GridPACK step-by-step installation instructions
 This document provides a step-by-step guide to install GridPACK and its
 dependencies. They are meant to be used with GridPACK's develop branch. The
 installation instructions have been tested on Linux, MacOS, and Ubuntu. 
 
+GridPACK includes two scripts that can be used to build GridPACK and its
+dependencies. These are not guaranteed to work for all Linux platforms, but they
+are likely to work for many configurations and we recommend that you try them
+first before building GridPACK and its dependencies by hand. Both scripts can be
+found in the top level GridPACK directory. The
+[install_gridpack_deps.sh](../../install_gridpack_deps.sh) script can be used to
+build all modules needed by GridPACK and the
+[install_gridpack.sh](../../install_gridpack.sh) script can be used to
+build GridPACK itself. You may be able to get these to work on you platform with
+some minor edits. If you are not interested in building GridPACK with the python
+interface, you should set the `install_gridpack_python` variable in
+[install_gridpack.sh](../../install_gridpack.sh) to false. If the
+`install_gridpack` scripts do not work on your platform, it will be necessary to
+build GridPACK and its dependencies by hand. Instructions for doing so are given
+in the following.
+
 ## Prerequisite software
 Before building GridPACK using these instructions, you will need to make sure that
 - CMake is available on your system (version newer than 3.5.0) 
@@ -90,7 +106,8 @@ More information on building and installing GA can be found
 ## <b>Step 3: Install PETSc 3.16.4</b>
 Step 3.1. Download PETSc release
 ```
-git clone https://gitlab.com/petsc/petsc.git
+git clone https://gitlab.com/petsc/petsc.githttps://gitlab.com/petsc/petsc.git
+git checkout v3.16.4
 ```
 
 Step 3.2.

docs/markdown/required/BOOST.md

@@ -51,9 +51,9 @@ Boost configuration in GridPACK should report the results
 ```
 
 If you need to build Boost yourself, refer to the documentation on building
-GridPACK on individual platforms for additional details on build Boost. If an
-attempt to configure and build Boost fails, it usually is a good idea to fix the
-build script and then remove the existing Boost directory and create a new one
+GridPACK on individual platforms for additional details. If an attempt to
+configure and build Boost fails, it usually is a good idea to fix the build
+script and then remove the existing Boost directory. Create a new Boost directory
 by untarring the Boost tarball. Attempts to resume a failed Boost build after
 fixing the build script are usually unsuccessful.
 
@@ -96,17 +96,7 @@ replace the first line in the above script with
 
 Make sure you include the spaces around ":" and before ";".
 
-Boost has a tendency to use cutting-edge features of the C++ compiler so it is a
-good idea to use a compiler version that was released at the same time as the
-Boost version you are working with. If you are having problems, you may have
-better luck moving to an earlier version of Boost. If the Boost build fails, you
-should delete the entire boost directory and start from scratch after making
-corrections to your build script. Restarting a failed Boost build does not
-appear to work in most instances.
-
-If you want to use Intel compilers modify the `--with-toolset=gcc` line to
-`--with-toolset=intel-linux`. For shared library builds, modify the two link lines
-to
+To build Boost as a shared library, modify the two link lines to
 
 ```
     ./b2 -a -d+2 link=shared stage

docs/markdown/required/GLOBAL_ARRAYS.md

@@ -33,26 +33,59 @@ depends on the runtime used to build GA and should only be set to `TRUE`
 if GA was configured using the `--with-mpi-pr` option.
 
 We have used two different configurations of GA to build and run GridPACK.
-For any system with a working version of MPI, you can
-use the MPI two-sided runtime or the progress ranks runtime with GA. Use the
-`--with-mpi-ts` or `--with-mpi-pr` options when configuring GA.
+For any system with a working version of MPI, you can build GA with the MPI
+two-sided runtime or the progress ranks runtime with GA. These can be accessed
+by configuring GA with the `--with-mpi-ts` or `--with-mpi-pr` options,
+respectively.
 The two-sided runtime is the simplest runtime and is suitable for workstations
 with a limited number of cores. This runtime provides reasonable performance on
 a small number of cores but slows down considerably at larger core counts(our
 experience is that you should limit this runtime to 8 or less processors). It is
 not recommended for large-scale parallel computation.  The progress ranks
-runtime is much higher performing and approaches the performance of the OpenIB
-runtime. It is very reliable and runs on any platform that supports MPI.
+runtime is much higher performing.
+It is very reliable and runs on any platform that supports MPI.
 However, it has one peculiarity in that it reserves one MPI process on each SMP
 node to act as a communication manager. Thus, if you are running your
 calculation on 2 nodes with 5 processes on each node, the GridPACK application
 will only see 8 processes (4 on each node). To make sure that the GridPACK build
 is aware of this, the `USE_PROGRESS_RANKS` parameter should be set to
 `TRUE` when using the progress ranks build of GA.
 
+A comparison of the performance of the progress ranks and two-sided runtimes is
+shown below in Figure 1 for the Polish network test calculation included as
+part of the
+contingency analysis application. Contingency analysis consists of many
+individual tasks that can be distributed at runtime to different processors.
+The progress ranks runtime shows significantly
+better performance for all process counts, especially after four processors or
+so. After 16 processors, the performance of the two-sided runtime has degraded
+to the point that the overall runtime for the calculation starts increasing.
+
+<img src="../images/Polish_CA.png" alt="drawing" width="600"/>
+
+**Figure 1:** Comparison of speedup for the progress ranks and two-sided runtimes
+for a contingency analysis calculation using the Polish network data set.
+
+Dynamic simulation has different features with respect to parallelization
+compared to contingency analysis. A comparision of the progress ranks and
+two-sided runtimes is shown in Figure 2 for a simulation on a 12,000 bus
+model of the
+WECC network. In this case the performance is comparable up to 16 processors.
+The dynamic simulation calculation is more tightly coupled than contingency
+analysis and data must be exchanged at a finer level than individual
+simulations. Because of this, individual dynamic simulation calculations do not
+show speedup beyond the point at which the calculation is divided up between two
+SMP nodes. For the computer used in this calculation, this point is reached at
+16 processors.
+
+<img src="../images/WECC_DS.png" alt="drawing" width="600"/>
+
+**Figure 2:** Comparison of speedup for the progress ranks and two-sided runtimes
+for a single dynamic simulation calculation using a 12,000 bus WECC network data
+set.
+
 Global Arrays is a relatively straightforward build if MPI is available on your
-system. To configure GA with the basic two-sided runtime (suitable for
-workstations with a limited number of cores) use the configuration line
+system. To configure GA with the basic two-sided runtime use the configuration line
 
 ```
 ../configure --enable-i4 --enable-cxx --without-blas --disable-f77 \
@@ -63,11 +96,8 @@ workstations with a limited number of cores) use the configuration line
 This configuration line assumes that the build directory is located directly
 below the top level GA directory. If you want to build someplace else, the `../`
 before `configure` needs to be replaced with the path to `configure`.
-The two-sided build will work with almost any version of MPI and is easy to use
-but is
-slow for more than a few processors. For higher performance, particularly on
-clusters with a high performance network, the progress ranks runtime is
-preferable. To configure GA with this runtime, use the configure command
+To configure with the higher performing progress ranks runtime,
+configure GA with the command
 
 ```
 ../configure --enable-i4 --enable-cxx --with-mpi-pr --without-blas --disable-f77

docs/markdown/required/LINUX_BASICS.md

@@ -79,8 +79,7 @@ include them in your configure script!
 
 For most systems, it is possible to install CMake using modules or an
 installation capability such as `yum`.  In the case that this is not possible
-or your version is too old, you can build it using the
-commands below.
+or your version is too old, you can build it using the commands below.
 
 You will need
 to start by downloading the CMake tar file (e.g. cmake-3.24.3.tar.gz) from the
@@ -154,7 +153,7 @@ build the libraries.
 
 The most direct way to download tar files on a Linux machine is to use a web
 browser such as Firefox to download files to a local download directory. These
-can then be moved to another location such are your GridPACK software directory.
+can then be moved to another location such as your GridPACK software directory.
 
 If, for some reason, you do not have a web browser on your machine, you can use
 the `wget` command. This has the form

docs/user_manual/GridPACK.tex

@@ -7,6 +7,7 @@
 \usepackage{amsmath}
 \usepackage{txfonts}
 \usepackage{mathdots}
+\usepackage{microtype}
 \usepackage[classicReIm]{kpfonts}
 \usepackage[dvips]{graphicx} %%% use 'pdftex' instead of 'dvips' for PDF output
 \usepackage{xcolor}
@@ -26,7 +27,7 @@
 \begin{document}
 
 \title{GridPACK$\mathrm{{}^{TM}}$ User Manual}
-\author{B. Palmer}
+\author{B. Palmer, W. Perkins, S. Abhyankar}
 \date{\today}
 \maketitle
 

docs/user_manual/tex/adv_network.tex

@@ -16,43 +16,44 @@ \section{Advanced Network Functionality}
 {
 \color{red}
 \begin{Verbatim}[fontseries=b]
-bool setGlobalBusIndex(int idx, int gdx);
+bool setGlobalBusIndex(int ldx, int gdx);
 \end{Verbatim}
 }
 
-The argument \texttt{\textbf{idx}} is the local index of the bus in the network, the argument \texttt{\textbf{gdx}} is the global index assigned by the user. This function will return false if the local index exceeds the number of buses on the processor. The existing GridPACK parsers assign the original index based on the index used in the configuration file and the global index based on the position of the bus in the configuration file. For other sources, it may be necessary for users to develop their own strategies for assigning indices.
+The argument \texttt{\textbf{ldx}} is the local index of the bus in the network, the argument \texttt{\textbf{gdx}} is the global index assigned by the user. This function will return false if the local index exceeds the number of buses on the processor. The existing GridPACK parsers assign the original index based on the index used in the configuration file and the global index based on the position of the bus in the configuration file. For other sources, it may be necessary for users to develop their own strategies for assigning indices.
 
 Once the bus has been added, its properties can be modified using methods in the \texttt{\textbf{BaseBusComponent}} class. Note that creating the bus simultaneously creates the associated \texttt{\textbf{DataCollection}} object. This can be accessed using the network function
 
 {
 \color{red}
 \begin{Verbatim}[fontseries=b]
-boost::shared_ptr<DataCollection> getBusData(int idx);
+boost::shared_ptr<DataCollection> getBusData(int ldx);
 \end{Verbatim}
 }
 
-where \texttt{\textbf{idx}} is once again the local bus index. Once the data collection object is available, properties can be added to it as described earlier.
+where \texttt{\textbf{ldx}} is once again the local bus index. Once the data collection object is available, properties can be added to it as described earlier.
 
 New buses are added to the system with the assumption that they are local to the processor. This means the ``active'' flag is originally set to true. The partitioner can then be used to redistribute buses and branches and add ghost components. If the user wants to set their own local/ghost status, then this can be done through the function
 
 {
 \color{red}
 \begin{Verbatim}[fontseries=b]
-bool setActiveBus(int idx, bool flag);
+bool setActiveBus(int ldx, bool flag);
 \end{Verbatim}
 }
 
-The index \texttt{\textbf{idx}} is a local index, \texttt{\textbf{flag}} is the status of the bus (true for local buses, false for ghost buses) and the function returns false if the local bus index does not correspond to a bus on the process.
+The index \texttt{\textbf{ldx}} is a local index, \texttt{\textbf{flag}} is the status of the bus (true for local buses, false for ghost buses) and the function returns false if the local bus index does not correspond to a bus on the process.
 The status of a bus as a reference bus can be set using the function
 
 {
 \color{red}
 \begin{Verbatim}[fontseries=b]
-void setReferenceBus(int idx);
+void setReferenceBus(int ldx);
 \end{Verbatim}
 }
 
-where \texttt{\textbf{idx}} is a local index.By default, buses are created as ordinary buses.
+where \texttt{\textbf{ldx}} is a local index.By default, buses are created as ordinary buses.
+
 Branches can be added to the system using a similar set of functions. Note that there is no requirement that branches be created on processes that contain either of the endpoint buses. In an extreme case, the complete set of buses and branches can be created on separate processes. To add a new branch to the system, the user must supply the original indices of the buses at each end of the branch and a global index for each individual branch. Again, the global index runs consecutively from 0 to M-1, where M is the total number of unique branches in the system. A new branch is added to the network using the function
 
 {
@@ -67,29 +68,29 @@ \section{Advanced Network Functionality}
 {
 \color{red}
 \begin{Verbatim}[fontseries=b]
-bool setGlobalBranchIndex(int idx, int gdx);
+bool setGlobalBranchIndex(int ldx, int gdx);
 \end{Verbatim}
 }
 
-where \texttt{\textbf{idx}} is the local index of the branch on the processor and \texttt{\textbf{gdx}} is the global index. As in the case of buses, the complicated part of adding a branch to the network is to determine a global index for the branch.
+where \texttt{\textbf{ldx}} is the local index of the branch on the processor and \texttt{\textbf{gdx}} is the global index. As in the case of buses, the complicated part of adding a branch to the network is to determine a global index for the branch.
 When a branch is created, a \texttt{\textbf{DateCollection}} object for the branch is created along and can be accessed using
 
 {
 \color{red}
 \begin{Verbatim}[fontseries=b]
-boost::shared_ptr<DataCollection> getBranchData(int idx);
+boost::shared_ptr<DataCollection> getBranchData(int ldx);
 \end{Verbatim}
 }
 
-where \texttt{\textbf{idx}} is the local index of the branch. Once a pointer to the data collection object is available, parameters can be added to it or modified as described earlier. The active status of the branch can be set with
+where \texttt{\textbf{ldx}} is the local index of the branch. Once a pointer to the data collection object is available, parameters can be added to it or modified as described earlier. The active status of the branch can be set with
 
 {
 \color{red}
 \begin{Verbatim}[fontseries=b]
-bool setActiveBranch(int idx, bool flag);
+bool setActiveBranch(int ldx, bool flag);
 \end{Verbatim}
 }
 
-The arguments \texttt{\textbf{idx}} and \texttt{\textbf{flag}} are the local branch index and the branch status and the function returns false if the local index is not in the range of branches on the processor.
+The arguments \texttt{\textbf{ldx}} and \texttt{\textbf{flag}} are the local branch index and the branch status and the function returns false if the local index is not in the range of branches on the processor.
 
 These functions are all that is needed to create a network from scratch or to write a parser for a new network configuration file format. These are currently used in the PSS/E parser classes to implement the network setup functionality.