# mystic scripts documentation¶

## mystic_collapse_plotter script¶

generate cost convergence rate plots from file written with write_support_file

Available from the command shell as:

mystic_collapse_plotter filename [options]


or as a function call:

mystic.collapse_plotter(filename, **options)

param filename

name of the convergence logfile (e.g paramlog.py).

type filename

str

returns

None

Notes

• The option dots takes a boolean, and will show data points in the plot.

• The option linear takes a boolean, and will plot in a linear scale.

• The option out takes a string of the filepath for the generated plot. If out = True, return the Figure object instead of generating a plot.

• The option iter takes an integer of the largest iteration to plot.

• The option label takes a label string. For example, label = "y" will label the plot with a ‘y’, while label = " log-cost, $log_{10}(\hat{P} - \hat{P}_{max})$" will label the y-axis with standard LaTeX math formatting. Note that the leading space is required, and that the text is aligned along the axis.

• The option col takes a string of comma-separated integers indicating iteration numbers where parameter collapse has occurred. If a second set of integers is provided (delineated by a semicolon), the additional set of integers will be plotted with a different linestyle (to indicate a different type of collapse).

plot parameter convergence from file written with LoggingMonitor

Available from the command shell as:

mystic_log_reader filename [options]


or as a function call:

mystic.log_reader(filename, **options)

param filename

name of the convergence logfile (e.g log.txt).

type filename

str

returns

None

Notes

• The option out takes a string of the filepath for the generated plot. If out = True, return the Figure object instead of generating a plot.

• The option dots takes a boolean, and will show data points in the plot.

• The option line takes a boolean, and will connect the data with a line.

• The option iter takes an integer of the largest iteration to plot.

• The option legend takes a boolean, and will display the legend.

• The option nid takes an integer of the nth simultaneous points to plot.

• The option param takes an indicator string. The indicator string is built from comma-separated array slices. For example, param = ":" will plot all parameters. Alternatively, param = ":2, 3:" will plot all parameters except for the third parameter, while param = "0" will only plot the first parameter.

## mystic_model_plotter script¶

generate surface contour plots for model, specified by full import path; and generate model trajectory from logfile (or solver restart file), if provided

Available from the command shell as:

mystic_model_plotter model (logfile) [options]


or as a function call:

mystic.model_plotter(model, logfile=None, **options)

param model

full import path for the model (e.g. mystic.models.rosen)

type model

str

param logfile

name of convergence logfile (e.g. log.txt)

type logfile

str, default=None

returns

None

Notes

• The option out takes a string of the filepath for the generated plot. If out = True, return the Figure object instead of generating a plot.

• The option bounds takes an indicator string, where bounds are given as comma-separated slices. For example, using bounds = "-1:10, 0:20" will set lower and upper bounds for x to be (-1,10) and y to be (0,20). The “step” can also be given, to control the number of lines plotted in the grid. Thus "-1:10:.1, 0:20" sets the bounds as above, but uses increments of .1 along x and the default step along y. For models > 2D, the bounds can be used to specify 2 dimensions plus fixed values for remaining dimensions. Thus, "-1:10, 0:20, 1.0" plots the 2D surface where the z-axis is fixed at z=1.0. When called from a script, slice objects can be used instead of a string, thus "-1:10:.1, 0:20, 1.0" becomes (slice(-1,10,.1), slice(20), 1.0).

• The option label takes comma-separated strings. For example, label = "x,y," will place ‘x’ on the x-axis, ‘y’ on the y-axis, and nothing on the z-axis. LaTeX is also accepted. For example, label = "$h$, ${\alpha}$, $v$" will label the axes with standard LaTeX math formatting. Note that the leading space is required, while a trailing space aligns the text with the axis instead of the plot frame.

• The option nid takes an integer of the nth simultaneous points to plot.

• The option iter takes an integer of the largest iteration to plot.

• The option reduce can be given to reduce the output of a model to a scalar, thus converting model(params) to reduce(model(params)). A reducer is given by the import path (e.g. numpy.add).

• The option scale will convert the plot to log-scale, and scale the cost by z=log(4*z*scale+1)+2. This is useful for visualizing small contour changes around the minimium.

• If using log-scale produces negative numbers, the option shift can be used to shift the cost by z=z+shift. Both shift and scale are intended to help visualize contours.

• The option fill takes a boolean, to plot using filled contours.

• The option depth takes a boolean, to plot contours in 3D.

• The option dots takes a boolean, to show trajectory points in the plot.

• The option join takes a boolean, to connect trajectory points.

• The option verb takes a boolean, to print the model documentation.

• The option kernel can be given to transform the input of a model from nD to 2D, where params' = model(params) with params' being 2D. A kernel is given by the import path (e.g. mymodule.kernel). Using kernel can be slow, as it may calcuate inverse transform at each point.

• The option tol takes a float of max distance of dots from surface. For finer control, provide an array[float] the same length as params.

## support_convergence script¶

generate parameter convergence plots from file written with write_support_file

Available from the command shell as:

support_convergence filename [options]


or as a function call:

mystic.support.convergence(filename, **options)

param filename

name of the convergence logfile (e.g paramlog.py)

type filename

str

returns

None

Notes

• The option out takes a string of the filepath for the generated plot. If out = True, return the Figure object instead of generating a plot.

• The option iter takes an integer of the largest iteration to plot.

• The option param takes an indicator string. The indicator string is built from comma-separated array slices. For example, param = ":" will plot all parameters in a single plot. Alternatively, param = ":2, 2:" will split the parameters into two plots, and param = "0" will only plot the first parameter.

• The option label takes comma-separated strings. For example, label = "x,y," will label the y-axis of the first plot with ‘x’, a second plot with ‘y’, and not add a label to a third or subsequent plots. If more labels are given than plots, then the last label will be used for the y-axis of the ‘cost’ plot. LaTeX is also accepted. For example, label = "$h$, $a$, $v$" will label the axes with standard LaTeX math formatting. Note that the leading space is required, and the text is aligned along the axis.

• The option nid takes an integer of the nth simultaneous points to plot.

• The option cost takes a boolean, and will also plot the parameter cost.

• The option legend takes a boolean, and will display the legend.

## support_hypercube script¶

generate parameter support plots from file written with write_support_file

Available from the command shell as:

support_hypercube filename [options]


or as a function call:

mystic.support.hypercube(filename, **options)

param filename

name of the convergence logfile (e.g paramlog.py)

type filename

str

returns

None

Notes

• The option out takes a string of the filepath for the generated plot. If out = True, return the Figure object instead of generating a plot.

• The options bounds, axes, and iters all take indicator strings. The bounds should be given as comma-separated slices. For example, using bounds = "60:105, 0:30, 2.1:2.8" will set the lower and upper bounds for x to be (60,105), y to be (0,30), and z to be (2.1,2.8). Similarly, axes also accepts comma-separated groups of ints; however, for axes, each entry indicates which parameters are to be plotted along each axis – the first group for the x direction, the second for the y direction, and third for z. Thus, axes = "2 3, 6 7, 10 11" would set 2nd and 3rd parameters along x. Iters also accepts strings built from comma-separated array slices. For example, iters = ":" will plot all iters in a single plot. Alternatively, iters = ":2, 2:" will split the iters into two plots, while iters = "0" will only plot the first iteration.

• The option label takes comma-separated strings. Thus label = "x,y," will place ‘x’ on the x-axis, ‘y’ on the y-axis, and nothing on the z-axis. LaTeX, such as label = "$h$, $a$, $v$" will label the axes with standard LaTeX math formatting. Note that the leading space is required, while a trailing space aligns the text with the axis instead of the plot frame.

• The option nid takes an integer of the nth simultaneous points to plot.

• The option scale takes an integer as a grayscale contrast multiplier.

• The option flat takes a boolean, to plot results in a single plot.

## support_hypercube_measures script¶

generate measure support plots from file written with write_support_file

Available from the command shell as:

support_hypercube_measures filename [options]


or as a function call:

mystic.support.hypercube_measures(filename, **options)

param filename

name of the convergence logfile (e.g paramlog.py)

type filename

str

returns

None

Notes

• The option out takes a string of the filepath for the generated plot. If out = True, return the Figure object instead of generating a plot.

• The options bounds, axes, weight, and iters all take indicator strings. The bounds should be given as comma-separated slices. For example, using bounds = "60:105, 0:30, 2.1:2.8" will set lower and upper bounds for x to be (60,105), y to be (0,30), and z to be (2.1,2.8). Similarly, axes also accepts comma-separated groups of ints; however, for axes, each entry indicates which parameters are to be plotted along each axis – the first group for the x direction, the second for the y direction, and third for z. Thus, axes = "2 3, 6 7, 10 11" would set 2nd and 3rd parameters along x. The corresponding weights are used to color the measure points, where 1.0 is black and 0.0 is white. For example, using weight = "0 1, 4 5, 8 9" would use the 0th and 1st parameters to weight x. Iters is also similar, however only accepts comma-separated ints. Hence, iters = "-1" will plot the last iteration, while iters = "0, 300, 700" will plot the 0th, 300th, and 700th in three plots.

• The option label takes comma-separated strings. Thus label = "x,y," will place ‘x’ on the x-axis, ‘y’ on the y-axis, and nothing on the z-axis. LaTeX, such as label = "$h$, $a$, $v$" will label the axes with standard LaTeX math formatting. Note that the leading space is required, while a trailing space aligns the text with the axis instead of the plot frame.

• The option nid takes an integer of the nth simultaneous points to plot.

• The option scale takes an integer as a grayscale contrast multiplier.

• The option flat takes a boolean, to plot results in a single plot.

Warning

This function is intended to visualize weighted measures (i.e. weights and positions), where the weights must be normalized (to 1) or an error will be thrown.

## support_hypercube_scenario script¶

generate scenario support plots from file written with write_support_file; and generate legacy data and cones from a dataset file, if provided

Available from the command shell as:

support_hypercube_scenario filename (datafile) [options]


or as a function call:

mystic.support.hypercube_scenario(filename, datafile=None, **options)

param filename

name of the convergence logfile (e.g. paramlog.py)

type filename

str

param datafile

name of the dataset file (e.g. data.txt)

type datafile

str, default=None

returns

None

Notes

• The option out takes a string of the filepath for the generated plot. If out = True, return the Figure object instead of generating a plot.

• The options bounds, dim, and iters all take indicator strings. The bounds should be given as comma-separated slices. For example, using bounds = ".062:.125, 0:30, 2300:3200" will set lower and upper bounds for x to be (.062,.125), y to be (0,30), and z to be (2300,3200). If all bounds are to not be strictly enforced, append an asterisk * to the string. The dim (dimensions of the scenario) should comma-separated ints. For example, dim = "1, 1, 2" will convert the params to a two-member 3-D dataset. Iters accepts a string built from comma-separated array slices. Thus, iters = ":" will plot all iters in a single plot. Alternatively, iters = ":2, 2:" will split the iters into two plots, while iters = "0" will only plot the first iteration.

• The option label takes comma-separated strings. Thus label = "x,y," will place ‘x’ on the x-axis, ‘y’ on the y-axis, and nothing on the z-axis. LaTeX, such as label = "$h$, $a$, $v$" will label the axes with standard LaTeX math formatting. Note that the leading space is required, while a trailing space aligns the text with the axis instead of the plot frame.

• The option “filter” is used to select datapoints from a given dataset, and takes comma-separated ints.

• A “mask” is given as comma-separated ints. When the mask has more than one int, the plot will be 2D.

• The option “vertical” will plot the dataset values on the vertical axis; for 2D plots, cones are always plotted on the vertical axis.

• The option nid takes an integer of the nth simultaneous points to plot.

• The option scale takes an integer as a grayscale contrast multiplier.

• The option gap takes an integer distance from cone center to vertex.

• The option data takes a boolean, to plot legacy data, if provided.

• The option cones takes a boolean, to plot cones, if provided.

• The option flat takes a boolean, to plot results in a single plot.