Alpha's command line interface has been growing organically for quite some time. Right now, we have a lot of different flags and options that are partly related and - in some cases - influence each other in a rather intransparent fashion.
In order to make the CLI a bit more approachable, it would be useful to group related options by category, e.g.
preprocessing (re-writing options, ...)
grounding (for grounder type, heuristics etc)
solving
output formatting
One way to achieve this from a programming point of view would be switching to a more powerful argument parsing library - one I can think of right now is argparse4j, which supports subcommands which could be used for grouping of options.
This task is divided into two basic steps:
[ ] Specfiy how an ideal CLI should look (i.e. complete usage)
[ ] Implement result of step 1 using a suitable library
clingo options
```
$ clingo --help=3
clingo version 5.4.0
usage: clingo [number] [options] [files]
Clasp.Config Options:
--configuration= : Set default configuration [auto]
: {auto|frumpy|jumpy|tweety|handy|crafty|trendy|many|}
auto : Select configuration based on problem type
frumpy: Use conservative defaults
jumpy : Use aggressive defaults
tweety: Use defaults geared towards asp problems
handy : Use defaults geared towards large problems
crafty: Use defaults geared towards crafted problems
trendy: Use defaults geared towards industrial problems
many : Use default portfolio to configure solver(s)
: Use configuration file to configure solver(s)
--tester= : Pass (quoted) string of to tester
--stats[=[,]],-s : Enable {1=basic|2=full} statistics ( for tester)
--[no-]parse-ext : Enable extensions in non-aspif input
--[no-]parse-maxsat : Treat dimacs input as MaxSAT problem
Clasp.Context Options:
--share=|no : Configure physical sharing of constraints [auto]
: {auto|problem|learnt|all}
--learn-explicit : Do not use Short Implication Graph for learning
--sat-prepro[=|no] : Run SatELite-like preprocessing (Implicit: 2)
: [,...]
: Set preprocessing level to
1: Variable elimination with subsumption (VE)
2: VE with limited blocked clause elimination (BCE)
3: Full BCE followed by VE
: [=] (0=no limit)
iter : Set iteration limit to [0]
occ : Set variable occurrence limit to [0]
time : Set time limit to seconds [0]
frozen: Set frozen variables limit to % [0]
size : Set size limit to *1000 clauses [4000]
Clasp.ASP Options:
--trans-ext=|no : Configure handling of extended rules
: {all|choice|card|weight|integ|dynamic}
all : Transform all extended rules to basic rules
choice : Transform choice rules, but keep cardinality and weight rules
card : Transform cardinality rules, but keep choice and weight rules
weight : Transform cardinality and weight rules, but keep choice rules
scc : Transform "recursive" cardinality and weight rules
integ : Transform cardinality integrity constraints
dynamic: Transform "simple" extended rules, but keep more complex ones
--eq= : Configure equivalence preprocessing
Run for at most iterations (-1=run to fixpoint)
--[no-]backprop : Use backpropagation in ASP-preprocessing
--supp-models : Compute supported models
--no-ufs-check : Disable unfounded set check
--no-gamma : Do not add gamma rules for non-hcf disjunctions
--eq-dfs : Enable df-order in eq-preprocessing
Clasp.Solving Options:
--solve-limit=[,] : Stop search after conflicts or restarts
--parallel-mode,-t : Run parallel search with given number of threads
: [,]
: Number of threads to use in search
: Run competition or splitting based search [compete]
--global-restarts= : Configure global restart policy
: [,]
: Maximal number of global restarts (0=disable)
: Restart schedule [x,100,1.5] ()
--distribute=|no : Configure nogood distribution [conflict,global,4]
: [,][,][,]
: Distribute {all|short|conflict|loop} nogoods
: Use {global|local} distribution [global]
: Distribute only if LBD <= [4]
: Distribute only if size <= [-1]
--integrate= : Configure nogood integration [gp]
: [,][,]
: Add {all|unsat|gp(unsat wrt guiding path)|active} nogoods
: Always keep at least last integrated nogoods [1024]
: Accept nogoods from {all|ring|cube|cubex} peers [all]
--enum-mode,-e : Configure enumeration algorithm [auto]
: {bt|record|brave|cautious|auto}
bt : Backtrack decision literals from solutions
record : Add nogoods for computed solutions
domRec : Add nogoods over true domain atoms
brave : Compute brave consequences (union of models)
cautious: Compute cautious consequences (intersection of models)
auto : Use bt for enumeration and record for optimization
--project[=|no] : Enable projective solution enumeration
: {show|project|auto}[,] (Implicit: auto,3)
Project to atoms in show or project directives, or
select depending on the existence of a project directive
: Additional options for enumeration algorithm 'bt'
Use activity heuristic (1) when selecting backtracking literal
and/or progress saving (2) when retracting solution literals
--models,-n : Compute at most models (0 for all)
--opt-mode= : Configure optimization algorithm
: [,...]
opt : Find optimal model
enum : Find models with costs <=
optN : Find optimum, then enumerate optimal models
ignore: Ignore optimize statements
: Set initial bound for objective function(s)
Clasp.Search Options:
--opt-strategy= : Configure optimization strategy
: {bb|usc}[,]
bb : Model-guided optimization with [lin]
lin : Basic lexicographical descent
hier: Hierarchical (highest priority criteria first) descent
inc : Hierarchical descent with exponentially increasing steps
dec : Hierarchical descent with exponentially decreasing steps
usc: Core-guided optimization with : [,]
: Relaxation algorithm {oll|one|k|pmres} [oll]
oll : Use strategy from unclasp
one : Add one cardinality constraint per core
k[,]: Add cardinality constraints of bounded size ([0]=dynamic)
pmres : Add clauses of size 3
: Tactics |
disjoint: Disjoint-core preprocessing (1)
succinct: No redundant (symmetry) constraints (2)
stratify: Stratification heuristic for handling weights (4)
--opt-usc-shrink= : Enable core-shrinking in core-guided optimization
: [, (0=no limit)]
: Use algorithm {lin|inv|bin|rgs|exp|min}
lin : Forward linear search unsat
inv : Inverse linear search not unsat
bin : Binary search
rgs : Repeated geometric sequence until unsat
exp : Exponential search until unsat
min : Linear search for subset minimal core
: Limit solve calls to 2^ conflicts [10]
--opt-heuristic= : Use opt. in heuristics
--[no-]restart-on-model : Restart after each model
--lookahead[=|no] : Configure failed-literal detection (fld)
: [,] / Implicit: atom
: Run fld via {atom|body|hybrid} lookahead
: Disable fld after applications ([0]=no limit)
--lookahead=atom is default if --no-lookback is used
--heuristic= : Configure decision heuristic
: {Berkmin|Vmtf|Vsids|Domain|Unit|None}[,]
Berkmin: Use BerkMin-like heuristic (Check last nogoods [0]=all)
Vmtf : Use Siege-like heuristic (Move literals to the front [8])
Vsids : Use Chaff-like heuristic (Use 1.0/0. as decay factor [95])
Domain : Use domain knowledge in Vsids-like heuristic
Unit : Use Smodels-like heuristic (Default if --no-lookback)
None : Select the first free variable
--[no-]init-moms : Initialize heuristic with MOMS-score
--score-res= : Resolution score {auto|min|set|multiset}
--score-other= : Score other learnt nogoods: {auto|no|loop|all}
--sign-def= : Default sign: {asp|pos|neg|rnd}
--[no-]sign-fix : Disable sign heuristics and use default signs only
--[no-]berk-huang : Enable Huang-scoring in Berkmin
--[no-]vsids-acids : Enable acids-scheme in Vsids/Domain
--vsids-progress= : Enable dynamic decaying scheme in Vsids/Domain
: [,][,]|(0=disable)
: Set initial decay factor to 1.0/0. : Set decay update to /100.0 [1]
: Decrease decay every conflicts [5000]
--[no-]nant : Prefer negative antecedents of P in heuristic
--dom-mod= : Default modification for domain heuristic
: (no|[,])
: Modifier {level|pos|true|neg|false|init|factor}
: Apply to (all | ) atoms
--save-progress[=] : Use RSat-like progress saving on backjumps >
--init-watches= : Watched literal initialization: {rnd|first|least}
--update-mode= : Process messages on {propagate|conflict}
--acyc-prop[={0..1}] : Use backward inference in acyc propagation
--seed= : Set random number generator's seed to
--partial-check[=] : Configure partial stability tests
:
[,] / Implicit: 50
: Partial check skip percentage
: Init/update value for high bound ([0]=umax)
--sign-def-disj= : Default sign for atoms in disjunctions
--rand-freq=
|no : Make random decisions with probability
--rand-prob=[,] : Do random searches with [=100] conflicts
Clasp.Lookback Options:
--no-lookback : Disable all lookback strategies
--forget-on-step= : Configure forgetting on (incremental) step
: |
--strengthen=|no : Use MiniSAT-like conflict nogood strengthening
: [,][,]
: Use {local|recursive} self-subsumption check
: Follow {all|short|binary} antecedents [all]
: Bump activities of antecedents [yes]
--otfs[={0..2}] : Enable {1=partial|2=full} on-the-fly subsumption
--update-lbd=|no : Configure LBD updates during conflict resolution
: [,]
less : update to X = new LBD iff X < previous LBD
glucose: update to X = new LBD iff X+1 < previous LBD
pseudo : update to X = new LBD+1 iff X < previous LBD
: Protect updated nogoods on next reduce if X <=
--update-act : Enable LBD-based activity bumping
--reverse-arcs[={0..3}] : Enable ManySAT-like inverse-arc learning
--contraction=|no : Configure handling of long learnt nogoods
: [,]
: Contract nogoods if size > (0=disable)
: Nogood replacement {no|decisionSeq|allUIP|dynamic} [no]
--loops= : Configure learning of loop nogoods
: {common|distinct|shared|no}
common : Create loop nogoods for atoms in an unfounded set
distinct: Create distinct loop nogood for each atom in an unfounded set
shared : Create loop formula for a whole unfounded set
no : Do not learn loop formulas
--restarts,-r |no: Configure restart policy
: ,[,][,]
F, : Run fixed sequence of conflicts
L, : Run Luby et al.'s sequence with unit length
x,,: Run geometric seq. of *(^i) conflicts ( >= 1.0)
+,,: Run arithmetic seq. of +(*i) conflicts ()
...,: Repeat seq. every +j restarts ( != F)
D,,: Restart based on moving LBD average over last conflicts
Mavg(,LBD)* > avg(LBD)
use conflict level average if > 0 and avg(LBD) >
no|0 : Disable restarts
--reset-restarts= : Update restart seq. on model {no|repeat|disable}
--[no-]local-restarts : Use Ryvchin et al.'s local restarts
--counter-restarts=: Use counter implication restarts
: ([,] | {0|no})
: Interval in number of restarts
: Bump factor applied to indegrees
--block-restarts= : Use glucose-style blocking restarts
: [,][,]
: Window size for moving average (0=disable blocking)
: Block restart if assignment > average * [1.4]
: Disable blocking for the first conflicts [10000]
--shuffle=,|no : Shuffle problem after +(*i) restarts
--deletion,-d |no : Configure deletion algorithm [basic,75,0]
: [,][,]
: Use {basic|sort|ipSort|ipHeap} algorithm
: Delete at most % of nogoods on reduction [75]
: Use {activity|lbd|mixed} nogood scores [activity]
no : Disable nogood deletion
--del-grow=|no : Configure size-based deletion policy
: [,][,] ( >= 1.0)
: Keep at most T = X*(^i) learnt nogoods with X being the
initial limit and i the number of times fired
: Stop growth once T > P*
Alpha's command line interface has been growing organically for quite some time. Right now, we have a lot of different flags and options that are partly related and - in some cases - influence each other in a rather intransparent fashion.
In order to make the CLI a bit more approachable, it would be useful to group related options by category, e.g.
One way to achieve this from a programming point of view would be switching to a more powerful argument parsing library - one I can think of right now is argparse4j, which supports subcommands which could be used for grouping of options.
This task is divided into two basic steps: