docs/notebooks/PICS/FuzzingWithConstraints-synopsis-1.svg

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN"
 "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<!-- Generated by graphviz version 7.0.2 (20221119.0110)
 -->
<!-- Pages: 1 -->
<svg width="228pt" height="84pt"
 viewBox="0.00 0.00 228.00 84.00" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
<g id="graph0" class="graph" transform="scale(1 1) rotate(0) translate(4 80)">
<g id="a_graph0"><a xlink:title="ISLaSolver class hierarchy">
<polygon fill="white" stroke="none" points="-4,4 -4,-80 224,-80 224,4 -4,4"/>
</a>
</g>
<!-- ISLaSolver -->
<g id="node1" class="node">
<title>ISLaSolver</title>
<g id="a_node1"><a xlink:href="isla.solver.ipynb" xlink:title="class ISLaSolver:&#10;The solver class for ISLa formulas/constraints. Its methods are&#10;`solve()`, `check(DerivationTree | str)`, `parse(str)`, and&#10;`repair(DerivationTree | str)`.">
<polygon fill="none" stroke="black" points="0,-0.5 0,-75.5 82,-75.5 82,-0.5 0,-0.5"/>
<text text-anchor="start" x="8" y="-61.3" font-family="Patua One, Helvetica, sans-serif" font-weight="bold" font-size="14.00" fill="#b03a2e">ISLaSolver</text>
<polyline fill="none" stroke="black" points="0,-52.5 82,-52.5"/>
<g id="a_node1_0"><a xlink:href="#" xlink:title="ISLaSolver">
<g id="a_node1_1"><a xlink:href="isla.solver.ipynb" xlink:title="__init__(self, grammar: Union[Dict[str, List[str]], str], formula: isla.language.Formula | str = &#39;true&#39;, structural_predicates: Set[isla.language.StructuralPredicate] = {StructuralPredicate(name=&#39;after&#39;, arity=2, eval_fun=&lt;function is_after&gt;), StructuralPredicate(name=&#39;inside&#39;, arity=2, eval_fun=&lt;function in_tree&gt;), StructuralPredicate(name=&#39;nth&#39;, arity=3, eval_fun=&lt;function is_nth&gt;), StructuralPredicate(name=&#39;before&#39;, arity=2, eval_fun=&lt;function is_before&gt;), StructuralPredicate(name=&#39;direct_child&#39;, arity=2, eval_fun=&lt;function is_direct_child&gt;), StructuralPredicate(name=&#39;different_position&#39;, arity=2, eval_fun=&lt;function is_different_position&gt;), StructuralPredicate(name=&#39;same_position&#39;, arity=2, eval_fun=&lt;function is_same_position&gt;), StructuralPredicate(name=&#39;level&#39;, arity=4, eval_fun=&lt;function level_check&gt;), StructuralPredicate(name=&#39;consecutive&#39;, arity=2, eval_fun=&lt;function consecutive&gt;)}, semantic_predicates: Set[isla.language.SemanticPredicate] = {SemanticPredicate(count, 3)}, max_number_free_instantiations: int = 10, max_number_smt_instantiations: int = 10, max_number_tree_insertion_results: int = 5, enforce_unique_trees_in_queue: bool = True, debug: bool = False, cost_computer: Optional[ForwardRef(&#39;CostComputer&#39;)] = None, timeout_seconds: Optional[int] = None, global_fuzzer: bool = False, predicates_unique_in_int_arg: Tuple[isla.language.SemanticPredicate, ...] = (SemanticPredicate(count, 3),), fuzzer_factory: Callable[[Dict[str, List[str]]], isla.fuzzer.GrammarFuzzer] = &lt;function ISLaSolver.&lt;lambda&gt;&gt;, tree_insertion_methods: Optional[int] = None, activate_unsat_support: bool = False, grammar_unwinding_threshold: int = 4, initial_tree: isla.helpers.Maybe[isla.derivation_tree.DerivationTree] = Maybe(a=None), enable_optimized_z3_queries: bool = True):&#10;Constructs a new ISLaSolver object. Passing a grammar and a formula is mandatory.&#10;&#10;:param grammar: The underlying grammar; either, as a &quot;Fuzzing Book&quot; dictionary or in BNF syntax.&#10;:param formula: The formula to solve; either a string or a readily parsed formula.&#10;:param structural_predicates: Structural predicates to use when parsing a formula.&#10;:param semantic_predicates: Semantic predicates to use when parsing a formula.&#10;:param max_number_free_instantiations: Number of times that nonterminals that are not bound by any formula&#10;should be expanded by a coverage&#45;based fuzzer.&#10;:param max_number_smt_instantiations: Number of solutions of SMT formulas that should be produced.&#10;:param max_number_tree_insertion_results: The maximum number of results when solving existential quantifiers&#10;by tree insertion.&#10;:param enforce_unique_trees_in_queue: If true, states with the same tree as an already existing tree in the&#10;queue are discarded, irrespectively of the constraint.&#10;:param debug: If true, debug information about the evolution of states is collected, notably in the&#10;field state_tree. The root of the tree is in the field state_tree_root. The field costs stores the computed&#10;cost values for all new nodes.&#10;:param cost_computer: The `CostComputer` class for computing the cost relevant to placing states&#10;in ISLa&#39;s queue.&#10;:param timeout_seconds: Number of seconds after which the solver will terminate.&#10;:param global_fuzzer: If set to True, only one coverage&#45;guided grammar fuzzer object is used to finish&#10;off unconstrained open derivation trees throughout the whole generation time. This may be beneficial for&#10;some targets; e.g., we experienced that CSV works significantly faster. However, the achieved k&#45;path coverage&#10;can be lower with that setting.&#10;:param predicates_unique_in_int_arg: This is needed in certain cases for instantiating universal&#10;integer quantifiers. The supplied predicates should have exactly one integer argument, and hold&#10;for exactly one integer value once all other parameters are fixed.&#10;:param fuzzer_factory: Constructor of the fuzzer to use for instantiating &quot;free&quot; nonterminals.&#10;:param tree_insertion_methods: Combination of methods to use for existential quantifier elimination by&#10;tree insertion. Full selection: `DIRECT_EMBEDDING &amp; SELF_EMBEDDING &amp; CONTEXT_ADDITION`.&#10;:param activate_unsat_support: Set to True if you assume that a formula might be unsatisfiable. This&#10;triggers additional tests for unsatisfiability that reduce input generation performance, but might&#10;ensure termination (with a negative solver result) for unsatisfiable problems for which the solver&#10;could otherwise diverge.&#10;:param grammar_unwinding_threshold: When querying the SMT solver, ISLa passes a regular expression for&#10;the syntax of the involved nonterminals. If this syntax is not regular, we unwind the respective part&#10;in the reference grammar up to a depth of `grammar_unwinding_threshold`. If this is too shallow, it can&#10;happen that an equation etc. cannot be solved; if it is too deep, it can negatively impact performance&#10;(and quite tremendously so).&#10;:param initial_tree: An initial input tree for the queue, if the solver shall&#10;not start from the tree `(&lt;start&gt;, None)`.&#10;:param enable_optimized_z3_queries: Enables preprocessing of Z3 queries (mainly&#10;numeric problems concerning things like length). This can improve performance&#10;significantly; however, it might happen that certain problems cannot be solved&#10;anymore. In that case, this option can/should be deactivated.">
<text text-anchor="start" x="11" y="-41.5" font-family="'Fira Mono', 'Source Code Pro', 'Courier', monospace" font-weight="bold" font-size="10.00">__init__()</text>
</a>
</g>
<g id="a_node1_2"><a xlink:href="isla.solver.ipynb" xlink:title="check(self, inp: isla.derivation_tree.DerivationTree | str) &#45;&gt; bool:&#10;Evaluates whether the given derivation tree satisfies the constraint passed to&#10;the solver. Raises an `UnknownResultError` if this could not be evaluated&#10;(e.g., because of a solver timeout or a semantic predicate that cannot be&#10;evaluated).&#10;&#10;:param inp: The input to evaluate, either readily parsed or as a string.&#10;:return: A truth value.">
<text text-anchor="start" x="11" y="-30.5" font-family="'Fira Mono', 'Source Code Pro', 'Courier', monospace" font-weight="bold" font-size="10.00">check()</text>
</a>
</g>
<g id="a_node1_3"><a xlink:href="isla.solver.ipynb" xlink:title="parse(self, inp: str, nonterminal: str = &#39;&lt;start&gt;&#39;, skip_check: bool = False) &#45;&gt; isla.derivation_tree.DerivationTree:&#10;Parses the given input `inp`. Raises a `SyntaxError` if the input does not&#10;satisfy the grammar, a `SemanticError` if it does not satisfy the constraint&#10;(this is only checked if `nonterminal` is &quot;&lt;start&gt;&quot;), and returns the parsed&#10;`DerivationTree` otherwise.&#10;&#10;:param inp: The input to parse.&#10;:param nonterminal: The nonterminal to start parsing with, if a string&#10;corresponding to a sub&#45;grammar shall be parsed. We don&#39;t check semantic&#10;correctness in that case.&#10;:param skip_check: If True, the semantic check is left out.&#10;:return: A parsed `DerivationTree`.">
<text text-anchor="start" x="11" y="-19.5" font-family="'Fira Mono', 'Source Code Pro', 'Courier', monospace" font-weight="bold" font-size="10.00">parse()</text>
</a>
</g>
<g id="a_node1_4"><a xlink:href="isla.solver.ipynb" xlink:title="solve(self) &#45;&gt; isla.derivation_tree.DerivationTree:&#10;Attempts to compute a solution to the given ISLa formula. Returns that solution,&#10;if any. This function can be called repeatedly to obtain more solutions until&#10;one of two exception types is raised: A `StopIteration` indicates that no more&#10;solution can be found; a `TimeoutError` is raised if a timeout occurred.&#10;After that, an exception will be raised every time.&#10;&#10;The timeout can be controlled by the `timeout_seconds` constructor parameter.&#10;&#10;:return: A solution for the ISLa formula passed to the `ISLaSolver`.">
<text text-anchor="start" x="11" y="-8.5" font-family="'Fira Mono', 'Source Code Pro', 'Courier', monospace" font-weight="bold" font-size="10.00">solve()</text>
</a>
</g>
</a>
</g>
</a>
</g>
</g>
<!-- Legend -->
<g id="node2" class="node">
<title>Legend</title>
<text text-anchor="start" x="100" y="-55.5" font-family="Patua One, Helvetica, sans-serif" font-weight="bold" font-size="10.00" fill="#b03a2e">Legend</text>
<text text-anchor="start" x="100" y="-45.5" font-family="Patua One, Helvetica, sans-serif" font-size="10.00">• </text>
<text text-anchor="start" x="107" y="-45.5" font-family="'Fira Mono', 'Source Code Pro', 'Courier', monospace" font-weight="bold" font-size="8.00">public_method()</text>
<text text-anchor="start" x="100" y="-35.5" font-family="Patua One, Helvetica, sans-serif" font-size="10.00">• </text>
<text text-anchor="start" x="107" y="-35.5" font-family="'Fira Mono', 'Source Code Pro', 'Courier', monospace" font-size="8.00">private_method()</text>
<text text-anchor="start" x="100" y="-25.5" font-family="Patua One, Helvetica, sans-serif" font-size="10.00">• </text>
<text text-anchor="start" x="107" y="-25.5" font-family="'Fira Mono', 'Source Code Pro', 'Courier', monospace" font-style="italic" font-size="8.00">overloaded_method()</text>
<text text-anchor="start" x="100" y="-16.3" font-family="Helvetica,sans-Serif" font-size="9.00">Hover over names to see doc</text>
</g>
</g>
</svg>