From 05ba1475426e1b5f6e6126c6ccc806e9f586e071 Mon Sep 17 00:00:00 2001 From: Bruce J Palmer Date: Thu, 14 Dec 2023 08:56:57 -0800 Subject: [PATCH] Reviewed and updated some of the online and user manual documentation. --- docs/markdown/required/GLOBAL_ARRAYS.md | 3 +- docs/user_manual/tex/build.tex | 12 +++---- docs/user_manual/tex/buildapps.tex | 2 +- docs/user_manual/tex/framework.tex | 23 ++++++++++-- docs/user_manual/tex/intro.tex | 5 ++- docs/user_manual/tex/network.tex | 47 ++++++++++++++++--------- docs/user_manual/tex/readthisdoc.tex | 2 +- 7 files changed, 62 insertions(+), 32 deletions(-) diff --git a/docs/markdown/required/GLOBAL_ARRAYS.md b/docs/markdown/required/GLOBAL_ARRAYS.md index 506ebe201..63eae76e9 100644 --- a/docs/markdown/required/GLOBAL_ARRAYS.md +++ b/docs/markdown/required/GLOBAL_ARRAYS.md @@ -54,7 +54,8 @@ A comparison of the performance of the progress ranks and two-sided runtimes is shown below for the Polish network test calculation included as part of the contingency analysis application. The progress ranks runtime shows significantly better performance for all process counts, especially after four processors or -so. +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. drawing diff --git a/docs/user_manual/tex/build.tex b/docs/user_manual/tex/build.tex index d0fd1af96..85b19fbe5 100644 --- a/docs/user_manual/tex/build.tex +++ b/docs/user_manual/tex/build.tex @@ -11,9 +11,9 @@ \chapter{Configuring and Building GridPACK} This particular form assumes that the build directory is below the directory that contains the top-level \texttt{\textbf{CMakeLists.txt}} file for the build. For GridPACK, this is located in the \texttt{\textbf{src}} directory. If your build directory for GridPACK is below \texttt{\textbf{src}} and you invoke CMake from this directory, the ``\texttt{\textbf{..}}'' at the end of the \texttt{\textbf{cmake}} command is pointing to \texttt{\textbf{src}}. You could also use the absolute path to the \texttt{\textbf{src}} directory instead of ``\texttt{\textbf{..}}'' and this would work no matter where you locate the build directory. -Building GridPACK requires several external libraries that must be built prior trying to configure and build GridPACK itself. On some systems, these libraries may already be available but in many cases, users will need to build them by hand. An exception is MPI, which is usually available on parallel platforms, although users interested in running parallel jobs on a multi-core workstation may still need to build it themselves. In any case, the best way to guarantee that all libraries are compatible with each other is to build them all using a consistent environment and set of compilers. There is extensive documentation on how to build GridPACK and the libraries on which it depends on the website located at https://gridpack.org. We refer to the information on the website for most of the details on how to build GridPACK and will only discuss some general properties of the configure procedure in this document. +Building GridPACK requires several external libraries that must be built prior trying to configure and build GridPACK itself. On some systems, these libraries may already be available but in many cases, users will need to build them by hand. An exception is MPI, which is usually available on parallel platforms, although users interested in running parallel jobs on a multi-core workstation may still need to build it themselves. In any case, the best way to guarantee that all libraries are compatible with each other is to build them all using a consistent environment and set of compilers. There is extensive documentation on how to build GridPACK and the libraries on which it depends on the website located at \href{https://github.com/GridOPTICS/GridPACK}{https://github.com/GridOPTICS/GridPACK}. We refer to the information on the website for most of the details on how to build GridPACK and will only discuss some general properties of the configure procedure in this document. -Example scripts for building the libraries used by GridPACK on different systems can be found under \texttt{\textbf{\$GRIDPACK/src/scripts}}. In most cases these need to be modified slightly before they will work on your system, but the changes are usually small and self-evident. The scripts contain some additional documentation at the top to help you with these modifications. Find a script for a platform that is similar to your system and use this as the starting point for your build. +Example scripts for building the libraries used by GridPACK on different systems can be found under \texttt{\textbf{\$GRIDPACK/src/scripts}}. In most cases these need to be modified slightly before they will work on your system, but the changes are usually small and self-evident. The scripts contain some additional documentation at the top to help you with these modifications. Find a script for a platform that is similar to your system and use this as the starting point for your build. Addititional information for building on advanced platforms, such as DOE's Leadership Class Facilities, can be found in the \texttt{\textbf{\$GRIDPACK/docs/notes}} directory. This directory contains notes on building GridPACK on different platforms that may be useful to users trying to build on similar systems. Note that these systems can be quite complicated to build on for any application and usually require assistance from facility staff. GridPACK uses the CMake build system to create a set of make files that can then be used to compile the entire GridPACK framework. Most of the effort in building GridPACK is focused on getting the configure process to work, once configure has been successfully completed, compilation is usually straightforward. Builds of GridPACK should be done in their own directory and this also makes it possible to have multiple builds that use different configuration parameters associated with the same source tree. Typically, the build directories are under \texttt{\textbf{\$GRIDPACK/src}} directory but they can be put anywhere the user chooses. The user then needs to run CMake from the build directory to configure GridPACK and then \texttt{\textbf{make}} and \texttt{\textbf{make install}} to compile and install the GridPACK libraries. After running \texttt{\textbf{make}}, all applications in the GridPACK source tree are also available for use. The application executables will be located in the build directory and not in the source tree. @@ -34,7 +34,6 @@ \chapter{Configuring and Building GridPACK} '\$HOME/software_new/petsc-3.6.0/linux-openmpi-gnu-cxx/lib' \ -D GA_DIR:STRING='\$HOME/software_new/ga-5-4-ib' \ -D USE_PROGRESS_RANKS:BOOL=FALSE \ - -D GA_EXTRA_LIBS='-lrt -libverbs' \ -D MPI_CXX_COMPILER:STRING='mpicxx' \ -D MPI_C_COMPILER:STRING='mpicc' \ -D MPIEXEC:STRING='mpiexec' \ @@ -50,9 +49,8 @@ \chapter{Configuring and Building GridPACK} The Boost, PETSc, Parmetis and Global Array library locations are specified by the \texttt{\textbf{BOOST\_ROOT}}, \texttt{\textbf{PETSC\_DIR}}, \texttt{\textbf{PARMETIS\_DIR}} and \texttt{\textbf{GA\_DIR}} variables. The \texttt{\textbf{PETSC\_ARCH}} variable specifies the particular build within PETSc that you want GridPACK to use. It is usually possible when configuring and building PETSc to have it download and build Parmetis as well. This was done in the example above and thus the Parmetis libraries are located within the PETSc source tree in the directory corresponding to the architecture specified in \texttt{\textbf{PETSC\_ARCH}}. -The Global Arrays library can be built using a number of different runtimes. The default runtime uses MPI two-sided communication. While it is very easy to use, this runtime does not scale well beyond a dozen or so processors. Users interested on running on large numbers of cores should look at configuring Global Arrays with other runtimes. A high performing GA runtime that is available on most platforms is called progress ranks. This runtime has a peculiarity in that it reserves one MPI process per SMP node to manage communication. Thus, if you request a total of 20 MPI processes on 4 nodes with 5 processes running on each node only 4 MPI process per node will actually be available to the application for a total of 16. In order to notify GridPACK that you are using this runtime, you need to set the parameter \texttt{\textbf{USE\_PROGRESS\_RANKS}} to true. In the example above, we are not using progress ranks so we set \texttt{\textbf{USE\_PROGRESS\_RANKS}} to false. +The Global Arrays library can be built using a number of different runtimes. The default runtime uses MPI two-sided communication. While it is very easy to use, this runtime does not scale well beyond a dozen or so processors. Users interested on running on large numbers of cores should look at configuring Global Arrays with other runtimes. A high performing GA runtime that is available on all platforms is called progress ranks. While it is very robust, this runtime has a peculiarity in that it reserves one MPI process per SMP node to manage communication. Thus, if you request a total of 20 MPI processes on 4 nodes with 5 processes running on each node only 4 MPI process per node will actually be available to the application for a total of 16. In order to notify GridPACK that you are using this runtime, you need to set the parameter \texttt{\textbf{USE\_PROGRESS\_RANKS}} to true. In the example above, we are not using progress ranks so we set \texttt{\textbf{USE\_PROGRESS\_RANKS}} to false. The \texttt{\textbf{GA\_EXTRA\_LIBS}} parameter can be used to include extra libraries in the link step that are not picked up as part of the configuration process. For this example, this parameter is not needed. -The \texttt{\textbf{GA\_EXTRA\_LIBS}} parameter can be used to include extra libraries in the link step that are not picked up as part of the configuration process. In this example, GA is configured to run on an Infiniband network so it is necessary to explicitly include \texttt{\textbf{libibverbs}} and \texttt{\textbf{librt}}. For most of the MPI-based runtimes, this variable is not needed. The MPI wrappers for the C and C++ compilers can be specified by setting \texttt{\textbf{MPI\_C\_COMPILER}} and \texttt{\textbf{MPI\_CXX\_COMPILER}} and the MPI launch command can be specified using \texttt{\textbf{MPIEXEC}}. The \texttt{\textbf{CMAKE\_INSTALL\_PREFIX}} specifies the location of the installed build of GridPACK. This location should be used when linking external applications to GridPACK. The \texttt{\textbf{CMAKE\_BUILD\_TYPE}} can be used to control the level of debugging symbols in the library. \texttt{\textbf{MPIEXEC\_NUM\_PROCS}} should be set to a small number and controls the number of processors that will be used if running the parallel tests in the GridPACK test suite. Many of the application tests are small (9 or 14 buses) and will fail if you try and run on a large number of cores. Finally, \texttt{\textbf{CMAKE\_VERBOSE\_MAKEFILE}} controls the level of information generated during the compilation. It is mainly of interest for people doing development in GridPACK and most other users can safely set it to false. A new feature in the build is to use shared libraries instead of static builds. This may be of interest to users that are interested in wrapping GridPACK applications with python. A shared library version of GridPACK can be created by configuring GridPACK against versions of Boost, GA, and PETSc that are built as shared libraries. It appears that just configuring against shared libraries is enough to trigger a share library build in CMake, but users can add the line @@ -73,8 +71,8 @@ \chapter{Configuring and Building GridPACK} { \color{red} \begin{Verbatim}[fontseries=b] - mpirun -n 2 code.x + mpirun -n 2 code.x input.xml \end{Verbatim} } -In this case the code will run on 2 processors. Different platforms may use different scripts to run the parallel job. Consult your local system documentation for details. Applications may also have additional arguments that are processed inside the application itself. Most GridPACK applications will take an argument representing the input file for the application. +In this case the code will run on 2 processors. Different platforms may use different scripts to run the parallel job. Consult your local system documentation for details. Applications may also have additional arguments that are processed inside the application itself. Most GridPACK applications will take an argument representing the input file for the application. In this example, the input file is \texttt{\textbf{input.xml}}. diff --git a/docs/user_manual/tex/buildapps.tex b/docs/user_manual/tex/buildapps.tex index 1c6d80bff..68e63599e 100644 --- a/docs/user_manual/tex/buildapps.tex +++ b/docs/user_manual/tex/buildapps.tex @@ -7,7 +7,7 @@ \chapter{Building GridPACK Applications} { \color{red} \begin{Verbatim}[fontseries=b] - 1 cmake_minimum_required(VERSION 2.6.4) + 1 cmake_minimum_required(VERSION 3.5.0) 2 3 if (NOT GRIDPACK_DIR) 4 set(GRIDPACK_DIR /HOME/gridpack-install diff --git a/docs/user_manual/tex/framework.tex b/docs/user_manual/tex/framework.tex index 411bcac7d..970b4c2b3 100644 --- a/docs/user_manual/tex/framework.tex +++ b/docs/user_manual/tex/framework.tex @@ -23,7 +23,18 @@ \chapter{GridPACK Framework Components} %\textcolor{red}{\texttt{\textbf{Figure 1.}} Relationship between major GridPACK components.} -A full description of a power grid network requires specification of both the network topology and the physical properties of the bus and branch components. The combination of the models and the network generate algebraic equations that can be solved to get desired system properties. GridPACK supplies numerous modules to simplify the process of specifying the model and solving it. These include power grid components that describe the physics of the different network models or analyses, grid component factories that initialize the grid components, mappers that convert the current state of the grid components into matrices and vectors, solvers that supply the preconditioner and solver functionality necessary to implement solution algorithms, input and output modules that allow developers to import and export data, and other utility modules that support standard code develop operations like timing, event logging, and error handling. +A full description of a power grid network requires specification of both the +network topology and the physical properties of the bus and branch components. +The combination of the models and the network generate algebraic equations that +can be solved to get desired system properties. GridPACK supplies numerous +modules to simplify the process of specifying the model and solving it. These +include power grid components that describe the physics of the different network +models or analyses, grid component factories that initialize the grid +components, mappers that convert the current state of the grid components into +matrices and vectors, solvers that supply the preconditioner and solver +functionality necessary to implement solution algorithms, input and output +modules that allow developers to import and export data, and other utility +modules that support standard code development operations like timing, event logging, and error handling. Many of these modules are constructed using libraries developed elsewhere so as to minimize framework development time. However, by wrapping them in interfaces @@ -64,4 +75,12 @@ \section{Preliminaries} The GridPACK software uses a few coding conventions to h at the top of the application .hpp and/or .cpp files. This file contains definitions of all the GridPACK modules and their associated functions. -Matrices and vectors in GridPACK were originally complex but now either complex or real matrices can be created using the library. Inside the GridPACK implementation, the underlying distributed matrices are either complex or real, but the framework adds a layer that supports both types of objects, even if the underlying math library does not. However, computations on complex matrices will perform better if the underlying math library is configured to use complex matrices directly. This should be kept in mind when choosing the math library to build GridPACK on. The underlying PETSc library can be configured to support either real or complex matrices. Complex numbers are represented in GridPACK as having type \texttt{\textbf{ComplexType}}. The real and imaginary parts of a complex number \texttt{\textbf{x}} can be obtained using the functions \texttt{\textbf{real(x)}} and \texttt{\textbf{imag(x)}}. +Matrices and vectors in GridPACK were originally complex but now either complex +or real matrices can be created using the library. Inside the GridPACK +implementation, the underlying distributed matrices are either complex or real, +but the framework adds a layer that supports both types of objects, even if the +underlying math library does not. However, computations on complex matrices will +perform better if the underlying math library is configured to use complex +matrices directly. This should be kept in mind when choosing the math library to +build GridPACK on. The underlying PETSc library can be configured to support +either real or complex matrices, but not both at the same time. Complex numbers are represented in GridPACK as having type \texttt{\textbf{ComplexType}}. The real and imaginary parts of a complex number \texttt{\textbf{x}} can be obtained using the functions \texttt{\textbf{real(x)}} and \texttt{\textbf{imag(x)}}. diff --git a/docs/user_manual/tex/intro.tex b/docs/user_manual/tex/intro.tex index 6577a39f4..5c8e65cef 100644 --- a/docs/user_manual/tex/intro.tex +++ b/docs/user_manual/tex/intro.tex @@ -1,7 +1,6 @@ \chapter{Introduction} -The objective of the GridPACK$\mathrm{{}^{TM}}$ toolkit project is to provide a framework to support the rapid development of power grid applications capable of running on high performance computing architectures (HPC) with high levels of performance and scalability. The toolkit allows power system engineers to focus on developing working applications from their models without getting bogged down in the details of decomposing the computation across multiple processors, managing data transfers between processors, working out index transformations between power grid networks and the matrices generated by different power applications, and managing input and output. GridPACK is being designed to encapsulate as much of the book-keeping required to set up HPC applications as possible using high-level programming abstractions that allow developers to concentrate on the physics and mathematics of their problems. -This document summarizes the overall design of the GridPACK framework and provides a detailed description of its components. The remainder of this document will describe the functionality incorporated into the GridPACK framework to support multiple power grid applications. The framework will continue to evolve as more real-world experience can be incorporated into the design process but many base classes that have already been identified that are capable of supporting a range of applications. +The objective of the GridPACK$\mathrm{{}^{TM}}$ toolkit project is to provide a framework to support the rapid development of power grid applications capable of running on high performance computing architectures (HPC) with high levels of performance and scalability. The toolkit allows power system engineers to focus on developing working applications from their models without getting bogged down in the details of decomposing the computation across multiple processors, managing data transfers between processors, working out index transformations between power grid networks and the matrices generated by different power grid applications, and managing input and output. GridPACK is being designed to encapsulate as much of the book-keeping required to set up HPC applications as possible using high-level programming abstractions that allow developers to concentrate on the physics and mathematics of their problems. This document summarizes the overall design of the GridPACK framework and provides a detailed description of its components. The remainder of this document will describe the functionality incorporated into the GridPACK framework to support multiple power grid applications. The framework will continue to evolve as more real-world experience can be incorporated into the design process but many base classes that have already been identified that are capable of supporting a range of applications. During the initial stages of GridPACK development, four power grid applications were targeted for implementation. These included: \begin{enumerate} \item Powerflow simulations of the electric grid @@ -17,7 +16,7 @@ \chapter{Introduction} \begin{enumerate} \item Network topology and behavior. The network topology is the starting point for any power grid analysis. The topology defines the initial network model and is the connection point between the physical problem definition in terms of buses and branches and the solution method, which is usually expressed in terms of matrices and vectors. -\item Network components and their properties (e.g. bus and branch models, measurements, etc.). Grid components are the objects associated with the buses and branches of the power grid network. Along with the network topology itself, these define the physical system being modeled and in some cases the analysis that is to be performed. Bus and branch components can be differentiated into things like generators, loads, grounds, lines, transformers, measurements, etc. and depending on the how they are defined and the level of detail incorporated into them, they define different power grid systems and analyses. The behavior of buses and branches can depend on the properties of branches or buses that are directly attached to them, e.g. figuring out the contribution of a particular bus to the solution procedure may require that properties of the attached branches are made available to the bus. The necessity for exchanging this data is built into the framework. Furthermore, these data exchanges must also be accounted for in a parallel computing context, since the grid component from which data is required may be located on a different processor. +\item Network components and their properties (e.g. bus and branch models, measurements, etc.). Grid components are the objects associated with the buses and branches of the power grid network. Along with the network topology itself, these define the physical system being modeled and in some cases the analysis that is to be performed. Bus and branch components can be differentiated into things like generators, loads, grounds, lines, transformers, measurements, etc. and depending on the how they are defined and the level of detail incorporated into them, they define different power grid systems and analyses. The behavior of buses and branches can depend on the properties of branches or buses that are directly attached to them, e.g. figuring out the contribution of a particular bus to the solution procedure may require that properties of the attached branches are made available to the bus. The capability for exchanging this data is built into the framework. Furthermore, these data exchanges must also be accounted for in a parallel computing context, since the grid component from which data is required may be located on a different processor. \item Linear algebra and solvers. Basic algebraic objects, such as distributed matrices and vectors, are a core part of the solution algorithms required by power grid analyses. Most solution algorithms are dominated by sparse matrices but a few, such as Kalman filter analyses, require dense matrices. Vectors are typically dense. There exists a rich set of libraries for constructing distributed matrices and vectors and these are coupled to preconditioner and solver libraries. GridPACK can leverage this work heavily by creating wrappers to these libraries that can be used in solution algorithms. Wrapping these libraries instead of using them directly will have the advantage that creating algebraic objects can be simplified somewhat for power grid applications but more importantly, it will allow framework developers to investigate new solver and algebraic libraries seamlessly, without disrupting other parts of the code. diff --git a/docs/user_manual/tex/network.tex b/docs/user_manual/tex/network.tex index 94d5e5bc7..98d4ee615 100644 --- a/docs/user_manual/tex/network.tex +++ b/docs/user_manual/tex/network.tex @@ -24,14 +24,17 @@ \section{Network Module} A major use of the partitioner is to rearrange the network in a form that is useful for computation immediately after it is read in from an external file. Typically, the information in the external file is not organized in a way that is necessarily optimal for computation, so the partitioner must redistribute data such that each processor contains at most a few large connected subsets of the network. The partitioner is also responsible for adding the ghost buses and branches to the system. -Ghost buses and branches in a parallel program represent images of buses and branches that are owned by other processes. In order to carry out operations on buses and branches it is frequently necessary to gain access to data associated with attached buses and branches. The most efficient way to do this is to create copies of the buses and branches from other processors that are connected to locally owned objects. All local network components then have a complete set of attached neighbors. The ghost objects are updated collectively with current information from their home processors at points in the computation. Updating all ghosts at once is almost always more efficient than accessing data from one remote bus or branch at a time. +Ghost buses and branches in a parallel program represent images of buses and +branches that are owned by other processes. In order to carry out operations on +buses and branches it is frequently necessary to gain access to data associated +with attached buses and branches. If the attached bus or branch resides on the +same process, this is easily done but if they are located on another process, +then some other mechanism is needed. The most efficient way to access remote +data is to create copies of the buses and branches from other processors that are connected to locally owned objects. All local network components then have a complete set of attached neighbors. The ghost objects are updated collectively with current information from their home processors at points in the computation. Updating all ghosts at once is almost always more efficient than accessing data from one remote bus or branch at a time. The use of the partitioner to distribute the network between different processors and create ghost nodes and branches is illustrated in -Figure~\ref{fig:partition}. Figure~\ref{fig:partition}(a) shows a simple network -and Figure~\ref{fig:partition}(b) and Figure~\ref{fig:partition}(c) show the -result of distributing the network between two processors. -Figure~\ref{fig:partition}(a) shows a connected network that has been +Figure~\ref{fig:partition}. Figure~\ref{fig:partition}(a) shows a connected network that has been partitioned between two processors such that each processor owns roughly equally sized connected pieces. Figure~\ref{fig:partition}(b) and Figure~\ref{fig:partition}(c) show the pieces of the network on each processor @@ -48,17 +51,22 @@ \section{Network Module} \label{fig:partition} \end{figure} -%\noindent \includegraphics*[width=6.50in, height=3.55in, keepaspectratio=false, trim=0.00in 0.45in 0.00in 0.87in]{image69} - -%\noindent \includegraphics*[width=6.50in, height=3.54in, keepaspectratio=false, trim=0.00in 0.41in 0.00in 0.93in]{image70} - -%\noindent \includegraphics*[width=6.50in, height=3.24in, keepaspectratio=false, trim=0.00in 0.69in 0.00in 0.95in]{image71} - -%\textcolor{red}{\texttt{\textbf{Figure 4.}} (a) a simple network (b) partition of network on processor 0 (b) partition of network on processor 1. Open circles indicate ghost buses and dotted lines indicate ghost branches.} - -Networks can be created using the templated base class \texttt{\textbf{BaseNetwork$\boldsymbol{\mathrm{<}}$class Bus, class Branch$\boldsymbol{\mathrm{>}}$}}, where \texttt{\textbf{Bus}} and \texttt{\textbf{Branch}} are application-specific classes describing the properties of buses and branches in the network. The \texttt{\textbf{BaseNetwork}} class is defined within the \texttt{\textbf{gridpack::network}} namespace. In addition to the \texttt{\textbf{Bus}} and \texttt{\textbf{Branch}} classes, each bus and branch has an associated \texttt{\textbf{DataCollection}} object, which is described in more detail in the data interface section. The \texttt{\textbf{DataCollection}} object is a collection of key-value pairs that acts as an intermediary between data that is read in from external configuration files and the bus and branch classes that define the network. - -The \texttt{\textbf{BaseNetwork}} class contains a large number of methods, but only a relatively small number will be of interest to most application developers. Users that are interested in building networks from scratch instead of using one of the GridPACK parser modules can read the section on advanced network functionality that describes methods used primarily within other GridPACK modules to implement higher level capabilities. This section will focus on calls that are likely to be used by application developers. +Networks can be created using the templated base class +\texttt{\textbf{BaseNetwork$\boldsymbol{\mathrm{<}}$class Bus, class +Branch$\boldsymbol{\mathrm{>}}$}}, where \texttt{\textbf{Bus}} and +\texttt{\textbf{Branch}} are application-specific classes describing the +properties of buses and branches in the network. The +\texttt{\textbf{BaseNetwork}} class is defined within the +\texttt{\textbf{gridpack::network}} namespace. In addition to the +\texttt{\textbf{Bus}} and \texttt{\textbf{Branch}} classes, each bus and branch +has an associated \texttt{\textbf{DataCollection}} object, which is described in +more detail in the data interface section~\ref{data_interface}. The \texttt{\textbf{DataCollection}} object is a collection of key-value pairs that acts as an intermediary between data that is read in from external configuration files and the bus and branch classes that define the network. + +The \texttt{\textbf{BaseNetwork}} class contains a large number of methods, but +only a relatively small number will be of interest to most application +developers. Users that are interested in building networks from from an external +file that is not supported by one of the GridPACK parser modules can read the +section on advanced network functionality. This describes methods used primarily within other GridPACK modules to implement higher level capabilities. This section will focus on calls that are likely to be used by application developers. The constructor for the network class is the function @@ -81,6 +89,7 @@ \section{Network Module} } that is called when the network object passes out of scope or is explicitly deleted by the user. + Two functions are available that return the number of buses or branches that are available on a process. This number includes both buses and branches that are held locally as well as any ghosts that may be located on the process. { @@ -165,6 +174,7 @@ \section{Network Module} } These functions return a list of local indices that correspond to either the original bus index \texttt{\textbf{idx }}for a bus, or the pair of indices \texttt{\textbf{idx1}}, \texttt{\textbf{idx2}} for a branch. The reason that a list is returned instead of a single index is that in the case of ghost buses and branches, more than one copy of a network component may exist on a process. If no copies of a network component exist on a process then the returned vector has zero length. These functions can be used for applications such as contingency analysis, where modifications are made to a single network component and the modifications are specified in terms of the original bus indices. These functions can be used to find the local index of the component, if it exists. + The network partitioner can be accessed via the function { @@ -181,7 +191,9 @@ \section{Network Module} other processors. Before these functions can be called, the buffers in individual network components must be allocated. See the documentation on network components in section~\ref{network_components} and the network factory -in section~\ref{factory} for more information on how to do this. Once the buffers are in place, bus and branch exchanges can be set up and executed with just a few calls. The functions +in section~\ref{factory} for more information on how to do this. + +Once the buffers are in place, bus and branch exchanges can be set up and executed with just a few calls. The functions { \color{red} @@ -206,6 +218,7 @@ \section{Network Module} } These functions will cause data on ghost buses and branches to be updated with current values from active buses and branches located on other processors. + One additional network function that can be useful in certain circumstances is the capability for recovering the communicator on which the network is defined { diff --git a/docs/user_manual/tex/readthisdoc.tex b/docs/user_manual/tex/readthisdoc.tex index db6fa0243..8e159853f 100644 --- a/docs/user_manual/tex/readthisdoc.tex +++ b/docs/user_manual/tex/readthisdoc.tex @@ -1,4 +1,4 @@ \textbf{How to read this document} -Depending on how you are planning on using GridPACK$\mathrm{{}^{TM}}$, there are a variety of different ways of approaching the documentation. If you are only planning on using existing applications as is, without modification, then you should focus on the sections for configuring and building GridPACK and the application module documentation. Users that interested in developing their own applications may want to scan the section ``Developing Applications'' before going to the beginning of the document to learn about individual functionality in depth. The ``GridPACK Examples'' section contains additional examples of simple applications that can be used to get a sense of how to build an application from the ground up. The ``Contingency Analysis'' section provides some information on how to build applications that are based on the existing GridPACK application modules. Users that are interested in modifying the core functionality in GridPACK can look at the Doxygen documentation online under the ``GridPACK API Documentation'' link on www.gridpack.org, in addition to the documentation in this document. +Depending on how you are planning on using GridPACK$\mathrm{{}^{TM}}$, there are a variety of different ways of approaching the documentation. If you are only planning on using existing applications as is, without modification, then you should focus on the sections for configuring and building GridPACK and the application module documentation. Users that are interested in developing their own applications may want to scan the section ``Developing Applications'' before going to the beginning of the document to learn about individual functionality in depth. The ``GridPACK Examples'' section contains additional examples of simple applications that can be used to get a sense of how to build an application from the ground up. The ``Contingency Analysis'' section provides some information on how to build applications that are based on the existing GridPACK application modules. Users that are interested in modifying the core functionality in GridPACK can look at the Doxygen documentation online under the ``GridPACK API Documentation'' link on www.gridpack.org, in addition to the documentation presented below. \eject