Update documentation for 3.5 release

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/GLOBAL_ARRAYS.md

@@ -41,15 +41,48 @@ 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

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.