NAME

#

phtrees - Query optimal/stable volumes from a PH tree file

SYNOPSIS

#

homcloud-phtrees
    [-h] [-V] [-x X] [-y Y] [-X X_RANGE] [-Y Y_RANGE]
    [-j JSON_OUTPUT] [-S STABLE_VOLUME]
    input

This program can also be invoked as python3 -m homcloud.cli.phtrees.

ALIAS

#

homcloud-phtrees

DESCRIPTION

#

This program queries a PH-tree .pdgm file (produced by homcloud-pc-alpha --save-phtrees on) for the optimal volume (or a stabilized/tightened variant of it) of one or more birth-death pairs, without solving any LP problem — the volumes are read directly out of the pre-built tree structure.

The queried degree is always (dim - 1), where dim is the dimension recorded in the input file; there is no -d/--degree option.

You can specify a single point by using the -x and -y options. The program chooses the closest birth-death pair to that point.

You can also specify a rectangle region on the persistence diagram using the -X and -Y options. The program returns every birth-death pair in the given rectangle.

If -S/--stable-volume is given, instead of the raw optimal volume the program returns the stable volume: the sub-volume obtained by discarding children whose birth time is not more than STABLE_VOLUME (epsilon) later than the queried pair’s birth time.

OPTIONS

#

-h, --help            show this help message and exit
-V, --version         show program's version number and exit
-x X                  birth time of the pair
-y Y                  death time of the pair
-X X_RANGE, --x-range X_RANGE
                      birth time of the pair
-Y Y_RANGE, --y-range Y_RANGE
                      death time of the pair
-j JSON_OUTPUT, --json-output JSON_OUTPUT
                      output in json format
-S STABLE_VOLUME, --stable-volume STABLE_VOLUME
                      stable volume epsilon

input must be a .pdgm file whose filtration type is alpha and which was written with the PH-tree chunk included, i.e. produced by homcloud-pc-alpha --save-phtrees on -M on (the boundary map, -M on, is required to compute the tree).

Exactly one of the point query (-x/-y) or the rectangle query (-X/-Y) should be given. If -j/--json-output is not given, the program silently computes nothing observable (there is no console output).

OUTPUT FORMAT

#

The output format (written to the file given by -j/--json-output) is JSON:

{
    "format-version": 2,
    "query": {
        "query-type": "signle",       /* [sic] always this literal string */
        "query-target": string,        /* "optimal-volume" or "stable-volume" */
        "degree": int,                 /* dim - 1 */
        "birth": double or [double, double], /* birth time, or birth range for a rectangle query */
        "death": double or [double, double], /* death time, or death range for a rectangle query */
        "ancestor-pairs": false,       /* reserved, always false */
        "query-children": false        /* reserved, always false */
    },
    "dimension": int, /* dim, as recorded in the input file */
    "result": array of volume
}

volume: {
    "birth-index": int,
    "death-index": int,
    "birth-time": double,
    "death-time": double,
    "boundary": array of simplex, /* boundary of the volume, by point coordinates */
    "boundary-by-symbols": array of symbol-simplex,
    "boundary-vertices": array of point, /* boundary vertices, by coordinates */
    "boundary-vertices-by-symbols": array of symbol,
    "vertices": array of point, /* all vertices in the volume */
    "vertices-by-symbols": array of symbol,
    "simplices": array of simplex, /* all simplices in the volume */
    "simplices-by-symbols": array of symbol-simplex,
    "children": array of child
}

child: {
    "birth-index": int,
    "death-index": int,
    "birth-time": double,
    "death-time": double,
    "children": array of child /* nested recursively */
}

point: array of float
simplex: array of point
symbol: string
symbol-simplex: array of symbol

Note that for a rectangle query, the "birth"/"death" fields of query hold the [min, max] range given by -X/-Y, not a single value, despite the singular field names.

EXAMPLE

#

homcloud-pc-alpha -d 3 --save-phtrees on -M on points.txt points.pdgm
homcloud-phtrees -x 1.0 -y 4.0 -j result.json points.pdgm
homcloud-phtrees -X "[0.5:1.5]" -Y "[3.5:4.5]" -S 0.1 -j stable.json points.pdgm

NOTES

#

If neither a point query nor a rectangle query is given (or an incomplete one, e.g. only -x without -y), the program currently fails with an unhandled UnboundLocalError rather than a clear error message; always give a complete -x/-y pair or a complete -X/-Y pair.

There used to be a separate homcloud-build-phtrees command that wrote a narrower, standalone PH-tree .pdgm file (filtration type alpha-phtrees) for this program to query. That command has been removed: it computed exactly the same tree as homcloud-pc-alpha --save-phtrees on (both call the same homcloud.build_phtrees.PHTrees class internally), its own output format was never fully supported by the rest of HomCloud (in particular homcloud-phtrees itself could not read it), and its one structural advantage — skipping the boundary-matrix reduction step — did not show a measurable speed benefit in practice. Use homcloud-pc-alpha --save-phtrees on -M on instead, as in the example above.