document analyze-archive

1 files changed, 58 insertions, 0 deletions

diff --git a/bin/analyze-archive.py b/bin/analyze-archive.py
index 276daf5..21f9ceb 100755
--- a/bin/analyze-archive.py
+++ b/bin/analyze-archive.py
@@ -1,4 +1,62 @@
 #!/usr/bin/env python3
+"""
+analyze-archive -- generate PTA energy model from annotated traces.
+
+Usage:
+PYTHONPATH=lib bin/analyze-archive.py [options] <tracefiles ...>
+
+analyze-archive generates a PTA energy model from one or more annotated
+traces generated by MIMOSA/dfatool-legacy. By default, it does nothing else --
+use one of the --plot-* or --show-* options to examine the generated model.
+
+Options:
+--plot-unparam=<name>:<attribute>:<Y axis label>[;<name>:<attribute>:<label>;...]
+    Plot all mesurements for <name> <attribute> without regard for parameter values.
+    X axis is measurement number/id.
+
+--plot-param=<name> <attribute> <parameter> [gplearn function][;<name> <attribute> <parameter> [function];...]
+    Plot measurements for <name> <attribute> by <parameter>.
+    X axis is parameter value.
+    Plots the model function as one solid line for each combination of non-<parameter>
+    parameters. Also plots the corresponding measurements.
+    If gplearn function is set, it is plotted using dashed lines.
+
+--show-models=<static|paramdetection|param|all|tex>
+    static: show static model values as well as parameter detection heuristic
+    paramdetection: show stddev of static/lut/fitted model
+    param: show parameterized model functions and regression variable values
+    all: all of the above
+    tex: print tex/pgfplots-compatible model data on stdout
+
+--show-quality=<table|summary|all|tex>
+    table: show static/fitted/lut SMAPE and MAE for each name and attribute
+    summary: show static/fitted/lut SMAPE and MAE for each attribute, averaged over all states/transitions
+    all: all of the above
+    tex: print tex/pgfplots-compatible model quality data on stdout
+
+--ignored-trace-indexes=<i1,i2,...>
+    Specify traces which should be ignored due to bogus data. 1 is the first
+    trace, 2 the second, and so on.
+
+--discard-outliers=
+    not supported at the moment
+
+--function-override=<name attribute function>[;<name> <attribute> <function>;...]
+    Manually specify the function to fit for <name> <attribute>. A function
+    specified this way bypasses parameter detection: It is always assigned,
+    even if the model seems to be independent of the parameters it references.
+
+--with-safe-functions
+    If set, include "safe" functions (safe_log, safe_inv, safe_sqrt) which are
+    also defined for cases such as safe_inv(0) or safe_sqrt(-1). This allows
+    a greater range of functions to be tried during fitting.
+
+--hwmodel=<hwmodel.json>
+    Load DFA hardware model from JSON
+
+--export-energymodel=<model.json>
+    Export energy model. Requires --hwmodel.
+"""
 
 import getopt
 import json