Scotch Brand 5.1.10 User Manual

Scotch brand (3m) calculator user manual

page of 136

/ 136
Contents
Table of Contents
Bookmarks

Table of Contents

Quick Links

Download this manual

Scotch and libScotch 5.1 User's Guide

Bacchus team, INRIA Bordeaux Sud-Ouest

ENSEIRB & LaBRI, UMR CNRS 5800

351 cours de la Lib´ e ration, 33405 TALENCE, FRANCE

This document describes the capabilities and operations of Scotch and

libScotch, a software package and a software library devoted to static

mapping, partitioning, and sparse matrix block ordering of graphs and

meshes/hypergraphs. It gives brief descriptions of the algorithms, details

the input/output formats, instructions for use, installation procedures, and

provides a number of examples.

Scotch is distributed as free/libre software, and has been designed such

that new partitioning or ordering methods can be added in a straightforward

manner. It can therefore be used as a testbed for the easy and quick coding

and testing of such new methods, and may also be redistributed, as a library,

along with third-party software that makes use of it, either in its original or

in updated forms.

(version 5.1.10)

Fran¸ c ois Pellegrini

Universit´ e Bordeaux I

pelegrin@labri.fr

August 29, 2010

Abstract

Table of Contents

Need help?

Do you have a question about the 5.1.10 and is the answer not in the manual?

Questions and answers

Summary of Contents for Scotch Brand 5.1.10

Page 1 It can therefore be used as a testbed for the easy and quick coding and testing of such new methods, and may also be redistributed, as a library, along with third-party software that makes use of it, either in its original or in updated forms. (version 5.1.10) Abstract...
Page 2: Table Of Contents
Contents 1 Introduction 1.1 Static mapping ......1.2 Sparse matrix ordering ......1.3 Contents of this document .
Page 3 6.3.5 gcv ....... . 6.3.6 gmap / gpart ......6.3.7 gmk * .
Page 4 7.5.3 SCOTCH graphFree ......7.5.4 SCOTCH graphLoad ......7.5.5 SCOTCH graphSave .
Page 5 7.10.2 SCOTCH stratExit ......108 7.10.3 SCOTCH stratSave ......109 7.10.4 SCOTCH stratGraphBipart .
Page 6: Introduction
Introduction Static mapping The eﬃcient execution of a parallel program on a parallel machine requires that the communicating processes of the program be assigned to the processors of the machine so as to minimize its overall running time. When processes have a lim- ited duration and their logical dependencies are accounted for, this optimization problem is referred to as scheduling.
Page 7: Contents Of This Document
Contents of this document This document describes the capabilities and operations of Scotch, a software package devoted to static mapping, graph and mesh partitioning, and sparse matrix block ordering. Scotch allows the user to map eﬃciently any kind of weighted process graph onto any kind of weighted architecture graph, and provides high- quality block orderings of sparse matrices.
Page 8: Algorithms
The free/libre software license under which Scotch 5.1 is distributed is the CeCILL-C license [6], which has basically the same features as the GNU LGPL (“Lesser General Public License”): ability to link the code as a library to any free/libre or even proprietary software, ability to modify the code and to redistribute these modiﬁcations.
Page 9: The Dual Recursive Bipartitioning Algorithm
This function, which has already been considered by several authors for hyper- cube target topologies [11, 21, 25], has several interesting properties: it is easy to compute, allows incremental updates performed by iterative algorithms, and its minimization favors the mapping of intensively intercommunicating processes onto nearby processors;...
Page 10 calls a graph bipartitioning algorithm to split the subset of processes associated with the domain across the two subdomains, as sketched in the following. mapping (D, P) Set_Of_Processors Set_Of_Processes Set_Of_Processors D0, D1; Set_Of_Processes P0, P1; if (|P| == 0) return; /* If nothing to do.
Page 11: Partial Cost Function
3.1.4 Partial cost function The production of eﬃcient complete mappings requires that all graph bipartition- ings favor the criteria that we have chosen. Therefore, the bipartitioning of a subgraph S of S should maintain load balance within the user-speciﬁed tolerance, and minimize the partial communication cost function f (τ...
Page 12: Graph Bipartitioning Methods
neighbor processes, whether they are handled by the job itself or not, since it can estimate in f the dilation of the corresponding edges. This results in an interesting feedback eﬀect: once an edge has been kept in a cut between two subdomains, the distance between its end vertices will be accounted for in the partial communication cost function to be minimized, and following jobs will be more likely to keep these vertices close to each other, as illustrated in Figure 2.
Page 13 space that derives from the one which was globally deﬁned at the coarsest level, thus preventing local optimization reﬁnement algorithms to be trapped in local optima of the ﬁner graphs [8]. Diﬀusion This global optimization method, presented in [42], ﬂows two kinds of antag- onistic liquids, scotch and anti-scotch, from two source vertices, and sets the new frontier as the limit between vertices which contain scotch and the ones which contain anti-scotch.
Page 14 tree rooted at a randomly chosen vertex, and this process is iterated by se- lecting a new root vertex within the last layer as long as the number of layers increases. Then, starting from the current root vertex, vertices are assigned layer after layer to the ﬁrst subdomain, until half of the total weight has been processed.
Page 15: Mapping Onto Variable-Sized Architectures
for it to account for topological structures of the graph that would else be of a too high level for it to encompass in its local optimization process. 3.1.7 Mapping onto variable-sized architectures Several constrained graph partitioning problems can be modeled as mapping the problem graph onto a target architecture, the number of vertices and topology of which depend dynamically on the structure of the subgraphs to bipartition at each step.
Page 16: Hybridization
vertex separators are computed by using direct heuristics [28, 37], or from edge separators [48, and included references] by minimum cover techniques [9, 30], but other techniques such as spectral vertex partitioning have also been used [49]. Provided that good vertex separators are found, the nested dissection algorithm produces orderings which, both in terms of ﬁll-in and operation count, compare favorably [19, 31, 46] to the ones obtained with the minimum degree algorithm [39].
Page 17: Ordering Methods
measure its quality, several parameters can be deﬁned: h the minimum, maximum, and average heights of the tree is the variance, expressed as a percentage of h small chains in the elimination tree, h of separators. 3.2.5 Ordering methods The core of our ordering algorithm uses graph ordering methods as black boxes, which allows the orderer to run any type of ordering method.
Page 18: Graph Separation Methods
3.2.6 Graph separation methods The core of our incomplete nested dissection algorithm uses graph separation methods as black boxes. It allows the orderer to run any type of graph separation method compatible with our criteria for quality, that is, reducing the size of the vertex separator while maintaining the loads of the separated parts within some user-speciﬁed tolerance.
Page 19: Changes From Version
Scotch can now handle compressed streams on the ﬂy, in several widely used formats such as gzip, bzip2 or lzma. Please refer to Section 6.2 for more informa- tion. Changes from version 5.0 A new integer index type has been created in the Fortran interface, to address array indices larger than the maximum value which can be stored in a regular integer.
Page 20: Mesh Files
The numeric ﬂag, similar to the one used by the Chaco graph format [24], is made of three decimal digits. A non-zero value in the units indicates that vertex weights are provided. A non-zero value in the tenths indicates that edge weights are provided.
Page 21: Geometry Files
The third line holds three ﬁgures: the base index of the ﬁrst element vertex in memory (velmbas), the base index of the ﬁrst node vertex in memory (vnodbas), and a numeric ﬂag. The Scotch mesh ﬁle format requires that all nodes and all elements be assigned to contiguous ranges of indices.
Page 22: Target Files
Figure 5: Mesh ﬁle representing three square elements, with unity vertex and edge weights. Elements are deﬁned before nodes, and numbering of the underlying graph starts from 1. The left part of the ﬁgure shows the mesh representation in memory, with consecutive element and node indices.
Page 23: Decomposition-Deﬁned Architecture Files
allowed to do so because, in our approach, the recursive bipartitioning of the target graph is fully independent with respect to that of the source graph (however, the opposite is false). For space and time saving issues, some classical homogeneous architectures (2D and 3D meshes and tori, hypercubes, complete graphs, etc.) have been algorithmi- cally coded within the mapper itself by the means of built-in functions.
Page 24: Algorithmically-Coded Architecture Files
5.4.2 Algorithmically-coded architecture ﬁles Almost all algorithmically-coded architectures are deﬁned with unity edge and ver- tex weights. They start with an abbreviation name of the architecture, followed by parameters speciﬁc to the architecture. The available built-in architecture deﬁni- tions are listed below. cmplt size Deﬁnes a complete graph with size vertices.
Page 25: Variable-Sized Architecture Files
mesh2D dimX dimY Deﬁnes a bidimensional array of dimX columns by dimY rows. The vertex with coordinates (posX, posY) has label posY × dimX + posX. mesh3D dimX dimY dimZ Deﬁnes a tridimensional array of dimX columns by dimY rows by dimZ lev- els.
Page 26: Ordering Files
of the target graph vertex onto which it is mapped. Mapping pairs can be stored in any order in the ﬁle; however, labels of source graph vertices must be all dif- ferent. For example, Figure 9 shows the result obtained when mapping the source graph of Figure 4 onto the target architecture of Figure 7.
Page 27: Programs
Figure 10: Ordering ﬁle obtained when reordering the hypercube graph of Figure 4. Vertex lists are coded as lists of integer numbers. The ﬁrst integer is the number of vertices in the list and the other integers are the labels of the selected vertices, given in any order.
Page 28 External mesh file mmk_* Geometry file .xyz Source gmk_msh mesh file .msh mtst mord Ordering file .ord gotst File Program Data flow Figure 12: General architecture of the Scotch project. All of the features oﬀered by the stand-alone programs are also available in the libScotch library. External graph file gmk_*...
Page 29: Using Compressed Files
A brief on-line help is provided with all the programs. To get this help, use the “-h” option after the program name. The case of option letters is not signiﬁcant, except when both the lower and upper cases of a letter have diﬀerent meanings. When passing parameters to the programs, only the order of ﬁle names is signiﬁcant;...
Page 30: Amk
However, compiled architecture ﬁles are read much more eﬃciently, as they are directly loaded into memory without further processing. Since the compilation time of a target architecture graph evolves as the square of its number of vertices, precompiling with acpl can save some time when many mappings are to be performed onto the same large target architecture.
Page 31 Program amk hy outputs the target architecture ﬁle of a hypercube graph of dimension dim. Vertices are labeled according to the decimal value of their binary representation. The decomposition-deﬁned target architectures computed by amk hy do not exactly give the same results as the built-in hypercube targets because distances are not computed in the same manner, although the two recursive bipartitionings are identical.
Page 32: Amk Grf
6.3.3 amk grf Synopsis amk grf [input graph ﬁle [output target ﬁle]] options Description The program amk grf turns a source graph ﬁle into a decomposition-deﬁned target ﬁle. It computes a recursive bipartitioning of the source graph, as well as the array of distances between all pairs of its vertices, both of which are combined to give a decomposition-deﬁned target architecture of same topology as the input source graph.
Page 33: Atst
6.3.4 atst Synopsis atst [input target ﬁle [output data ﬁle]] options Description The program atst is the architecture tester. It gives some statistics on decomposition-deﬁned target architectures, and in particular the minimum, maximum, and average communication costs (that is, weighted distance) be- tween all pairs of processors.
Page 34: Gmap / Gpart
Chaco v1.0/MeTiS format. The Matrix Market format. Scotch source graph format. Print the program version and copyright. Default option set is “-Ib0 -Os”. 6.3.6 gmap / gpart Synopsis gmap [input graph ﬁle [input target ﬁle [output mapping ﬁle [output log ﬁle]]]] options gpart number of parts [input graph ﬁle [output mapping ﬁle [output log ﬁle]]] options...
Page 35: Gmk
-brat Set the maximum load imbalance ratio to rat, which should be a value comprised between 0 and 1. This option can be used in conjunction with option -c, but is incompatible with option -m. -cﬂags Tune the default mapping strategy according to the given preference ﬂags.
Page 36: Gmk Msh
Description The gmk * programs make source graphs. Each of them is devoted to a speciﬁc topology, for which it builds target graphs of any dimension. The gmk * programs are mainly used in conjunction with amk grf. Most gmk * programs build source graphs describing parallel machines, which are used by amk grf to generate corresponding target sub-architectures, by means of its -l option.
Page 37: Gmtst
Display the program synopsis. Print the program version and copyright. 6.3.9 gmtst Synopsis gmtst [input graph ﬁle [input target ﬁle [input mapping ﬁle [output data ﬁle]]]] options Description The program gmtst is the graph mapping tester. It outputs some statistics on the given mapping, regarding load balance and inter-processor communi- cation.
Page 38 Description The gord program is the block sparse matrix graph orderer. It uses an or- dering strategy to compute block orderings of sparse matrices represented as source graphs, whose vertex weights indicate the number of DOFs per node (if this number is non homogeneous) and whose edges are unweighted, in order to minimize ﬁll-in and operation count.
Page 39: Gotst
When the geometry of the graph is available, this mapping ﬁle may be processed by program gout to display the vertex separators and super- variable amalgamations that have been computed. -ostrat Apply ordering strategy strat. The format of ordering strategies is deﬁned in section 7.3.4.
Page 40: Gout
6.3.12 gout Synopsis [input graph ﬁle gout visualization ﬁle]]]] options Description The gout program is the graph, matrix, and mapping viewer program. It takes on input a source graph, its geometry ﬁle, and optionally a mapping result ﬁle, and produces a ﬁle suitable for display. At the time being, gout can gener- ate plain and encapsulated PostScript ﬁles for the display of adjacency matrix patterns and the display of planar graphs (although tridimensional objects can be displayed by means of isometric projection, the display of tridimensional...
Page 41 a. A subgraph of M be mapped onto K(2). Mapping result dis- played on another subgraph of M (4, 4). Figure 14: PostScript diplay of a single mapping ﬁle with diﬀerent subgraphs of the same source graph. Vertices covered with disks of the same color are mapped onto the same processor.
Page 42 Figure 15: Snapshot of an Open Inventor display of a sphere partitioned into 7 almost equal pieces by mapping onto the complete graph with 7 vertices. Vertices of same color are mapped onto the same processor. Avoid displaying the mapping disks. Opposite of d. Color PostScript output, using 16 diﬀerent colors.
Page 43: Gtst
-V Print the program version and copyright. Default option set is “-Oi{v}”. 6.3.13 gtst Synopsis gtst [input graph ﬁle [output data ﬁle]] options Description The program gtst is the source graph tester. It checks the consistency of the input source graph structure (matching of arcs, number of vertices and edges, etc.), and gives some statistics regarding edge weights, vertex weights, and vertex degrees.
Page 44: Mmk
Scotch source mesh format. -oformat Specify the output graph format. The available output formats are listed below. Scotch source graph format. Print the program version and copyright. Default option set is “-Ib0 -Os”. 6.3.15 mmk * Synopsis mmk m2 dimX [dimY [output mesh ﬁle]] options mmk m3 dimX [dimY [dimZ [output mesh ﬁle]]] options Description The mmk * programs make source meshes.
Page 45 Since its main purpose is to provide orderings that exhibit high concurrency for parallel block factorization, it comprises a nested dissection method [17], but classical [39] and state-of-the-art [1, 47] minimum degree algorithms are implemented as well. Ordering methods are used to deﬁne ordering strategies by means of selection, grouping, and condition operators.
Page 46: Mtst
a root of the separator tree (there can be several roots, if the mesh is disconnected). Combined to the column block mapping data produced by option -m, the tree structure allows one to rebuild the separator tree. Print the program version and copyright. -vverb Set verbose mode to verb, which may contain several of the following switches.
Page 47: Calling The Routines Of Libscotch
• error handling routines, which allow the user either to provide his own error servicing routines, or to use the default routines provided in the libScotch distribution. A MeTiS compatibility library, called libscotchmetis.a, is also available. It allows users who were previously using MeTiS in their software to take advantage of the eﬃcieny of Scotch without having to modify their code.
Page 48: Compiling And Linking
exists a SCOTCHFTYPEACTION () Fortran counterpart, in which the separating underscore character is replaced by an “F”. In most cases, the Fortran routines have exactly the same parameters as the C functions, save for an added trailing INTEGER argument to store the return value yielded by the function when the return type of the C function is not void.
Page 49: Machine Word Size Issues
“-lscotch -lscotcherr -lm”. If you want to handle errors by yourself, you should not link with library ﬁle libscotcherr.a, but rather provide a SCOTCH errorPrint() routine. Please refer to section 7.12 for more information. 7.1.4 Machine word size issues Graph indices are represented in Scotch as integer values of type SCOTCH Num. By default, this type equates to the int C type, that is, an integer type of size equal to the one of the machine word.
Page 50: Architecture Format
and “Data”, allow callers to retrieve information from opaque structures. In all of the following, whenever arrays are deﬁned, passed, and accessed, it is assumed that the ﬁrst element of these arrays is always labeled as baseval, whether baseval is set to 0 (for C-style arrays) or 1 (for Fortran-style arrays). Scotch internally manages with base values and array pointers so as to process these arrays accordingly.
Page 51 baseval vertnbr edgenbr vlbltab velotab 4 1 4 4 4 4 4 vendtab verttab 4 10 13 16 19 22 25 edgetab 2 6 3 4 1 7 6 5 1 2 4 2 7 3 7 2 6 2 1 5 5 2 4 edlotab 1 1 1 Figure 16: Sample graph and its description by libScotch arrays using a compact...
Page 52: Mesh Format
Dynamic graphs can be handled elegantly by using the vendtab array. In order to dynamically manage graphs, one just has to allocate verttab, vendtab and edgetab arrays that are large enough to contain all of the expected new vertex and edge data.
Page 53 velmbas vnodbas velmnbr vnodnbr edgenbr vlbltab velotab vendtab verttab 13 14 16 18 20 21 22 23 edgetab Figure 18: Sample mesh and its description by libScotch arrays using a compact edge array. Numbers within vertices are vertex indices. Since the edge array is compact, verttab is of size vertnbr + 1 and vendtab points to verttab + 1.
Page 54: Geometry Format
velmbas vnodbas velmnbr vnodnbr edgenbr vlbltab velotab verttab 1 2 5 8 9 edgetab 11 11 12 13 11 12 14 13 13 14 12 14 vendtab 2 5 8 9 12 13 Figure 19: Sample mesh and its description by libScotch arrays, with nodes numbered ﬁrst and elements numbered last.
Page 55 velmbas vnodbas velmnbr vnodnbr edgenbr vlbltab velotab verttab 2 5 8 13 16 19 edgetab 11 12 vendtab 5 8 9 16 19 22 25 Figure 20: Re-meshing of the mesh of Figure 19. New node vertices have been added at the end of the vertex sub-array, new elements have been added at the beginning of the element sub-array, and vertex base values have been updated accordingly.
Page 56: Block Ordering Format
dimnnbr ≤ 2, and its “z” coordinate is located at geomtab[(i - vnodbas) * dimnnbr + baseval + 2] if dimnnbr = 3. 7.2.5 Block ordering format Block orderings associated with graphs and meshes are described by means of block and permutation arrays, made of SCOTCH Nums, as shown in Figure 21.
Page 57: Using Default Strategy Strings
8 7 1 permtab peritab cblknbr 1 2 4 rangtab 3 3 7 −1 treetab Figure 21: Arrays resulting from the ordering by complete nested dissection of a 4 by 3 grid based from 1. Leftmost grid is the original grid, and righmost grid is the reordered grid, with separators shown and column block indices written in bold.
Page 58: Mapping Strategy Strings
such as ﬂoating point exceptions, which could not be properly handled by the calling software. 7.3.2 Mapping strategy strings At the time being, mapping methods only apply to graphs, as there is not yet a mesh mapping tool in the Scotch package. Mapping strategies are made of methods, with optional parameters enclosed between curly braces, and separated by commas, in the form of method [{parameters}] .
Page 59: Graph Bipartitioning Strategy Strings
Untie job pools. Subjobs are stored in the next job pool to be pro- cessed. map=tie The tie ﬂag deﬁnes how results of bipartitioning jobs are propagated to jobs still in pools. Tie both mapping tables together. Results are immediately available to jobs in the same job pool.
Page 60 cond1 |cond2 Logical or operator. The result of the condition is true if cond1 or cond2 are true, or both. cond1 &cond2 Logical and operator. The result of the condition is true only if both cond1 and cond2 are true. !cond Logical not operator.
Page 61 application of the bnd bipartitioning method to the band graph leads to a situation where both anchor vertices are placed in the same part. width=val Set the width of the band graph. All graph vertices that are at a distance less than or equal to val from any frontier vertex are kept in the band graph.
Page 62 pass=nbr Set the maximum number of optimization passes performed by the algo- rithm. The Fiduccia-Mattheyses algorithm stops as soon as a pass has not yielded any improvement of the cost function, or when the maximum number of passes has been reached. Value ber of passes, that is, as many as needed by the algorithm to converge.
Page 63: Ordering Strategy Strings
7.3.4 Ordering strategy strings Ordering strategies are available both for graphs and for meshes. An ordering strategy is made of one or several ordering methods, which can be combined by means of strategy operators. The strategy operators that can be used in ordering strategies are listed below, by increasing precedence.
Page 64 of large diagonal blocks are likely to be ﬁlled at factoring time. However, in the context of incomplete solving methods such as ILU(k) [29], it can lead to a signiﬁcant reduction of the required memory space and time, because it helps carving large triangular blocks.
Page 65 frat=rat Fill-in ratio over which some column block will not amalgamate one of its descendents in the elimination tree. Typical values range from 0.05 to 0.10. Block Halo Approximate Minimum Fill method. The parameters of the Halo Approximate Minimum Fill method are listed below. cmin=size Minimum number of columns per column block.
Page 66: Node Separation Strategy Strings
ordering strategy is then applied to the derived graph, and this ordering is projected back to the nodes of the mesh. This method is here for evaluation purposes only, as mesh ordering methods are generally more eﬃcient than their graph ordering counterpart. strat=strat Graph ordering strategy to apply to the associated graph.
Page 67 levl The level of the subgraph in the separators tree, starting from zero at the root of the tree. Integer. proc The number of processors on which the current subgraph is dis- tributed at this level of the separators tree. This variable is available only when calling from routines of the PT-Scotch parallel library.
Page 68 bal=val Set the load imbalance tolerance to val, which is a ﬂoating-point ratio expressed with respect to the ideal load of the partitions. strat=strat Set the graph bipartitioning strategy that is used to compute the edge bi- partition. The syntax of bipartitioning strategy strings is deﬁned within section 7.3.3, at page 59.
Page 69 computed for coarser graphs or meshes. This strategy is not applied to the coarsest graph or mesh, for which only the low strategy is used. low=strat Set the strategy that is used to compute the vertex separator of the coarsest graph or mesh, at the lowest level of the coarsening process. rat=rat Set the threshold maximum coarsening ratio over which graphs or meshes are no longer coarsened.
Page 70: Target Architecture Handling Routines
Target architecture handling routines 7.4.1 SCOTCH archInit Synopsis int SCOTCH archInit (SCOTCH Arch * scotchfarchinit (doubleprecision (*) integer Description The SCOTCH archInit function initializes a SCOTCH Arch structure so as to make it suitable for future operations. It should be the ﬁrst function to be called upon a SCOTCH Arch structure.
Page 71: Scotch Archsave
The SCOTCH archLoad routine ﬁlls the SCOTCH Arch structure pointed to by archptr with the source graph description available from stream stream in the Scotch target architecture format (see Section 5.4). Fortran users must use the PXFFILENO or FNUM functions to obtain the num- ber of the Unix ﬁle descriptor fildes associated with the logical unit of the architecture ﬁle.
Page 72: Scotch Archsize
string pointers, the scotchfarchname routine takes as second and third pa- rameters a character() array to be ﬁlled with the name of the architecture, and the integer size of the array, respectively. If the array is of suﬃcient size, a trailing nul character is appended to the string to materialize the end of the string (this is the C style of handling character strings).
Page 73: Scotch Archcmplt
When listptr is not NULL and listnbr is greater than zero, the decomposition-deﬁned architecture is restricted to the listnbr vertices whose indices are given in the array pointed to by listtab, from listtab[0] to listtab[listnbr - 1]. These indices should have the same base value as the one of the graph pointed to by grafptr, that is, be in the range from 0 to 1 if the graph base is 0, and from 1 to vertnbr if the graph base vertnbr...
Page 74: Scotch Archhcub
Description The SCOTCH archCmpltw routine ﬁlls the SCOTCH Arch structure pointed to by archptr with the description of a weighted complete graph architecture with vertnbr processors. The relative weights of the processors are given in the velotab array. Once the target architecture has been created, it can be used as input to SCOTCH graphMap to perform weighted graph partitioning.
Page 75: Scotch Archmesh3D
Return values SCOTCH archMesh2D returns 0 if the 2D mesh target architecture has been successfully built, and 1 else. 7.4.12 SCOTCH archMesh3D Synopsis int SCOTCH archMesh3D (SCOTCH Arch * scotchfarchmesh3d (doubleprecision (*) integer*num integer*num integer*num integer Description The SCOTCH archMesh3D routine ﬁlls the SCOTCH Arch structure pointed to by archptr with the description of a 3D mesh architecture with xdimval ×...
Page 76: Scotch Archtorus2D
(i + 1) of each node at level i, and linktab[i] is the cost of communication between processors the ﬁrst common ancestor of which belongs to this level. See Section 5.4.2, page 24, for an example of such an architecture. Return values SCOTCH archTleaf returns 0 if the tree-leaf target architecture has been suc- cessfully built, and 1 else.
Page 77: Graph Handling Routines
Return values SCOTCH archTorus3D returns 0 if the 3D torus target architecture has been successfully built, and 1 else. Graph handling routines 7.5.1 SCOTCH graphInit Synopsis int SCOTCH graphInit (SCOTCH Graph * scotchfgraphinit (doubleprecision (*) integer Description The SCOTCH graphInit function initializes a SCOTCH Graph structure so as to make it suitable for future operations.
Page 78: Scotch Graphload
Description The SCOTCH graphFree function frees the graph data of a SCOTCH Graph struc- ture previously initialized by SCOTCH graphInit, but preserves its internal data structures. This call is equivalent to a call to SCOTCH graphExit im- mediately followed by a call to SCOTCH graphInit. Consequently, the given SCOTCH Graph structure remains ready for subsequent calls to any routine of the libScotch library.
Page 79: Scotch Graphsave
7.5.5 SCOTCH graphSave Synopsis int SCOTCH graphSave (const SCOTCH Graph * scotchfgraphsave (doubleprecision (*) integer integer Description The SCOTCH graphSave routine saves the contents of the SCOTCH Graph struc- ture pointed to by grafptr to stream stream, in the Scotch graph format (see section 5.1).
Page 80: Scotch Graphbase
Description The SCOTCH graphBuild routine ﬁlls the source graph structure pointed to by grafptr with all of the data that are passed to it. baseval is the graph base value for index arrays (typically 0 for structures built from C and 1 for structures built from Fortran). vertnbr is the number of vertices.
Page 81: Scotch Graphcheck
Description The SCOTCH graphBase routine sets the base of all graph indices according to the given base value, and returns the old base value. This routine is a helper for applications that do not handle base values properly. In Fortan, the old base value is returned in the third parameter of the function call.
Page 82: Scotch Graphdata
Any of these pointers can be set to NULL on input if the corresponding infor- mation is not needed. Else, the reference to a dummy area can be provided, where all unwanted data will be written. This routine is useful to get the size of a graph read by means of the SCOTCH graphLoad routine, in order to allocate auxiliary arrays of proper sizes.
Page 83: Scotch Graphstat
hold the number of arcs (that is, twice the number of edges). edgetab is the pointer to a location that will hold the reference to the adjacency array, of size at least *edgeptr. edlotab is the pointer to a location that will hold the reference to the arc load array, of size *edgeptr.
Page 84: Graph Mapping And Partitioning Routines
scotchfgraphstat (doubleprecision (*) integer*num integer*num integer*num doubleprecision doubleprecision integer*num integer*num doubleprecision doubleprecision integer*num integer*num integer*num doubleprecision doubleprecision Description The SCOTCH graphStat routine produces some statistics regarding the graph structure pointed to by grafptr. velomin, velomax, velosum, veloavg and velodlt are the minimum vertex load, the maximum vertex load, the sum of all vertex loads, the average vertex load, and the variance of the vertex loads, respectively.
Page 85: Scotch Graphmap
The SCOTCH graphPart routine computes a partition into partnbr parts of the source graph structure pointed to by grafptr, using the graph partitioning strategy pointed to by stratptr, and returns the partition data in the array pointed to by parttab. The parttab array should have been previously allocated, of a size suﬃcient to hold as many SCOTCH Num integers as there are vertices in the source graph.
Page 86: Scotch Graphmapinit
7.6.3 SCOTCH graphMapInit Synopsis int SCOTCH graphMapInit (const SCOTCH Graph * scotchfgraphmapinit (doubleprecision (*) Description The SCOTCH graphMapInit routine ﬁlls the mapping structure pointed to by mappptr with all of the data that is passed to it. Thus, all subsequent calls to ordering routines such as SCOTCH graphMapCompute, using this mapping structure as parameter, will place mapping results in ﬁeld parttab.
Page 87: Scotch Graphmapload
7.6.5 SCOTCH graphMapLoad Synopsis int SCOTCH graphMapLoad (const SCOTCH Graph * scotchfgraphmapload (doubleprecision (*) Description The SCOTCH graphMapLoad routine ﬁlls the SCOTCH Mapping structure pointed to by mappptr with the mapping data available in the Scotch mapping for- mat (see section 5.5) from stream stream. Fortran users must use the PXFFILENO or FNUM functions to obtain the num- ber of the Unix ﬁle descriptor fildes associated with the logical unit of the mapping ﬁle.
Page 88: Scotch Graphmapcompute
7.6.7 SCOTCH graphMapCompute Synopsis int SCOTCH graphMapCompute (const SCOTCH Graph * scotchfgraphmapcompute (doubleprecision (*) Description The SCOTCH graphMapCompute routine computes a mapping on the given SCOTCH Mapping structure pointed to by mappptr using the mapping strategy pointed to by stratptr. On return, every cell of the mapping array (see section 7.6.3) holds the number of the target vertex to which the corresponding source vertex is mapped.
Page 89: Graph Ordering Routines
Return values SCOTCH mapView returns 0 if the data has been successfully written to stream, and 1 else. Graph ordering routines The ﬁrst routine provides high-level functionality and frees the user from the burden of calling in sequence several of the low-level routines described afterward. 7.7.1 SCOTCH graphOrder Synopsis...
Page 90: Scotch Graphorderinit
1 if the graph base is 0, and from 1 to vertnbr if the graph base vertnbr is 1. The three other result ﬁelds, *cblkptr, rangtab and treetab, contain data related to the block structure. *cblkptr holds the number of column blocks of the produced ordering, and rangtab holds the starting indices of each of the permuted column blocks, in increasing order, so that column block i starts at index rangtab[i] and ends at index (rangtab[i+1] 1), inclusive, in the new...
Page 91: Scotch Graphorderexit
vertnbr + 1, and treetab is the array holding the structure of the separators tree, of size vertnbr. See the above manual page of SCOTCH graphOrder, as well as section 7.2.5, for an explanation of the semantics of all of these ﬁelds. The SCOTCH graphOrderInit routine should be the ﬁrst function to be called upon a SCOTCH Ordering structure for ordering graphs.
Page 92: Scotch Graphordersave
Return values SCOTCH graphOrderLoad returns 0 if the ordering structure has been success- fully loaded from stream, and 1 else. 7.7.5 SCOTCH graphOrderSave Synopsis int SCOTCH graphOrderSave (const SCOTCH Graph * scotchfgraphordersave (doubleprecision (*) Description The SCOTCH graphOrderSave routine saves the contents of the SCOTCH Ordering structure pointed to by ordeptr to stream stream, in the Scotch ordering format (see section 5.6).
Page 93: Scotch Graphordersavetree
resulting mapping ﬁle can be used by the gout program (see Section 6.3.12) to produce pictures showing the diﬀerent separators and blocks. Fortran users must use the PXFFILENO or FNUM functions to obtain the num- ber of the Unix ﬁle descriptor fildes associated with the logical unit of the mapping ﬁle.
Page 94: Scotch Graphordercompute
Description The SCOTCH graphOrderCheck routine checks the consistency of the given SCOTCH Ordering structure pointed to by ordeptr. Return values SCOTCH graphOrderCheck returns 0 if ordering data are consistent, and 1 else. 7.7.9 SCOTCH graphOrderCompute Synopsis int SCOTCH graphOrderCompute (const SCOTCH Graph * scotchfgraphordercompute (doubleprecision (*) Description The SCOTCH graphOrderCompute routine computes a block ordering of the...
Page 95: Mesh Handling Routines
Description The SCOTCH graphOrderComputeList routine computes a block ordering of a subgraph of the graph structure pointed to by grafptr, using the ordering strategy pointed to by stratptr, and stores its result in the ordering structure pointed to by ordeptr. The induced subgraph is described by means of a vertex list: listnbr holds the number of vertices to keep in the induced subgraph, the indices of which are given, in any order, in the listtab array.
Page 96: Scotch Meshexit
Return values SCOTCH meshInit returns 0 if the mesh structure has been successfully ini- tialized, and 1 else. 7.8.2 SCOTCH meshExit Synopsis void SCOTCH meshExit (SCOTCH Mesh * scotchfmeshexit (doubleprecision (*) Description The SCOTCH meshExit function frees the contents of a SCOTCH Mesh structure previously initialized by SCOTCH meshInit.
Page 97: Scotch Meshsave
7.8.4 SCOTCH meshSave Synopsis int SCOTCH meshSave (const SCOTCH Mesh * scotchfmeshsave (doubleprecision (*) integer integer Description The SCOTCH meshSave routine saves the contents of the SCOTCH Mesh structure pointed to by meshptr to stream stream, in the Scotch mesh format (see section 5.2).
Page 98 scotchfmeshbuild (doubleprecision (*) integer*num integer*num integer*num integer*num integer*num (*) integer*num (*) integer*num (*) integer*num (*) integer*num (*) integer*num integer*num (*) integer*num Description The SCOTCH meshBuild routine ﬁlls the source mesh structure pointed to by meshptr with all of the data that is passed to it. velmbas and vnodbas are the base values for the element and node ver- tices, respectively.
Page 99: Scotch Meshcheck
stage, to call the SCOTCH meshCheck routine on the newly created SCOTCH Mesh structure, prior to any other calls to libScotch routines. Return values SCOTCH meshBuild returns 0 if the mesh structure has been successfully set with all of the input data, and 1 else. 7.8.6 SCOTCH meshCheck Synopsis...
Page 100: Scotch Meshdata
This routine is useful to get the size of a mesh read by means of the SCOTCH meshLoad routine, in order to allocate auxiliary arrays of proper sizes. If the whole structure of the mesh is wanted, function SCOTCH meshData should be preferred.
Page 101: Scotch Meshstat
the reference to the adjacency end index array, and is equal to verttab + 1 if the adjacency array is compact. velotab and vnlotab are pointers to locations that will hold the reference to the element and node vertex load arrays, of sizes *velmptr and *vnodptr, respectively.
Page 102: Scotch Meshgraph
scotchfmeshstat (doubleprecision (*) integer*num integer*num integer*num doubleprecision doubleprecision integer*num integer*num doubleprecision doubleprecision integer*num integer*num doubleprecision doubleprecision Description The SCOTCH meshStat routine produces some statistics regarding the mesh structure pointed to by meshptr. vnlomin, vnlomax, vnlosum, vnloavg and vnlodlt are the minimum node vertex load, the maximum node vertex load, the sum of all node vertex loads, the average node vertex load, and the vari- ance of the node vertex loads, respectively.
Page 103: Mesh Ordering Routines
In order to save memory space as well as computation time, in the current implementation of SCOTCH meshGraph, some mesh arrays are shared with the graph structure. Therefore, one should make sure that the graph must no longer be used after the mesh structure is freed. The graph structure can be freed before or after the mesh structure, but must not be used after the mesh structure is freed.
Page 104: Scotch Meshorderinit
On return, permtab holds the direct permutation of the unknowns, that is, node vertex i of the original mesh has index permtab[i] in the reordered mesh, while peritab holds the inverse permutation, that is, node vertex i in the reordered mesh had index peritab[i] in the original mesh. All of these indices are numbered according to the base value of the source mesh: permutation indices are numbered from min(velmbas, vnodbas) to vnodnbr+ min(velmbas, vnodbas)
Page 105: Scotch Meshorderexit
The SCOTCH meshOrderInit routine ﬁlls the ordering structure pointed to by ordeptr with all of the data that are passed to it. Thus, all subsequent calls to ordering routines such as SCOTCH meshOrderCompute, using this ordering structure as parameter, will place ordering results in ﬁelds permtab, peritab, *cblkptr, rangtab or treetab, if they are not set to NULL.
Page 106: Scotch Meshordersavemap
Description The SCOTCH meshOrderSave routine saves the contents of the SCOTCH Ordering structure pointed to by ordeptr to stream stream, in the Scotch ordering format (see section 5.6). Return values SCOTCH meshOrderSave returns 0 if the ordering structure has been success- fully written to stream, and 1 else.
Page 107: Scotch Meshordercheck
Description The SCOTCH meshOrderSaveTree routine saves the tree hierarchy information associated with the SCOTCH Ordering structure pointed to by ordeptr to stream stream. The format of the tree output ﬁle resembles the one of a mapping or ordering ﬁle: it is made up of as many lines as there are node vertices in the ordering. Each of these lines holds two integer numbers.
Page 108: Strategy Handling Routines
Description The SCOTCH meshOrderCompute routine computes a block ordering of the mesh structure pointed to by grafptr, using the mapping strategy pointed to by stratptr, and stores its result in the ordering structure pointed to by ordeptr. On return, the ordering structure holds a block ordering of the given mesh (see section 7.9.2 for a description of the ordering ﬁelds).
Page 109: Scotch Stratsave
7.10.3 SCOTCH stratSave Synopsis int SCOTCH stratSave (const SCOTCH Strat * scotchfstratsave (doubleprecision (*) integer integer Description The SCOTCH stratSave routine saves the contents of the SCOTCH Strat struc- ture pointed to by straptr to stream stream, in the form of a text string. The methods and parameters of the strategy string depend on the type of the strategy, that is, whether it is a bipartitioning, mapping, or ordering strategy, and to which structure it applies, that is, graphs or meshes.
Page 110: Scotch Stratgraphmap
7.10.5 SCOTCH stratGraphMap Synopsis int SCOTCH stratGraphMap (SCOTCH Strat * scotchfstratgraphmap (doubleprecision (*) Description The SCOTCH stratGraphMap routine ﬁlls the strategy structure pointed to by straptr with the graph mapping strategy string pointed to by string. From this point, the strategy structure can only be used as a mapping strategy, to be used by function SCOTCH graphMap, for instance.
Page 111: Scotch Stratgraphorder
7.10.7 SCOTCH stratGraphOrder Synopsis int SCOTCH stratGraphOrder (SCOTCH Strat * scotchfstratgraphorder (doubleprecision (*) Description The SCOTCH stratGraphOrder routine ﬁlls the strategy structure pointed to by straptr with the graph ordering strategy string pointed to by string. From this point, the strategy structure can only be used as a graph ordering strategy, to be used by function SCOTCH graphOrder, for instance.
Page 112: Scotch Stratmeshorder
7.10.9 SCOTCH stratMeshOrder Synopsis int SCOTCH stratMeshOrder (SCOTCH Strat * scotchfstratmeshorder (doubleprecision (*) Description The SCOTCH stratMeshOrder routine ﬁlls the strategy structure pointed to by straptr with the mesh ordering strategy string pointed to by string. From this point, strategy strat can only be used as a mesh ordering strategy, to be used by function SCOTCH meshOrder, for instance.
Page 113: Geometry Handling Routines
7.11 Geometry handling routines Since the Scotch project is based on algorithms that rely on topology data only, geometry data do not play an important role in the libScotch library. They are only relevant to programs that display graphs, such as the gout program. However, since all routines that are used by the programs of the Scotch distributions have an interface in the libScotch library, there exist geometry handling routines in it, which manipulate SCOTCH Geom structures.
Page 114: Scotch Geomdata
The SCOTCH geomExit function frees the contents of a SCOTCH Geom structure previously initialized by SCOTCH geomInit. All subsequent calls to SCOTCH *Geom* routines other than SCOTCH geomInit, using this structure as param- eter, may yield unpredictable results. 7.11.3 SCOTCH geomData Synopsis void SCOTCH geomData (const SCOTCH Geom * scotchfgeomdata (doubleprecision (*)
Page 115: Scotch Graphgeomloadchac
7.11.4 SCOTCH graphGeomLoadChac Synopsis int SCOTCH graphGeomLoadChac (SCOTCH Graph * scotchfgraphgeomloadchac (doubleprecision (*) Description The SCOTCH graphGeomLoadChac routine ﬁlls the SCOTCH Graph structure pointed to by grafptr with the source graph description available from stream grafstream in the Chaco graph format [24]. Since this graph format does not handle geometry data, the geomptr and geomstream ﬁelds are not used, as well as the string ﬁeld.
Page 116: Scotch Graphgeomloadhabo
The SCOTCH graphGeomSaveChac routine saves the contents of the SCOTCH Graph structure pointed to by grafptr to stream grafstream, in the Chaco graph format [24]. Since this graph format does not handle geometry data, the geomptr and geomstream ﬁelds are not used, as well as the string ﬁeld. Fortran users must use the PXFFILENO or FNUM functions to obtain the number of the Unix ﬁle descriptor graffildes associated with the logical unit of the graph ﬁle.
Page 117: Scotch Graphgeomsavescot
int SCOTCH graphGeomLoadScot (SCOTCH Graph * scotchfgraphgeomloadscot (doubleprecision (*) Description The SCOTCH graphGeomLoadScot routine ﬁlls the SCOTCH Graph and SCOTCH Geom structures pointed to by grafptr and geomptr with the source graph description and geometry data available from streams grafstream and geom stream in the Scotch graph and geometry formats (see sections 5.1 and 5.3, respectively).
Page 118: Scotch Meshgeomloadhabo
Fortran users must use the PXFFILENO or FNUM functions to obtain the numbers of the Unix ﬁle descriptors graffildes and geomfildes associated with the logical units of the graph and geometry ﬁles. Return values SCOTCH graphGeomSaveScot returns 0 if the graph topology and geometry have been successfully written to grafstream and geomstream, and 1 else.
Page 119: Scotch Meshgeomsavescot
scotchfmeshgeomloadscot (doubleprecision (*) Description The SCOTCH meshGeomLoadScot routine ﬁlls the SCOTCH Mesh and SCOTCH Geom structures pointed to by meshptr and geomptr with the source mesh description and node geometry data available from streams meshstream and geomstream in the Scotch mesh and geometry formats (see sections 5.2 and 5.3, respectively).
Page 120: Error Handling Routines
7.12 Error handling routines The handling of errors that occur within library routines is often diﬃcult, because library routines should be able to issue error messages that help the application programmer to ﬁnd the error, while being compatible with the way the application handles its own errors.
Page 121: Miscellaneous Routines
The SCOTCH errorProg function is designed to be called at the beginning of a program or of a portion of code to identify the place where subsequent errors take place. This routine is not reentrant, as it is only a minor help function. It is deﬁned in libscotcherr.a and is used by the standalone programs of the Scotch distribution.
Page 122: Metis Nodend
metis edgend (integer integer (*) integer (*) integer integer (*) integer (*) integer (*) Description The METIS EdgeND function performs a nested dissection ordering of the graph passed as arrays xadj and adjncy, using the default Scotch ordering strat- egy. The options array is not used. The perm and iperm arrays have the opposite meaning as in Scotch: the MeTiS perm array holds what is called “inverse permutation”...
Page 123: Metis Nodewnd
While Scotch has also both node and edge separation capabilities, all of the three MeTiS stubs METIS EdgeND, METIS NodeND and METIS NodeWND call the same Scotch routine, which uses the Scotch default ordering strategy proved to be eﬃcient in most cases. 7.14.3 METIS NodeWND Synopsis...
Page 124: Metis Partgraphrecursive
void METIS PartGraphKway (const int * const metis partgraphkway (integer Description The METIS PartGraphKway function performs a mapping onto the complete graph of the graph represented by arrays xadj, adjncy, vwgt and adjwgt, using the default Scotch mapping strategy. The options array is not used. The part array has the same meaning as the parttab array of Scotch.
Page 125: Metis Partgraphvkway
metis partgraphrecursive (integer Description The METIS PartGraphRecursive function performs a mapping onto the com- plete graph of the graph represented by arrays xadj, adjncy, vwgt and adjwgt, using the default Scotch mapping strategy. The options array is not used. The part array has the same meaning as the parttab array of Scotch.
Page 126: Installation
Scotch mailing list, and be automatically informed of new releases and publications. The extraction process will create a scotch 5.1.10 directory, containing several subdirectories and ﬁles. Please refer to the ﬁles called LICENSE EN.txt or LICENCE FR.txt, as well as ﬁle INSTALL EN.txt, to see under which conditions your distri-...
Page 127: Machine Word Size Issues
COMMON FILE COMPRESS LZMA for lzma decompression. Note that the correspond- ing development libraries must be installed on your system before compile time, and that compressed ﬁle handling can take place only on systems which support multi-threading or multi-processing. In the ﬁrst case, you must set the SCOTCH PTHREAD ﬂag in order to take advantage of these features.
Page 128 This can also be done in a single piped command: % echo cmplt 7 | gmap brol.grf - /tmp/brol.map If compressed data handling is enabled, read the graph as a gzip compressed ﬁle, and output the mapping as a bzip2 ﬁle, on the ﬂy: % echo cmplt 7 | gmap brol.grf.gz - /tmp/brol.map.bz2 •...
Page 129: Adding New Features To Scotch
To speed up target architecture loading in the future, the decomposition- deﬁned target architecture is compiled by means of acpl. • Build an architecture graph which is the subgraph of the 8-node de Bruijn graph restricted to vertices labeled 1, 2, 4, 5, 6, map graph graph.grf onto it, and save the result to ﬁle /tmp/brol.map.
Page 130: Methods And Partition Data
simple mesh, in the form of a bipartite graph, the deﬁnition of which is given in ﬁle mesh.h, respectively. From this structure are derived enriched graph and mesh structures: • Bgraph, in ﬁle bgraph.h: graph with bipartition, that is, edge separation, information attached to it;...
Page 131 1. Write the code of the method itself. First, choose a free two-letter code to describe your method, say “xy”. In the libscotch source directory, create ﬁles vgraph separate xy.c and vgraph separate xy.h, basing on existing ﬁles such as vgraph separate gg.c and vgraph separate gg.h, for instance. If the method is complex, it can be split across several other ﬁles, which will be named vgraph separate xy firstmodulename.c, vgraph separate xy secondmodulename.c, eventually with matching header ﬁles.
Page 132: Licensing Of New Methods And Of Derived Works
• STRATPARAMSTRAT: strategy. For instance, the graph ordering method by nested dissection takes a vertex partitioning strategy as one of its parameters, to compute the vertex separators. The fourth and ﬁfth ﬁelds are the address of the location of the default struc- ture and the address of the parameter within this default structure, respec- tively.
Page 133 • Alex Pothen kindly gave me a version of his Multiple Minimum Degree algo- rithm, which was embedded into Scotch from version 3.2 to version 3.4; • Luca Scarano, visiting Erasmus student from the Universit´ a degli Studi di Bologna, coded the multi-level graph algorithm in Scotch 3.1; •...
Page 134 [13] M. R. Garey and D. S. Johnson. Computers and Intractablility: A Guide to the Theory of NP-completeness. W. H. Freeman, San Francisco, 1979. [14] G. A. Geist and E. G.-Y. Ng. Task scheduling for parallel sparse Cholesky factorization. International Journal of Parallel Programming, 18(4):291–314, 1989.
Page 135 [29] P. H´ e non, F. Pellegrini, P. Ramet, J. Roman, and Y. Saad. High performance complete and incomplete factorizations for very large sparse systems by using scotch and pastix softwares. In Proc. 11 Processing for Scientiﬁc Computing, San Francisco, USA, February 2004. [30] J.
Page 136 [44] F. Pellegrini and J. Roman. Experimental analysis of the dual recursive bipar- titioning algorithm for static mapping. Research Report, LaBRI, Universit´ e Bordeaux I, August 1996. Available from http://www.labri.fr/ ~ pelegrin/ papers/scotch_expanalysis.ps.gz. [45] F. Pellegrini and J. Roman. Scotch: A software package for static mapping by dual recursive bipartitioning of process and architecture graphs.

Scotch Brand 5.1.10 User Manual

1 Introduction

2 The Scotch Project

3 Algorithms

4 Updates

5 Files and Data Structures

6 Programs

7 Library

8 Installation

9 Examples

10 Adding New Features to Scotch

Quick Links

Need help?

Questions and answers

Summary of Contents for Scotch Brand 5.1.10

Table of Contents