NAME#
optvol - Compute optimal volumes and variants of stable/tightened volumes
SYNOPSIS#
homcloud-optvol
[-h] [-V] [--license] -d DEGREE [-x X] [-y Y] [-X X_RANGE]
[-Y Y_RANGE] [-j JSON_OUTPUT] [-T TYPE] [-e EPSILON]
[-c CUTOFF_RADIUS] [-n RETRY] [--skip-infeasible SKIP_INFEASIBLE]
[--solver SOLVER] [-O OPTION]
input
This program can also be invoked as python3 -m homcloud.cli.optvol.
ALIAS#
homcloud-optvol
DESCRIPTION#
This program computes optimal volumes and volume-optimal cycles for given birth-death pairs.
The input file (a .pdgm file) must have the boundary map
information saved in it. This is done by giving -M on to the
program that created the diagram, for example:
homcloud-pc-alphahomcloud-ripshomcloud-abstract-filtrationhomcloud-pict-binarize-ndhomcloud-pict-pixel-levelset-nd
You can specify a single point by using the -x and -y options.
The program chooses the closest birth-death pair to that point and
computes an optimal volume / volume-optimal cycle for the pair.
You can also specify a rectangle region on the persistence diagram
using the -X and -Y options. The program computes the
volume-optimal cycle for every birth-death pair in the given
rectangle.
OPTIONS#
positional arguments:
input input filename
options:
-h, --help show this help message and exit
-V, --version show program's version number and exit
--license show license and exit
target:
-d DEGREE, --degree DEGREE
degree of PH
-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
output options:
-j JSON_OUTPUT, --json-output JSON_OUTPUT
output in json format
computation parameters:
-T TYPE, --type TYPE target type (*optimal-volume*, tightened-volume,
or tightened-subvolume
-e EPSILON, --epsilon EPSILON
tighened-volume/subvolume epsilon
-c CUTOFF_RADIUS, --cutoff-radius CUTOFF_RADIUS
cut-off radius in R^n
-n RETRY, --retry RETRY
number of retry
--skip-infeasible SKIP_INFEASIBLE
skip infeasible (on/*off*)
solver parameters:
--solver SOLVER LP solver name
-O OPTION, --option OPTION
options for LP solver
Exactly one of the point query (-x/-y) or the rectangle query
(-X/-Y) must be given; otherwise the program raises an error.
-c/--cutoff-radius and -n/--retry only have an effect for
alpha and cubical filtrations (where a spatial neighborhood is
meaningful); they are ignored for abstract and simplicial
filtrations.
OUTPUT FORMAT#
The output format of this module (written to the file given by
-j/--json-output) is JSON.
{
"format-version": 2.0, /* version of the format of this file */
"query": query, /* Query information */
"result": array of result /* One entry per queried birth-death pair */
}
query: {
"degree": int, /* degree of PH */
"solver-name": string, /* LP solver class name */
"solver-options": string or null, /* LP solver options */
"cutoff-radius": double, /* cutoff radius, only for alpha/cubical filtrations */
"num-retry": int, /* number of retries, only for alpha/cubical filtrations */
"query-target": string, /* "optimal-volume", "tightened-volume", or "tightened-subvolume" */
"birth": double, /* the birth time for a point query */
"death": double, /* the death time for a point query */
"birth-range": [double, double], /* the range of birth times for a rectangle query */
"death-range": [double, double], /* the range of death times for a rectangle query */
"skip-infeasible": bool /* only for a rectangle query */
}
result (success): {
"birth-time": double,
"death-time": double,
"birth-index": int,
"death-index": int,
"success": true,
"tightened-subvolume": result or null, /* nested tightened subvolume, when applicable */
"points": array of point, /* all vertices in the volume; alpha/cubical only */
"simplices": array of simplex, /* all simplices in the volume; alpha only */
"cubes": array of cube, /* all cubes in the volume; cubical only */
"cells": array of cell, /* all cells in the volume; abstract only */
"boundary": array of simplex/cube/cell, /* the boundary of the volume */
"boundary-points": array of point, /* boundary vertices; alpha/cubical only */
"points-symbols": array of symbol, /* all vertices in the volume, by symbol; alpha/simplicial only */
"simplices-symbols": array of symbol-simplex, /* alpha/simplicial only */
"boundary-symbols": array of symbol-simplex, /* alpha/simplicial only */
"boundary-points-symbols": array of symbol, /* alpha/simplicial only */
"children": array of pair /* children pairs' information */
}
result (failure; a point query always returns its result even on
failure, a rectangle query only includes a failure entry for an
infeasible pair when `--skip-infeasible on` is given): {
"birth-time": double,
"death-time": double,
"success": false,
"status": string /* PuLP LP status, e.g. "Infeasible" */
}
pair: {
"birth-time": double,
"death-time": double,
"birth-index": int,
"death-index": int
}
point: array of float
simplex: array of point
cell: array of point-or-symbol
symbol: string
symbol-simplex: array of symbol
cube: [array of int, array of bool]
For a rectangle query, an infeasible pair aborts the whole command
with an error unless --skip-infeasible on is given, in which case
it is recorded as a failure result instead. A point query never
aborts: an infeasible pair is simply returned as a single failure
result.
EXAMPLE#
A single pair query.
homcloud-optvol -d 1 -x 2.5 -y 6.2 -j voc.json example.pdgm
Rectangle query.
homcloud-optvol -d 1 -X "[2.4:2.5]" -Y "[6.2:6.3]" -j voc.json example.pdgm
NOTES#
The -P/--invoke-paraview option that used to launch ParaView on
the computed volume has been removed; visualize the resulting JSON
with homcloud-view-index-pict/homcloud-pict-show-volume-2d, or
with your own ParaView/matplotlib script instead.