**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*.

- The cell complex defining the topology of the space and optionally the function discretely sampled over it. The file may be a Healpix

**-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.

- Specifies the base name of the output file (extensions are added to this base name depending on the output type).

**-outDir <dir>**:

- Specifies the output directory.

Default value: the current working directory.

- Specifies the output 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*1*s and*0*s 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.

- 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

**-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.

- 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

**-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*.

- Specifies the number of threads.

**-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

- 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 <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.

- 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

**-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).

- This option allows the user to interactively select the persistence threshold on a persistence diagram (using pdview). if option

**-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).

- 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

**-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.

- Enables or prevents the computation of

**-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.

- 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

**-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.

- This is similar to option

**-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.

- 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

**-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).

- Dumps the persistence pairs as a

**-ppairs_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*.

- Dumps the "up" skeleton (i.e. arcs linking maxima to saddle-points, which trace the filamentary structures) as a

**-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*.

- Dumps the "down" skeleton (i.e. arcs linking minima to saddle-points, which trace the anti-filaments, or void filaments) as a

**-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''.

- Dumps the "inter" skeleton (i.e. arcs linking different types of saddle-points together) as a

**-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:

- 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).

- Dumps the specified type of arcs (i.e filaments) as a

**-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.

- Dumps ascending and/or descending manifolds (i.e. walls, voids, ...) as a

**-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.

- 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:

**-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).

- 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

**-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.

- By default,

**-no_saveMSC**:

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

- Use this if you do not want

**-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.

- Loads a given backup

**-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).

- Draws a diagram of the connectivity of critical points to a

**-smooth <Ntimes=0>**:

**-debug**:

- Outputs some debug information and files.