Manual

mse is the main program in DisPerSE, it is used to compute Morse-smale complexes and extract filamentary structures (i.e. arcs), voids and walls (ascending/descending manifolds), critical points and persistence pairs. By default, when no option is specified, the Morse-smale complex is computed and stored as a filename.MSC backup file in a format internal to mse, and no other file is produced. This file may later be loaded by mse (option -loadMSC) to skip the computation of the Morse-smale complex (this is useful when you want to produce different outputs from the same source).

Usage:

 mse <network filename> [-field <fname>]
     [-outName <fname>] [-noTags] [-outDir <dir>] 
     [-periodicity <val>]
     [-mask <fname>[~]]
     [-nthreads <N=$OMP_NUM_THREADS>]
 
     [-nsig <n1, n2, ...>] [-cut <l1, l2, ...>]
     [-interactive [<full/path/to/pdview>]]
     [-forceLoops]
     [-robustness] [-no_robustness]
 
     [-manifolds] [-interArcsGeom] [-no_arcsGeom]
 
     [-ppairs] [-ppairs_ASCII] 
     [-upSkl] [-downSkl] [-interSkl]
     [-dumpArcs <CUID>]
     [-dumpManifolds [<JEP0123456789ad>]] 
 
     [-compactify <type=natural>]
     [-vertexAsMinima] [-descendingFiltration] 
     [-no_saveMSC] [-loadMSC <fname>]
 
     [-no_gFilter]
     [-diagram] [-smooth <Ntimes=0>] 
     [-debug]

• <network filename>:
  
  • The cell complex defining the topology of the space and optionally the function discretely sampled over it. The file may be a Healpix FITS file, a regular grid or an unstructured network readable by netconv or fieldconv (run netconv or fieldconv without argument for a list of supported file formats). The value of the function from which the Morse-smale complex will be computed should be given for each vertex (or pixel in case of a regular grid). In the case of an unstructured network, the function should be given in a field labeled field_value, or the function may also be set using option -field.

• -field <fname>:
  
  • Specifies the scalar function whose morse complex will be computed. The function value should be given for each vertex (or pixel for regular grids), so the file must be a 1D array of values of size the number of vertices (or pixels) in the network, in a readable grid format.

• -outName <fname>:
  
  • Specifies the base name of the output file (extensions are added to this base name depending on the output type).
    Default value: the name of the input network file.

• -outDir <dir>:
  
  • Specifies the output directory.
    Default value: the current working directory.

• -noTags:
  
  • Prevents mse from adding trailing extensions to the output filename such as the persistence cut levels ... Note that the last extension correponding to the file format is still added.

• -periodicity <val>:
  
  • Specifies the periodicity of the domain. This is only applicable to grid types networks, which are considered by default to have periodic boundaries. The parameter <val> is a serie of 1s and 0s enabling/disabling periodic boundary conditions along the corresponding direction.
    Exemple: -periodicity 0 sets non periodic boundaries conditions (PBC) while -periodicity 101 sets PBC along dims 0 and 2 (x and z) but not along y axis.
    Default value: by default, boundary conditions are fully periodic.

• -mask <fname> [~]:
  
  • Specifies a mask. The file must be a 1D array of values of size the number of vertices (or pixels) in the network, in a readable grid format. By default, a value of 0 corresponds to a visible vertex/pixel while any other value masks the vertex/pixel. Adding a trailing ~ to the filename (without space) reverses this behavior, a value of 0 masking the corresponding pixels/vertices.

• -nthreads <N=$OMP_NUM_THREADS>:
  
  • Specifies the number of threads.
    Default value: the number of threads is set by the environment variable $OMP_NUM_THREADS which is usually set to the total number of cores available by openMP.

• -nsig <n1, n2, ...>:
  
  • Specifies the persistence ratio threshold in terms of "number of sigmas". Any persistence pair with a persistence ratio (i.e. the ratio of the values of the points in the pair) that has a probability less than "n-sigmas" to appear in a random field will be cancelled. This may only be used for discretely sampled density fields (such as N-body simulations or discrete objects catalogs) whose density was estimated through the DTFE of a delaunay tesselation. This option is typically used when the input network was produced using delaunay_2D or delaunay_3D, in any other case, use -cut instead. See also option -interactive

• -cut <l1, l2, ...>:
  
  • Specifies the persistence threshold. Any persistence pair with persistence (i.e. the difference of value between the two points in the pair) lower than the given threshold will be cancelled. Use -nsig instead of this when the input network was produced with delaunay_2D or delaunay_3D. The cut value should be typically set to the estimated amplitude of the noise. See also option -interactive.

• -interactive [<full/path/to/pdview>]:
  
  • This option allows the user to interactively select the persistence threshold on a persistence diagram (using pdview). if option -cut or -nsig is also used, the specified values are become default thresholds in pdview. The path to pdview may be optionally indicated in case it cannot be found automatically.
    Note: this option may only be used if pdview was compiled (requires mathGL and Qt4 libraries).

• -forceLoops:
  
  • Forces the simplification of non-cancellable persistence pairs (saddle-saddle pairs in 3D or more that are linked by at least 2 different arcs). When two critical points of critical index difference 1 are linked by 2 or more arcs, they may not be cancelled as this would result in a discrete gradient loop. This is not a problem in 2D as such pairs cannot form persistence pairs but in 3D, saddle-saddle persistence pairs may be linked by 2 or more arcs even though their persistence is low. By default those pairs are skipped in order to preserve the properties of the Morse-smale complex but as a result few non persistent features may remain (such as spurious filaments). Fortunately, there are usually none or only very few of those pairs, and their number is shown in the output of mse, in the Simplifying complex section. If you are only interested in identifying structures (as opposed to doing topology), you should probably use '-forceLoops' to remove those spurious structures (such as small non significant filaments).

• -robustness / -no_robustness:
  
  • Enables or prevents the computation of robustness and robustness ratio. By default, robustness is not computed as it can be costly for very large data sets. When enabled, a robustness value is tagged for each segments and node of the output skeleton files. See also options -trimBelow of skelconv and the tutorial section for applications.

• -manifolds:
  
  • Forces the computation and storage of all ascending and descending manifolds (i.e. walls, voids, ...). By default, mse only stores manifolds geometry if required (for instance, when the option -dumpManifolds is used), and the resulting backup MSC file will therefore not contain this information and may not be used later to compute manifolds.
    Example: running the command 'mse filename' will produce a the backup file 'filename.MSC' that stores the Morse-smale complex information. A later call to mse -loadMSC filename.MSC -upSkl would skip the computation of the MS-complex and succeed in producing the skeleton of the filamentary structures (arcs) as arcs geometry is computed by default. Unfortunately, mse -loadMSC filename.MSC -dumpManifolds J0a would fail as the information needed to compute the ascending 3-manifolds (i.e. manifolds originating from a minimum, which trace the voids) is not avaialble by default. Running mse filename -manifolds in the beginning would solve this problem.

• -interArcsGeom:
  
  • This is similar to option -manifolds, but for the arcs linking different types of saddle-points together (in 3D or more). By default, unless option -interSkl is specified, only the geometry of arcs linking extrema to saddle points is computed, so the backup .MSC file may not be used later to retrieve other types of arcs geometry. Specifying -interArcsGeom forces the computation and storage of all types of arcs in the .MSC backup file.

• -no_arcsGeom:
  
  • By default, the geometry of arcs linking extrema and saddle point is always computed even when not directly needed, so that it is stored in the backup .MSC file for later use. Specifying -no_arcsGeom may be used to lower memory usage when only the critical points and/or their persistence pairings are needed.
    Exemple: mse filename -ppairs -no_arcsGeom will compute the critical points and persistence pairs using less memory than mse filename -ppairs, but the resulting .MSC file may not be later used to retrieve arcs geometry.

• -ppairs:
  
  • Dumps the persistence pairs as a NDnet network type file. The resulting file is a 1D network, where the critical points are the vertices and 1-cells (segments) represent pairs. Additional information such as the type, persistence, cell in the initial complex, ... of each critical points and pairs is also stored as additional information. Try running netconv filename.ppairs.NDnet -info for a list of available additional data (see also additional data in the network file format section).

• -ppairs_ASCII:
  
  • Same as -ppairs but pairs are dumped in a easily readable ASCII format. This option is deprecated and should not be used, use -ppairs option instead and then run netconv filename.ppairs.NDnet -to NDnet_ascii.

• -upSkl:
  
  • Dumps the "up" skeleton (i.e. arcs linking maxima to saddle-points, which trace the filamentary structures) as a NDskl type skeleton file. This command is an alias of -dumpArcs U.

• -downSkl:
  
  • Dumps the "down" skeleton (i.e. arcs linking minima to saddle-points, which trace the anti-filaments, or void filaments) as a NDskl type skeleton file. This command is an alias of -dumpArcs D.

• -interSkl:
  
  • Dumps the "inter" skeleton (i.e. arcs linking different types of saddle-points together) as a NDskl type skeleton file. This will only work in 3D or more, and be careful that those type of arcs may have a very complex structure. This command is an alias of '-dumpArcs I''.

• -dumpArcs <CUID>:
  
  • Dumps the specified type of arcs (i.e filaments) as a NDskl type skeleton file. Any combination of the letter C, U, I and D may be used as parameter to indicate which type of arc should be saved:
    
    • -U(p): arcs leading to maxima (see also -upSkl).
    • -D(own): arcs leading to minima (see also -downSkl).
    • -I(nter): other arcs linking saddle-points together (see also -interSkl).
    • -C(onnect): keeps at least the connectivity information for all types of arcs.
      
  • Exemple: CUD dumps geometry of arcs for which one extremity is and extremum (a maximum or a minimum), and the connectivity of saddle points is also stored (i.e. one can retrieve how they are linked in the Morse-Smale complex but not the actual geometry of the corresponding arcs).

• -dumpManifolds [<JEP0123456789ad>]:
  
  • Dumps ascending and/or descending manifolds (i.e. walls, voids, ...) as a NDnet type network file. The first part of the argument must be a combination of letters J, E and P and the second, which indicates the type of manifold to dump as a digit indicating the critical index of the critical point it originates from followed by the letter a and/or d to select ascending and/or descending manifolds respectively:
    • - J(oin): join all the the manifolds in one single file. By default, one file is created for each manifold.
    • - E(xtended): compute extended manifolds. For instance, when computing an ascending 2-manifold (i.e. a wallseparating two voids), the ascending 1-manifolds (i.e. filaments) on its boundary as well as the ascending 0-manifolds (i.e. critical points) on their boundaries are also dumped.
    • - P(reserve): do not merge infinitely close submanifolds. By default, the overlapping part of manifolds are merged (e.g. filaments may have bifurcation points but arcs only stop at critical points, so although two arcs continue above the bifurcation, only one path is stored). Using this option preserve the properties of the MS-complex but may result in very large files.
    • - D(ual): compute dual cells geometry when appropriate. Descending and ascending manifolds are the dual of one another, so they should be represented by cells of the complex and their dual respectively. When this option is used, appropriate cells are replaced by their dual (for instance, ascending 0-manifolds of a delaunay tesselation are represented by sets of voronoi 3-cells, the dual of the 0-cells (vertices) of the delaunay tesselation). The default behavior is that descending manifolds belong to the dual, so ascending manifolds are always fine but one may want to use option D to compute dual cells or option -vertexAsMinima to change this behavior in order to obtain correct descending manifolds.
    • - 0123456789: specifies the critical index of the critical points from which the manifold originates (ascending 0,1,2 and 3-manifolds in 3D trace the voids, walls, filaments and maxima/sources respectively).
    • - a/d: compute the ascending and/or descending manifold.
  • Exemple 1: in 3D, argument JD0a2ad3d would dump to a single file the ascending manifolds of critical index 0 and 2, and the descending ones for critical index 2 and 3. Cells are replaced by their dual where appropriate (i.e. in 3D, the descending 2-manifolds would be 2-cells dual of segments, and descending 3 manifolds would be 3-cells dual to vertices).
  • Exemple 2: in 3D, argument JE0a would dump the union of the tetrahedrons within the voids, the walls separating the voids, as well as the filaments on their boundaries and the maxima at their extremity, as sets of triangles, segments and vertices of the input complex respectively, to a single file. As option P was not used, any overlapping region would be stored only once.

• -compactify <type=natural>:
  
  • This option is used to specify how to treat boundaries of manifolds with boundary (this option does not affect manifolds without boundary). Available type are:
    • - 'natural' is the default value, and almost always the best choice.
    • - 'torus' creates reflective (i.e periodic) boundaries.
    • - 'sphere' links boundaries to a cell at infinity.

• -vertexAsMinima:
  
  • As mse uses discrete Morse theory, each type of critical point corresponds to a particular cell type. By defaults, 0-cells (vertices) are maxima, 1-cells are saddle points, .... and d-cells are minima (d is the number of dimensions). Using -vertexAsMinima, the association is reversed and 0-cells are associated to minima ... while d-cells are associated to maxima. This option can be useful to identify manifolds or arcs as lists of a particular type of cell.
    Example: mse input_filename -dumpManifolds J0a -vertexAsMinima can be used to identify voids (ascending 0-manifolds) as sets of 0-cells (vertices). As a result, voids are identified as sets of pixels or particles (if input_filename is a grid or the delaunay tesselation of an N-body simulation respectiveley), which is easy to relate to the pixels/particles of the input file. If the command mse input_filename -dumpManifolds J0a had been issued instead, each void would have been described by a set of n-cells (in nD).

• -descendingFiltration:
  
  • By default, mse uses an ascending filtration to compute the discrete gradient. This option forces the program to use a descending filtration instead. Not that if mse works correctly (and it should hopefully be the case) the general properties of the Morse-smale complex are not affected, but simply critical points and manifolds geometry will slightly differ.

• -no_saveMSC:
  
  • Use this if you do not want mse to write a backup .MSC file.

• -loadMSC <fname>:
  
  • Loads a given backup .MSC file. This will basically skip the computation of the Morse-smale complex, therefore gaining a lot of time. By default, mse always write a backup .MSC after the MS-complex is computed. See options -manifolds and -interArcsGeom for information on the limitations.

• -no_gFilter:
  
  • Prevents the filtration of null-persistence pairs in the discrete gradient. There is no point in using this option except for debugging ...

• -diagram:
  
  • Draws a diagram of the connectivity of critical points to a .ps file. This should only be used when the number of critical points is very small (i.e. less than 100 or so).

• -smooth <Ntimes=0>:
  
  • Deprecated, don't use it ... use skelconv -smooth <Ntimes=0> or netconv -smooth <Ntimes=0> on the output files instead.

• -debug:
  
  • Outputs some debug information and files.