diff --git a/.buildinfo b/.buildinfo
new file mode 100644
index 0000000000..d95675c49a
--- /dev/null
+++ b/.buildinfo
@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 2cca740605cef710b38d3bc90671a0b9
+tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/.nojekyll b/.nojekyll
new file mode 100644
index 0000000000..e69de29bb2
diff --git a/_images/pipeline.svg b/_images/pipeline.svg
new file mode 100644
index 0000000000..b9be3c3556
--- /dev/null
+++ b/_images/pipeline.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/_sources/casestudies.rst.txt b/_sources/casestudies.rst.txt
new file mode 100644
index 0000000000..abfa74e9f4
--- /dev/null
+++ b/_sources/casestudies.rst.txt
@@ -0,0 +1,308 @@
+.. _casestudies:
+
+Case Studies
+============
+
+Case Study #1: Proving invariants of actor systems
+--------------------------------------------------
+
+Actor system model
+~~~~~~~~~~~~~~~~~~
+
+Our model is loosely based on the modern definition of object-based actor systems,
+and attempts to provide an idiomatic Scala API in the style of the Akka actor library.
+
+In this framework, each actor is addressed by a reference, through which other actors
+can asynchronously send messages. Each actor has an associated behavior, which holds
+the state of the actor, if any, and determines
+
+a) the operations which will be performed upon receiving a message
+b) what is the next behavior to associate with its reference
+
+A behavior can thus be seen as a data type holding some immutable values representing
+the state, and a method which takes in a message, performs some computation which might
+involve sending messages to other actors, and finally returns a new behavior.
+
+State at the actor level is thus effectively handled in a functional way, by returning
+a new behavior which holds the updated state. An actor system maintains a collection
+of one-way channels (inboxes) between any two actors in the system.
+
+An inbox is an ordered list of messages awaiting delivery, the head of the list being
+the next message to deliver.
+
+The system drives the execution by non-deterministically
+picking a non-empty inbox, taking the first message of the list, and invoking the message
+handler of the behavior associated with the destination reference.
+
+It then collects the messages to send, and appends them to the appropriate inboxes,
+and update the destination actor’s behavior with the behavior returned by the message handler.
+
+Actor system implementation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Imports
+^^^^^^^
+
+.. code-block:: scala
+
+ import stainless.lang._
+ import stainless.collection._
+ import stainless.annotation._
+
+Message
+^^^^^^^
+
+In our framework, messages are modeled as constructors of the abstract class ``Msg``.
+
+.. code-block:: scala
+
+ abstract class Msg
+
+Actor reference
+^^^^^^^^^^^^^^^
+
+Each actor is associated with a persistent reference, modeled as instances of the case class ``ActorRef``.
+Each reference has a name, and an underlying Akka ``akka.actor.ActorRef``, marked as extern and pure (see Section :doc:`wrap` for more information about extern fields).
+
+.. code-block:: scala
+
+ case class ActorRef(
+ name: String,
+ @extern @pure
+ underlying: akka.actor.ActorRef
+ ) {
+
+ @inline
+ def !(msg: Msg)(implicit ctx: ActorContext): Unit = {
+ ctx.send(this, msg)
+ }
+ }
+
+Actor Context
+^^^^^^^^^^^^^
+
+When a message is delivered to an actor, the latter is provided with a context, which holds a reference to itself, and a mutable list of messages to send. We mark this list as ghost to avoid having to persist in memory the list of all messages sent through the context.
+
+.. code-block:: scala
+
+ case class ActorContext(
+ self: ActorRef,
+ @ghost
+ var toSend: List[(ActorRef, Msg)] = Nil()
+ ) {
+
+ def send(to: ActorRef, msg: Msg): Unit = {
+ toSend = (to, msg) :: toSend
+
+ sendUnderlying(to, msg)
+ }
+
+ @extern @pure
+ private def sendUnderlying(to: ActorRef, msg: Msg): Unit = {
+ to.underlying ! msg
+ }
+ }
+
+Behavior
+^^^^^^^^
+
+A behavior specifies both the current state of an actor, and how this one should process the next incoming message. In our framework, these are modeled as a subclass of the abstract class ``Behavior``, which defines a single abstract method ``processMsg``, to be overridden for each defined behavior.
+
+Using the provided ``ActorContext``, the implementation of the ``processMsg`` method can both access its own reference, and send messages. It is also required to return a new ``Behavior`` for handling subsequent messages.
+
+.. code-block:: scala
+
+ sealed abstract class Behavior {
+ def processMsg(msg: Msg)(implicit ctx: ActorContext): Behavior
+ }
+
+Actor System
+^^^^^^^^^^^^
+
+The state of the actor system at a given point in time is modeled as a case class, holding the behavior associated with each actor reference, and the list of in-flight messages between any two actors.
+
+It provides a ``step`` method which, whengiven two ``ActorRef``, will deliver the next message (if any) in the corresponding channel.
+
+Because the ``ActorSystem`` class is only used to model and prove properties about the underlying actor system, we mark the whole class as ghost in order to drop it from the resulting program.
+
+.. code-block:: scala
+
+ @ghost
+ case class ActorSystem(
+ behaviors: CMap[ActorRef, Behavior],
+ inboxes: CMap[(ActorRef, ActorRef), List[Msg]]
+ ) {
+
+ def step(from: ActorRef, to: ActorRef): ActorSystem = {
+ inboxes(from -> to) match {
+ case Nil() =>
+ this
+
+ case Cons(msg, msgs) =>
+ val (newBehavior, toSend) = deliverMessage(to, msg)
+
+ val newBehaviors = behaviors.updated(to, newBehavior)
+ val newInboxes = toSend.foldLeft(inboxes.updated(from -> to, msgs)) {
+ case (acc, (dest, m)) => acc.updated(to -> dest, m :: acc(to -> dest))
+ }
+
+ ActorSystem(newBehaviors, newInboxes)
+ }
+ }
+
+ private def deliverMessage(actor: ActorRef, msg: Msg): (Behavior, List[(ActorRef, Msg)]) = {
+ val behavior = behaviors(actor)
+
+ val ctx = ActorContext(actor, Nil())
+ val nextBehavior = behavior.processMsg(msg)(ctx)
+
+ (nextBehavior, ctx.toSend)
+ }
+ }
+
+Building a replicated counter
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: scala
+
+ @extern
+ def noSender = akka.actor.ActorRef.noSender
+
+ val Primary = ActorRef("primary", noSender)
+ val Backup = ActorRef("backup", noSender)
+
+ case object Inc extends Msg
+
+ case class Counter(value: BigInt) {
+ require(value >= 0)
+
+ def increment: Counter = Counter(value + 1)
+
+ def <=(that: Counter): Boolean = this.value <= that.value
+ }
+
+ case class PrimBehav(backup: ActorRef, counter: Counter) extends Behavior {
+ require(backup.name == "backup")
+
+ override
+ def processMsg(msg: Msg)(implicit ctx: ActorContext): Behavior = msg match {
+ case Inc =>
+ backup ! Inc
+ PrimBehav(backup, counter.increment)
+
+ case _ => this
+ }
+ }
+
+ case class BackBehav(counter: Counter) extends Behavior {
+
+ override
+ def processMsg(msg: Msg)(implicit ctx: ActorContext): Behavior = msg match {
+ case Inc =>
+ BackBehav(counter.increment)
+
+ case _ => this
+ }
+ }
+
+Proving preservation of an invariant
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After having defined an actor system with our framework, one might want to verify that this system preserves some invariant between each step of its execution. That is to say, given an invariant ``inv: ActorSystem → Boolean``, for any ``ActorSystem`` `s` and any two ``ActorRef`` `n` and `m`, if ``inv(s)`` holds, then ``inv(s.step(n, m))`` should hold as well. In other words:
+
+:math:`\forall s: \texttt{ActorSystem}, n, m: \texttt{ActorRef}. \texttt{inv}(s) \implies \texttt{inv}(s.\texttt{step}(n, m))`
+
+We note that, because we are essentially doing a proof by induction over execution steps here, one needs also to ensure the invariant holds for some initial system. We show these two properties below:
+
+.. code-block:: scala
+
+ @ghost
+ def invariant(s: ActorSystem): Boolean = {
+ s.inboxes(Primary -> Primary).isEmpty &&
+ s.inboxes(Backup -> Primary).isEmpty &&
+ s.inboxes(Backup -> Backup).isEmpty &&
+ s.inboxes(Primary -> Backup).forall(_ == Inc) && {
+ (s.behaviors(Primary), s.behaviors(Backup)) match {
+ case (PrimBehav(_, p), BackBehav(b)) =>
+ p.value == b.value + s.inboxes(Primary -> Backup).length
+
+ case _ => false
+ }
+ }
+ }
+
+ @ghost
+ def initialSystem = ActorSystem(
+ behaviors = CMap({
+ case `Primary` => PrimBehav(Counter(0))
+ case `Backup` => BackBehav(Counter(0))
+ }),
+ inboxes = CMap(_ => List())
+ )
+
+ @ghost
+ def initialInv = invariant(initialSystem).holds
+
+ @ghost
+ def validRef(ref: ActorRef): Boolean = ref == Primary || ref == Backup
+
+ @ghost
+ def theorem(s: ActorSystem, from: ActorRef, to: ActorRef): Boolean = {
+ require(invariant(s) && validRef(from) && validRef(to))
+ val newSystem = s.step(from, to)
+ invariant(newSystem)
+ }.holds
+
+Running the system with Akka
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: scala
+
+ @ignore
+ class ActorWrapper(initialBehavior: Behavior) extends akka.actor.Actor with akka.actor.ActorLogging {
+
+ private def handler(behavior: Behavior): PartialFunction[Any, Unit] = {
+ case msg: Msg =>
+ val me = ActorRef(context.self.path.name, context.self)
+ val ctx = ActorContext(me, Nil())
+ val newBehavior = behavior.processMsg(msg)(ctx)
+
+ log.info(s"Received: $msg, becoming $newBehavior")
+ context.become(handler(newBehavior), discardOld = true)
+ }
+
+ def receive = handler(initialBehavior)
+ }
+
+.. code-block:: scala
+
+ @ignore
+ def main(args: Array[String]): Unit = {
+ val initCounter = Counter(0)
+
+ val system = akka.actor.ActorSystem("Counter")
+
+ val backupRef = ActorRef(
+ "backup",
+ system.actorOf(
+ akka.actor.Props(new ActorWrapper(BackBehav(initCounter))),
+ name = "backup"
+ )
+ )
+
+ val primaryRef = ActorRef(
+ "primary",
+ system.actorOf(
+ akka.actor.Props(new ActorWrapper(PrimBehav(backupRef, initCounter))),
+ name = "primary"
+ )
+ )
+
+ implicit val ctx = ActorContext(primaryRef, Nil())
+
+ import system.dispatcher
+ import scala.concurrent.duration._
+ system.scheduler.schedule(500.millis, 1000.millis) {
+ primaryRef ! Inc
+ }
+ }
diff --git a/_sources/coq.rst.txt b/_sources/coq.rst.txt
new file mode 100644
index 0000000000..b899cfdd98
--- /dev/null
+++ b/_sources/coq.rst.txt
@@ -0,0 +1,69 @@
+.. _coq:
+
+Translation from Stainless to Coq
+=================================
+
+Initially based on a project done by `Bence Czipó
+`_, this translation is an early experimental
+stage.
+
+The `--coq` option of Stainless replaces the standard verification checker
+(which uses Inox) by a translation to Coq. Each function from the `*.scala` file
+is translated to a Coq file, and obligations corresponding to assertions,
+preconditions, and postconditions are solved using predefined tactics in Coq.
+
+.. _coq-requirements:
+
+Requirements
+------------
+
+- Coq 8.11.2
+- Coq Equations 1.2.2+8.11
+
+These can be installed using `opam
+`_ as explained in the `Equations
+README.md `_.
+
+.. _coq-option:
+
+Usage of the Coq option
+-----------------------
+
+First, clone the `Stainless repository
+`_. In the `slc-lib` directory, run
+`./configure` and `make`.
+
+Then, assuming the Stainless binary ``stainless-scalac`` is in your path, run:
+``stainless-scalac --coq File.scala`` on the file of your choice. As an example,
+consider the ``test`` function from the `Arith.scala
+`_
+file:
+
+.. code-block:: scala
+
+ def test(a: BigInt, b: BigInt, c: BigInt): BigInt = {
+ require(a > b && c > BigInt(0))
+ c + a
+ } ensuring( _ > c + b )
+
+Running ``stainless-scalac --coq frontends/benchmarks/coq/Arith.scala``
+generates the file ``tmp/test.v`` which contains the following Coq definition.
+
+.. code-block:: coq
+
+ Definition test (a: Z) (b: Z) (c: Z) (contractHyp4: (ifthenelse (Z.gtb a b) bool
+ (fun _ => Z.gtb c (0)%Z )
+ (fun _ => false ) = true)) : {x___1: Z | (Z.gtb x___1 (Z.add c b) = true)} :=
+ Z.add c a.
+
+ Fail Next Obligation.
+
+The ``coqc`` executable in run on the file, and the status is reported by
+Stainless. In the translation to Coq, the ``BigInt`` type is encoded as ``Z``.
+The precondition (``require``) is encoded as an extra argument ``contractHyp4``,
+and the postcondition is encoded as a refinement on the return type of `test`.
+Here, the obligation related to the postcondition is solved automatically thanks
+to the obligation tactic defined above in the ``tmp/test.v`` file. The statement
+``Fail Next Obligation.`` then succeeds because all obligations have been solved
+(any command in Coq can be prefixed with ``Fail``, and the resulting command
+succeeds when the original command fails).
diff --git a/_sources/equivalence.rst.txt b/_sources/equivalence.rst.txt
new file mode 100644
index 0000000000..37e2c1f5ab
--- /dev/null
+++ b/_sources/equivalence.rst.txt
@@ -0,0 +1,93 @@
+.. equivalence:
+
+Equivalence Checking
+====================
+
+Stainless can prove equivalence of recursive programs using automated functional induction. Additionaly, it can treat many programs at once, reusing the information obtained throughout the process, to reason about subsequent programs. `This paper
+`_ explains the underlying algorithms.
+
+To run the equivalence checker, use the ``--equivchk`` option of Stainless. The option ``--comparefuns`` specifies the names of candidate functions. The option ``--models`` specifies the names of reference functions.
+
+
+Example run
+-----------
+
+Consider the following three functions ``isSortedA`` (incorrect), ``isSortedB`` and ``isSortedC`` (both correct), that implement a check whether a given input list is sorted in a non-decreasing order:
+
+.. code-block:: scala
+
+ def isSortedA(l: List[Int]): Boolean = {
+ def leq(cur: Int, next: Int): Boolean = cur < next
+ def iter(l: List[Int]): Boolean =
+ if (l.isEmpty) true
+ else if (l.tail.isEmpty) true
+ else leq(l.head, l.tail.head) && iter(l.tail)
+ if (l.size < 2) true
+ else l.head <= l.tail.head && iter(l.tail)
+ }
+
+.. code-block:: scala
+
+ def isSortedB(l: List[Int]): Boolean = {
+ if (l.isEmpty)
+ true
+ else if (!l.tail.isEmpty && l.head > l.tail.head)
+ false
+ else
+ isSortedB(l.tail)
+ }
+
+.. code-block:: scala
+
+ def isSortedC(l: List[Int]): Boolean = {
+ def chk(l: List[Int], p: Int, a: Boolean): Boolean = {
+ if (l.isEmpty) a
+ else if (l.head < p) false
+ else chk(l.tail, l.head, a)
+ }
+ if (l.isEmpty) true
+ else chk(l, l.head, true)
+ }
+
+And the following reference function ``isSortedR``:
+
+.. code-block:: scala
+
+ def isSortedR(l: List[Int]): Boolean = {
+ def loop(p: Int, l: List[Int]): Boolean = l match {
+ case Nil() => true
+ case Cons(x, xs) if (p <= x) => loop(x, xs)
+ case _ => false
+ }
+ if (l.isEmpty) true
+ else loop(l.head, l.tail)
+ }
+
+The following command invokes the equivalence checking (``isSortedA``, ``isSortedB``, ``isSortedC`` and ``isSortedR`` are defined in ``frontends/benchmarks/equivalence/isSorted/isSorted.scala``):
+
+``stainless frontends/benchmarks/equivalence/isSorted/isSorted.scala --equivchk=true --comparefuns=isSortedA,isSortedB,isSortedC --models=isSortedR --timeout=3``
+
+Stainless automatically generates all the equivalence lemmas and reports resulting equivalence clusters. This is done by checking for equivalence of each function from the ``--comparefuns`` list against the model functions from the ``--models`` list, until the proof of equivalence or a counterexample is found for one of the models.
+
+The output of equivalence checking is a classification of candidate functions into the following categories:
+
+ - ``Wrong``, if the signature is wrong;
+ - ``Correct``, if there is a reference program provably equivalent to this program;
+ - ``Incorrect``, if there is a counterexample that disproves the equivalence;
+ - ``Unknown``, when there is neither a proof nor a counterexample of equivalence.
+
+For our example run, we get the following output:
+
+.. code-block:: text
+
+ [ Info ] Printing equivalence checking results:
+ [ Info ] List of functions that are equivalent to model IsSorted.isSortedB: IsSorted.isSortedC
+ [ Info ] List of functions that are equivalent to model IsSorted.isSortedR: IsSorted.isSortedB
+ [ Info ] List of erroneous functions: IsSorted.isSortedA
+ [ Info ] List of timed-out functions:
+ [ Info ] List of wrong functions:
+ [ Info ] Printing the final state:
+ [ Info ] Path for the function IsSorted.isSortedB: IsSorted.isSortedR
+ [ Info ] Path for the function IsSorted.isSortedC: IsSorted.isSortedB, IsSorted.isSortedR
+ [ Info ] Counterexample for the function IsSorted.isSortedA:
+ [ Info ] l -> Cons[Int](-1357890535, Cons[Int](-1089455080, Cons[Int](-1089455080, Nil[Int]())))
\ No newline at end of file
diff --git a/_sources/faq.rst.txt b/_sources/faq.rst.txt
new file mode 100644
index 0000000000..c80f0acb18
--- /dev/null
+++ b/_sources/faq.rst.txt
@@ -0,0 +1,98 @@
+.. _faq:
+
+FAQ: (Frequently) Asked Questions
+=================================
+
+If you have a question, you may also post it at http://stackoverflow.com
+(try `searching for the leon tag `_
+or `the stainless tag `_)
+or contact one of the authors of this documentation.
+
+Below we collect answers to some questions that came up.
+
+How does Stainless compare to other verification tools?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+One can compare Stainless to proof assistants such as
+`Isabelle/HOL `_,
+`Coq `_,
+`Lean `_,
+`HOL4 `_, or
+`ACL2 `_ in terms of the complexity of some of the program properties it can prove, though it was originally conceived more as a program verifier, such as
+`Dafny `_ or
+`Viper `_.
+Stainless can be more automated when finding proofs of programs compared to proof assistants, and can also report counter-examples for invalid properties in many non-trivial cases, see counter-examples for bugs in benchmarks such as
+`ConcRope.scala `_,
+`ListOperations.scala `_,
+`Mean.scala `_,
+`PropositionalLogic.scala `_,
+`AssociativityProperties.scala `_,
+`InsertionSort.scala `_,
+`more example reports `_, or check some of our
+`regression tests `_.
+On the other hand, proof assistants are much better at formalizing mathematics than Stainless, especially when it comes to libraries of formalized mathematics knowledge.
+
+How does Stainless compare to fuzzing tools?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Formal software verification finds proofs that programs work under all scenarios of interest. Formal verification tools help developers construct such proofs, automatically searching for proofs using theorem proving and constraint solving (using, e.g. SMT solvers), and static analysis to discover program invariants. When it succeeds, formal verification is guaranteed to identify all software errors, including, for example, security vulnerabilities or cases when the computation produces a wrong numerical or symbolic result. Because it involves building proofs, this approach may require knowledge of proofs by induction and substitution of equals for equals, typically covered in computer science undergraduate university education. The best approach to obtain formally verified software is to perform formal verification while software is developed. If we try to apply formal verification after software is already written, we should be prepared to invest at least the amount of effort needed to rewrite it.
+
+Testing can establish the presence of errors, but not their absence. Basic forms of testing can be easy to deploy, because running a program on a given input is a minimum requirement for software, but such testing is extremely limited. Suppose that we wish to test whether a program running on a smartphone performs multiplication of two machine numbers correctly. If we could check one test per *nanosecond*, we would still need many billions of years to enumerate all cases! This also illustrates how minuscule of a region of space around a given test a fuzzer can ever explore, despite an amazing speed at which some these fuzzing tools work. Formal software verification can cover all these cases with a single proof because it uses algebraic properties that are independent of the size of the data that software manipulates.
+
+To avoid enumeration, advanced testing methods such as symbolic execution embrace constraint solvers originally developed for formal verification. These techniques reduce to formal verification when programs have no loops or recursion; otherwise they end up sampling a small fraction of program executions, so they do not result in a proof. To cover more than just absence of crashes and vulnerabilities, testing also requires insights into the purpose of software, the environment in which the software needs to execute and the expected outputs for given inputs.
+
+Does Stainless use SMT solvers?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Stainless uses SMT solvers such as z3, CVC and Princess. The component that encodes formulas with executable higher-order functions into these solvers is Inox. Inox is designed to emit quantifier-free queries for these solvers, which increases its ability to generate counter-examples. The use of SMT solvers allows Stainless to achieve notable automation in reasoning about, for example, equality, case analysis, bitvectors, and algebraic data types.
+
+
+What are the conditions required for Stainless to be applied to industry software?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is best to deploy formal verification when starting to develop software. In this way, software and its specifications are developed hand in hand, much like one can define a class hierarchy and other types during the process of writing an object-oriented program. It is also possible to focus on one part of an existing software system and rewrite it in Stainless; such efforts have been shown to work in industry for software components in Scala, Java, and C. Software that has well-defined modular structure with clear responsibility of different modules is a good candidate for verification because one can expect that specifications at module boundaries will be non-controversial. In terms of developer skills, good knowledge of discrete mathematics, such as proofs by induction and algebra will make developers more effective at verification.
+
+Can I use Stainless with Java?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Scala has excellent interoperability with Java, so external libraries can be used to build application where some parts are verified using Stainless. Stainless uses Scala syntax trees and does not support verification of Java itself. Whereas functional Scala works as a both specification and implementation language, Java does not appear to be a good language for specifications, so much that Java verification tools in the past introduced their own logical notation that developers then must learn in addition to Java.
+
+Can I use Stainless with Rust?
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Even though we had somewhat successful experiments translating Rust code into Stainless, we believe that, in the long term, it is more productive to use Scala as the starting point and generate low-level code. We are working on making this more practical in the future.
+
+Proving properties of size
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+I have defined a size function on my algebraic data type.
+
+.. code-block:: scala
+
+ sealed abstract class List
+ case class Cons(head: Int, tail: List) extends List
+ case object Nil extends List
+ def size(l: List) : Int = (l match {
+ case Nil => 0
+ case Cons(_, t) => 1 + size(t)
+ }) ensuring(_ >= 0)
+
+Stainless neither proves nor gives a counterexample. Why?
+
+**Answer:** You should consider using `BigInt`, which
+denotes unbounded mathematical integers, instead of `Int`,
+which denotes 32-bit integers. If you replace `Int` with
+`BigInt` in the result type of `size`, the function should
+verify. Note that algebraic data types can be arbitrarily
+large, so, if the input list had the size `Int.MaxValue + 1`
+(which is 2^32) then the addition `1 + size(t)` would wrap
+around and produce `Int.MinValue` (that is, -2^31), so the
+`ensuring` clause would not hold.
+
+Compiling Stainless programs to bytecode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you don't use special constructs such as ``choose`` or unbounded ``forall``, you
+should be able to compile Stainless programs to `.class` using `scalac` and
+execute them directly on the JVM, or integrate them as part as other
+Scala-based projects. See Section ":ref:`running-code`".
diff --git a/_sources/genc.rst.txt b/_sources/genc.rst.txt
new file mode 100644
index 0000000000..584a4928a5
--- /dev/null
+++ b/_sources/genc.rst.txt
@@ -0,0 +1,465 @@
+.. _genc:
+
+Generating C Code
+=================
+
+Stainless can generate from Scala code an equivalent and safe C99 code. Using the verification, repair and
+synthesis features of Stainless this conversion can be made safely. Additionally, the produced code can be
+compiled with any standard-compliant C99 compiler to target the desired hardware architecture
+without extra dependencies. The initial description of GenC, which has evolved since then, can be found in `Extending Safe C Support In Leon
+`_.
+Furthermore, this Master Thesis Report explains how to achieve compliance under the `MISRA C
+`_ guidelines.
+
+To convert a Scala program, please use the ``--genc`` option of Stainless.
+
+The option ``--genc-output=file`` specifies the file name for GenC output (default: ``stainless.c``).
+
+
+.. NOTE::
+ Currently the memory model is limited to stack allocation and global state. Hence, no dynamic allocation
+ is done using ``malloc`` function family.
+
+
+Requirements
+------------
+
+The following is required from the Scala program fed to GenC:
+
+ - Functions compiled to C, and the types they use,
+ should be exclusively in the set of features described below, with the
+ exceptions of the (ghost) code used for verification conditions;
+
+ - The program should be successfully verified with the ``--strict-arithmetic`` (enabled by default)
+ flag to ensure that arithmetic operations, array accesses, function
+ preconditions and so on, are safely converted into C code.
+
+
+The generated C code should be compiled with a C99-compliant compiler that
+satisfies these extra conditions:
+
+ - ``CHAR_BITS`` is defined to be 8;
+
+ - The ``int8_t``, ``int16_t``, ``int32_t``, ``int64_t`` and ``uint8_t``, ``uint16_t``, ``uint32_t``, ``uint64_t`` types are available (see :doc:`Pure Scala ` for description);
+
+ - Casting from unsigned to signed integer, and vice-versa, is not well supported at the moment.
+
+
+Export
+------
+
+Functions and classes can be marked with ``@cCode.export`` (``import stainless.annotation._``),
+which affects GenC compilation in several ways.
+First, the names of these functions and classes will not get mangled when generating the C code.
+Second, the signatures of the functions, and the type definitions corresponding to exported classes,
+will go into the header file (by default ``stainless.h``).
+Finally, preconditions of exported functions (which are meant to be called from external C code),
+are transformed into runtime assertions.
+
+Supported Features
+------------------
+
+The supported subset of Scala includes part of the core languages features, as well as some
+imperative features, while ensuring the same expression execution order in both
+languages.
+
+
+Types
+*****
+
+The following raw types and their corresponding literals are supported:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Scala
+ - C99
+ * - ``Unit``
+ - ``void``
+ * - ``Boolean``
+ - ``bool``
+ * - ``Byte`` and ``Int8`` (8-bit integer)
+ - ``int8_t``
+ * - ``Short`` and ``Int16`` (16-bit integer)
+ - ``int16_t``
+ * - ``Int`` and ``Int32`` (32-bit integer)
+ - ``int32_t``
+ * - ``Long`` and ``Int64`` (64-bit integer)
+ - ``int64_t``
+ * - ``UInt8`` (8-bit unsigned integer)
+ - ``uint8_t``
+ * - ``UInt16`` (16-bit integer)
+ - ``uint16_t``
+ * - ``UInt32`` (32-bit integer)
+ - ``uint32_t``
+ * - ``UInt64`` (64-bit integer)
+ - ``uint64_t``
+
+Additionally, GenC has partial support for character and string literals made
+of ASCII characters only but it has no API to manipulate strings at the moment:
+``Char`` is mapped to ``char`` and ``String`` is mapped to ``char*``.
+
+Tuples
+^^^^^^
+
+Using ``TupleN[T1, ..., TN]`` results in the creation of a C structure with the
+same fields and matching types for every combination of any supported type
+``T1, ..., TN``. The name of the generated structure will be unique and reflect
+the sequence of types.
+
+
+Arrays
+^^^^^^
+
+Arrays are compiled by GenC into C structs that also store the length of the array.
+For ``Array[Int]`` we get:
+
+.. code-block:: C
+
+ typedef struct {
+ int32_t* data;
+ int32_t length;
+ } array_int32;
+
+.. NOTE::
+
+ Arrays live on the stack and therefore cannot be returned by functions. This limitation is
+ extended to other types having an array as field. In some cases, it is acceptable to use the
+ ``@cCode.inline`` annotation from Stainless's library to workaround this limitation.
+
+For case classes containing arrays whose length is known at compile time, we avoid
+using a ``struct`` wrapper for the array, and instead directly inline the array
+in the ``struct`` of the case class. We trigger this optimized transformation
+when the array length is specified in the case class invariant (with ``require``)
+as a conjunct. The left-hand-side needs to be ``a.length`` where ``a`` is the
+array, and the right-hand-side needs to be a constant (or evaluate to a constant
+at compile time).
+
+See below for a case class with a fixed length array and its transformation in C:
+
+.. code-block:: scala
+
+ val CONSTANT1: UInt16 = 5
+ val CONSTANT2: UInt16 = 12
+ val CONSTANT3: UInt16 = CONSTANT1 + CONSTANT2
+
+ @cCode.export
+ case class W(x: Int, a: Array[Int], y: Int) {
+ require(
+ a.length == CONSTANT3.toInt &&
+ 0 <= x && x <= 1000 &&
+ 0 <= y && y <= 1000
+ )
+ }
+
+.. code-block:: C
+
+ typedef struct {
+ int32_t x;
+ int32_t a[17];
+ int32_t y;
+ } W;
+
+Classes
+^^^^^^^
+
+The support for classes is restricted to non-recursive ones so that instances
+of such data-types live on the stack. The following language features are available:
+
+ - ``case class`` with mutable ``var`` fields;
+
+ - generics:
+
+ + similarly to ``Array[T]`` or tuples, each combination of type parameters
+ is mapped to a specific C structure;
+
+ - inheritance:
+
+ + when all leaf classes have no fields, the class hierarchy is mapped to a
+ C enumeration,
+
+ + otherwise, a tagged-union is used to represent the class hierarchy in C;
+
+ - external types:
+
+ + see ``@cCode.typedef`` below.
+
+
+Functions
+*********
+
+Functions with access to the variables in their respective scopes. The
+following language features are available:
+
+ - top level, nested or member functions:
+
+ + both ``val`` and ``var`` are supported for local variable with the limitations imposed by
+ the imperative phases of Stainless
+
+ - generics:
+
+ + each combination of type parameters generates a different, specialised C function;
+
+ - overloading:
+
+ + the Scala compiler is responsible for identifying the correct function at each call site;
+
+ - higher-order functions:
+
+ + named functions that do not capture their environment can be used as value;
+
+ - external functions:
+
+ + see ``@cCode.function`` below;
+
+Since strings of characters are currently not (fully) available, in order to generate an executable
+program, one has to define a main function without any argument, whose return type can be ``Int``
+or ``Unit``:
+
+.. code-block:: scala
+
+ @cCode.export
+ def main(): Unit = {
+ // main code goes here
+ }
+
+
+Constructs
+**********
+
+The idiomatic ``if`` statements such as ``val b = if (x >= 0) true else false`` are converted into
+a sequence of equivalent statements.
+
+Imperative ``while`` loops are also supported.
+
+*Pattern matching* is supported, with the exception of the *Unapply
+Patterns*, as long as it is exempt of side effect.
+
+Assertions, invariant, pre- and post-conditions are not translated into C99 and are simply ignored.
+
+
+Operators
+*********
+
+The following operators are supported:
+
+.. list-table::
+ :header-rows: 1
+
+ * - Category
+ - Operators
+ * - Boolean operators
+ - ``&&``, ``||``, ``!``, ``!=``, ``==``
+ * - Comparision operators over integers
+ - ``<``, ``<=``, ``==``, ``!=``, ``>=``, ``>``
+ * - Comparision operators over instances of classes
+ - ``==``, ``!=``
+ * - Arithmetic operators over integers
+ - ``+``, ``-`` (unary & binary), ``*``, ``/``, ``%``
+ * - Bitwise operators over integers
+ - ``&``, ``|``, ``^``, ``~``, ``<<``, ``>>>``
+
+
+Global State
+------------
+
+At the moment, Stainless does not support global mutable variables declared in objects.
+It is however possible to simulate global state by using classes marked with ``@cCode.global``,
+as shown in the `Global.scala
+`_
+example:
+
+.. code-block:: scala
+
+ @cCode.global
+ case class GlobalState(
+ val data: Array[Int] = Array.fill(100)(0),
+ var stable: Boolean = true,
+ var x: Int = 5,
+ var y: Int = 7,
+ ) {
+ require(
+ data.length == 100 && (
+ !stable || (
+ 0 <= x && x <= 100 &&
+ 0 <= y && y <= 100 &&
+ x + y == 12
+ )
+ )
+ )
+ }
+
+.. note::
+
+ In classes annotated with ``@cCode.global``, only arrays with a fixed length are
+ allowed. Please check the paragraph about arrays to learn how to specify the array length.
+
+This annotation triggers some checks to make sure that indeed the ``GlobalState`` class
+(the name of the class can be changed, and there can be multiple such classes) is used as a global
+state:
+
+* Functions can take as argument at most one instance per each global class such as ``GlobalState``.
+* There can be at most one instance created for each global class such as ``GlobalState``
+ (in a function that doesn't already take an instance of that class as argument).
+* A ``GlobalState`` instance can only be used for reads and assignments (e.g. it cannot be let bound, except for the declaration mentioned above).
+* The only global state that can be passed to other functions is the one we create or the one we received as a function argument.
+
+These checks ensure that the fields of ``GlobalState`` can be compiled as global variables in ``C``.
+Consider the ``move`` function from the `Global.scala
+`_
+example:
+
+.. code-block:: scala
+
+ def move()(implicit state: GlobalState): Unit = {
+ require(state.stable && state.y > 0)
+ state.stable = false
+ state.x += 1
+ state.y -= 1
+ state.data(state.y) = 1
+ state.stable = true
+ if (state.y > 0) move()
+ }.ensuring(_ => state.stable)
+
+After compilation to C, we get the following function, with global declarations
+``stable``, ``x``, ``y``, and ``data``.
+
+.. code-block:: C
+
+ int32_t data[100] = { 0 };
+ bool stable = true;
+ int32_t x = 5;
+ int32_t y = 7;
+
+ void move() {
+ stable = false;
+ x = x + 1;
+ y = y - 1;
+ data[y] = 1;
+ stable = true;
+ if (y > 0) {
+ move();
+ }
+ }
+
+Note that the initial values for the global variables correspond to the default values given
+in the Stainless class declaration (default values are mandatory when using the ``@cCode.global``
+annotation). When creating a global state instance (the only one), we do not pass arguments, to
+make sure that the instance is created using the default values:
+
+.. code-block:: scala
+
+ @cCode.export
+ def main() {
+ implicit val gs = GlobalState()
+ StdOut.print(gs.x)
+ StdOut.print(gs.y)
+ move()
+ StdOut.print(gs.data(6))
+ StdOut.print(gs.data(7))
+ StdOut.print(gs.x)
+ StdOut.println(gs.y)
+ }
+
+Stainless supports two variants of the ``@cCode.global`` annotation, namely ``@cCode.globalUninitialized``
+and ``@cCode.globalExternal``. The first one generates global declarations without initial
+values. These global variables are thus initialized according to C semantics, and there can be
+a mismatch between the global state instance created by the user, and the initial values in C.
+The second one hides the global declarations, which can be useful when interacting with C code
+that declares global variables outside of the Stainless program.
+
+
+Custom Conversion
+-----------------
+
+When it comes to function using system calls, such as I/Os, no automated conversion is possible. In
+those situations the user can define his own implementation for functions, add manual conversion
+from Scala types to C types or even drop some functions and types from the translation, with
+``@cCode.function``, ``@cCode.typedef`` and ``@cCode.drop`` annotations from the package
+``stainless.annotation``. Their usage is described below.
+
+
+Custom Function Implementation
+******************************
+
+In order to circumvent some current limitations of GenC, one can use ``@cCode.function(code,
+includes)`` to define the corresponding implementation of any top-level function or method, usually
+accompanied by ``@extern``. Its usage is as follows:
+
+ * For convenience, the C implementation generated by ``code`` is represented using a String and
+ not an Abstract Syntax Tree. The user is responsible for the correctness of the provided C99
+ code. Because GenC might rename the function, e.g. to deal with overloading, the special
+ ``__FUNCTION__`` token should be used instead of the original name. Furthermore, the parameters
+ and return type should match the signature automatically generated by GenC.
+
+ * The optional parameter ``includes`` can hold a colon separated list of required C99 include
+ header files.
+
+Here is a typical example:
+
+.. code-block:: scala
+
+ // Print a 32-bit integer using the *correct*
+ // format for printf in C99
+ @cCode.function(
+ code = """
+ | void __FUNCTION__(int32_t x) {
+ | printf("%"PRIi32, x);
+ | }
+ """,
+ includes = "inttypes.h:stdio.h"
+ )
+ def myprint(x: Int): Unit = {
+ print(x)
+ }
+
+
+Custom Type Translation
+***********************
+
+When a whole type need to be represented using a special C type, the ``@cCode.typedef(alias,
+include)`` annotation can be used. Here the ``include`` parameter is also optional, however it can
+only refer to one header, as it is not expected to have a type defined in several headers. The
+``alias`` string must represent an existing and valid type.
+
+Using an aliasing from ``S`` to ``C`` implies that every function that accept a ``S`` in the input
+program must accept a ``C`` in the generated C code. Usually, using this annotation implicates
+manually defining the implementation of functions using this type with ``@cCode.function``.
+
+Here is an example:
+
+.. code-block:: scala
+
+ @cCode.typedef(alias = "FILE*", include = "stdio.h")
+ case class MyFile( ...
+
+
+Ignore Function or Type
+***********************
+
+It is also possible to skip the translation of some functions or types that are only used as
+implementation details in proofs, for example, using the ``@cCode.drop()`` annotation.
+
+
+API For Safe Low Level Programs
+-------------------------------
+
+In this section we describe the APIs that can be used to make the bridge between some Scala
+programming facilities and their low level, equivalent, C features.
+
+
+I/Os
+****
+
+Similarly to Scala's ``scala.io.StdIn`` and ``scala.io.StdOut``, Stainless provides ``stainless.io.StdIn`` and
+``stainless.io.StdOut``. These two APIs are provided with equivalent C code for easy translation with
+GenC, but are also shaped to allow users to write proofs in a non-deterministic environment.
+
+
+Furthermore, Stainless provides ``stainless.io.FileInputStream`` to read data and
+``stainless.io.FileOutputStream`` to write data to a file with a C99 compatible API.
+
+.. NOTE::
+
+ It is important that you close the stream after it was created or your C
+ application might leak resources.
diff --git a/_sources/gettingstarted.rst.txt b/_sources/gettingstarted.rst.txt
new file mode 100644
index 0000000000..7758004303
--- /dev/null
+++ b/_sources/gettingstarted.rst.txt
@@ -0,0 +1,105 @@
+.. _gettingstarted:
+
+Verifying and Compiling Examples
+================================
+
+Verifying Examples
+------------------
+
+Stainless is currently available as either:
+
+* a command line tool, which exposes most of the functionality, available as a ZIP file (recommended) or via Docker.
+* via an SBT plugin.
+
+See the :doc:`installation documentation ` for more information.
+
+It is henceforth assumed that there exists a ``stainless`` script in in your ``PATH``.
+
+To see the main options, use
+
+.. code-block:: bash
+
+ $ stainless --help
+
+in your command line shell.
+You may also wish to consult the :doc:`available command-line options `.
+
+You can try some of the examples from ``frontends/benchmarks``
+distributed with Stainless:
+
+.. code-block:: bash
+
+ $ stainless --solvers=smt-cvc5 frontends/benchmarks/verification/invalid/InsertionSort.scala
+
+and get something like this (some output cropped)
+
+.. code-block:: text
+
+ [ Info ] Starting verification...
+ [ Info ] Verified: 3 / 19
+ [Warning ] - Result for 'postcondition' VC for buggySortedIns @37:38:
+ [Warning ] l.isInstanceOf[Nil] || !(l.head <= e) || {
+ [Warning ] val res: List = Cons(l.head, buggySortedIns(e, l.tail))
+ [Warning ] assume({
+ [Warning ] val e: List = Cons(l.head, buggySortedIns(e, l.tail))
+ [Warning ] true
+ [Warning ] })
+ [Warning ] contents(res) == contents(l) ++ Set(e) && isSorted(res) && size(res) == size(l) + BigInt("1")
+ [Warning ] }
+ [Warning ] frontends/benchmarks/verification/invalid/InsertionSort.scala:37:38: => INVALID
+ case Cons(x,xs) => if (x <= e) Cons(x,buggySortedIns(e, xs)) else Cons(e, l)
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ [Warning ] Found counter-example:
+ [Warning ] l: List -> Cons(-770374653, Cons(-771685886, Nil()))
+ [Warning ] e: Int -> 1376322050
+ [ Info ] Verified: 3 / 19
+ [Warning ] - Result for 'postcondition' VC for buggySortedIns @37:73:
+ [Warning ] l.isInstanceOf[Nil] || l.head <= e || {
+ [Warning ] val res: List = Cons(e, l)
+ [Warning ] contents(res) == contents(l) ++ Set(e) && isSorted(res) && size(res) == size(l) + BigInt("1")
+ [Warning ] }
+ [Warning ] frontends/benchmarks/verification/invalid/InsertionSort.scala:37:73: => INVALID
+ case Cons(x,xs) => if (x <= e) Cons(x,buggySortedIns(e, xs)) else Cons(e, l)
+ ^^^^^^^^^^
+ [Warning ] Found counter-example:
+ [Warning ] l: List -> Cons(691483681, Cons(512, Nil()))
+ [Warning ] e: Int -> -1263292350
+ [ Info ] Verified: 17 / 19
+ [ Info ] ┌───────────────────┐
+ [ Info ] ╔═╡ stainless summary ╞══════════════════════════════════════════════════════════════════════════════════════════════╗
+ [ Info ] ║ └───────────────────┘ ║
+ [ Info ] ║ InsertionSort.scala:33:7: buggySortedIns non-negative measure valid U:smt-z3 0,1 ║
+ [ Info ] ║ InsertionSort.scala:35:5: buggySortedIns body assertion: match exhaustiveness trivial 0,0 ║
+ [ Info ] ║ InsertionSort.scala:35:5: buggySortedIns postcondition trivial 0,0 ║
+ [ Info ] ║ InsertionSort.scala:36:21: buggySortedIns postcondition valid U:smt-z3 0,1 ║
+ [ Info ] ║ InsertionSort.scala:37:38: buggySortedIns postcondition invalid U:smt-z3 0,3 ║
+ [ Info ] ║ InsertionSort.scala:37:45: buggySortedIns measure decreases valid U:smt-z3 0,1 ║
+ [ Info ] ║ InsertionSort.scala:37:73: buggySortedIns postcondition invalid U:smt-z3 0,1 ║
+ [ Info ] ║ InsertionSort.scala:20:7: contents non-negative measure valid from cache 0,0 ║
+ [ Info ] ║ InsertionSort.scala:20:37: contents body assertion: match exhaustiveness trivial 0,0 ║
+ [ Info ] ║ InsertionSort.scala:22:24: contents measure decreases valid U:smt-z3 0,0 ║
+ [ Info ] ║ InsertionSort.scala:25:7: isSorted non-negative measure valid U:smt-z3 0,0 ║
+ [ Info ] ║ InsertionSort.scala:25:36: isSorted body assertion: match exhaustiveness trivial 0,0 ║
+ [ Info ] ║ InsertionSort.scala:28:44: isSorted measure decreases valid U:smt-z3 0,1 ║
+ [ Info ] ║ InsertionSort.scala:15:7: size non-negative measure valid from cache 0,0 ║
+ [ Info ] ║ InsertionSort.scala:15:34: size body assertion: match exhaustiveness trivial 0,0 ║
+ [ Info ] ║ InsertionSort.scala:15:34: size postcondition trivial 0,0 ║
+ [ Info ] ║ InsertionSort.scala:16:19: size postcondition valid U:smt-z3 0,0 ║
+ [ Info ] ║ InsertionSort.scala:17:25: size postcondition valid U:smt-z3 0,0 ║
+ [ Info ] ║ InsertionSort.scala:17:29: size measure decreases valid from cache 0,0 ║
+ [ Info ] ╟┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄╢
+ [ Info ] ║ total: 19 valid: 17 (3 from cache, 6 trivial) invalid: 2 unknown: 0 time: 0,81 ║
+ [ Info ] ╚════════════════════════════════════════════════════════════════════════════════════════════════════════════════════╝
+ [ Info ] Verification pipeline summary:
+ [ Info ] cache, anti-aliasing, smt-z3
+ [ Info ] Shutting down executor service.
+
+
+Compiling and Executing Examples
+--------------------------------
+
+Scala code written with Stainless library dependencies can be compiled and run using the
+library sources available on the `Stainless github repository `_,
+along with the scala compiler and runner script.
+
+See the :ref:`installation documentation ` for more information.
\ No newline at end of file
diff --git a/_sources/ghost.rst.txt b/_sources/ghost.rst.txt
new file mode 100644
index 0000000000..220d0cdecc
--- /dev/null
+++ b/_sources/ghost.rst.txt
@@ -0,0 +1,153 @@
+.. _ghost:
+
+Ghost Context
+=============
+
+Introduction
+------------
+
+When verifying code, one often needs to introduce lemmas, auxiliary functions,
+additional fields and parameters, and contracts, whose only function is to specify
+and prove that some properties are satisfied by the program.
+
+.. code-block:: scala
+
+ import stainless.lang._
+ import stainless.lang.collection._
+ import stainless.lang.annotation._
+
+ def isSorted(list: List[BigInt]): Boolean = list match {
+ case Nil() => true
+ case Cons(_, Nil()) => true
+ case Cons(x1, Cons(x2, _)) if x1 > x2 => false
+ case Cons(_, xs) => isSorted(xs)
+ }
+
+ def sort(list: List[BigInt]): List[BigInt] = {
+ /* ... */
+ } ensuring { res =>
+ res.contents == list.contents &&
+ isSorted(res) &&
+ res.size == l.size
+ }
+
+One can alleviate this issue by adding the following import:
+
+
+.. code-block:: scala
+
+ import stainless.lang.StaticChecks._
+
+
+Ghost annotation
+----------------
+
+Correctness check
+-----------------
+
+As part of the verification pipeline, Stainless will check that it never
+encounters a *ghost expression* outside of a *ghost context*. Should
+the check fail, verification will fail and compilation will be aborted.
+
+A *ghost expression* is any of:
+
+- Call to a ghost method
+- Selection of a ghost field
+- Instantiation of a ghost class
+- Reference to a ghost variable
+
+A *ghost context* as any of:
+
+- Body of a ghost method
+- Argument to a ghost parameter (method or class constructor)
+- Assignment to a ghost variable
+- Anywhere where a value of type ``Unit`` is expected
+
+Ghost expression elimination
+----------------------------
+
+If the correctness check described in the previous section succeeds, the sbt plugin
+will then proceed to eliminate ghost methods and expressions from the programs.
+
+Case study
+----------
+
+.. code-block:: scala
+
+ import stainless.lang._
+ import stainless.lang.StaticChecks._
+ import stainless.collection._
+ import stainless.annotation._
+
+ import java.util.ArrayDeque
+
+ object MessageQueue {
+
+ case class MsgQueue[A](
+ @extern @pure
+ queue: ArrayDeque[A],
+ @ghost
+ var msgs: List[A]
+ ) {
+ def put(msg: A): Unit = {
+
+ msgs = msg :: msgs
+ _put(msg)
+ }
+
+ @extern @pure
+ private def _put(msg: A): Unit = {
+ queue.addFirst(msg)
+ }
+
+ def take(): Option[A] = {
+ val result = _take()
+ msgs = msgs.tailOption.getOrElse(Nil())
+ result
+ } ensuring { res =>
+ res == old(this).msgs.headOption
+ }
+
+ @extern @pure
+ private def _take(): Option[A] = {
+ Option(queue.pollFirst())
+ } ensuring { res =>
+ res == msgs.headOption
+ }
+
+ @extern @pure
+ def isEmpty: Boolean = {
+ queue.size() == 0
+ } ensuring { res =>
+ res == msgs.isEmpty
+ }
+ }
+
+ object MsgQueue {
+ @extern @pure
+ def empty[A]: MsgQueue[A] = {
+ MsgQueue(new ArrayDeque(), Nil())
+ } ensuring { res =>
+ res.isEmpty && res.msgs.isEmpty
+ }
+ }
+
+ def test = {
+ val queue = MsgQueue.empty[String]
+
+ queue.put("World")
+ queue.put("Hello")
+
+ assert(!queue.isEmpty)
+
+ val a = queue.take()
+ assert(a == Some("Hello"))
+
+ val b = queue.take()
+ assert(b == Some("World"))
+ assert(queue.isEmpty)
+
+ val c = queue.take()
+ assert(!c.isDefined)
+ }
+ }
diff --git a/_sources/imperative.rst.txt b/_sources/imperative.rst.txt
new file mode 100644
index 0000000000..819ea74877
--- /dev/null
+++ b/_sources/imperative.rst.txt
@@ -0,0 +1,545 @@
+.. _imperative:
+
+Imperative
+==========
+
+To complement the core :doc:`Pure Scala ` language, Stainless
+proposes a few extensions to that core language.
+
+On the technical side, these extensions do not have specific treatment in the
+back-end of Stainless. Instead, they are desugared into :doc:`Pure Scala `
+constructs during a preprocessing phase in the Stainless front-end.
+
+These transformations are partly documented in the `EPFL PhD thesis of Régis Blanc `_.
+
+Imperative Code
+---------------
+
+Stainless lets you introduce local variables in functions, and use Scala assignments
+syntax.
+
+.. code-block:: scala
+
+ def foo(x: Int): Int = {
+ var a = x
+ var b = 42
+ a = a + b
+ b = a
+ b
+ }
+
+The above example illustrates three new features introduced by imperative support:
+
+1. Declaring a variable in a local scope
+
+2. Blocks of expressions
+
+3. Assignments
+
+You can use Scala variables with a few restrictions. The variables can only be
+declared and used locally, no variable declaration outside of a function body.
+There is also support for variables in case classes constructors. Imperative support
+introduces the possibility to use sequences of expressions (blocks) -- a
+feature not available in :doc:`Pure Scala `, where your only
+option is a sequence of ``val`` which essentially introduce nested ``let``
+declarations.
+
+
+While loops
+-----------
+
+You can use the ``while`` keyword. While loops usually combine the ability to
+declare variables and make a sequence of assignments in order to compute
+something useful:
+
+.. code-block:: scala
+
+ def foo(x: Int): Int = {
+ var res = 0
+ var i = 0
+ while(i < 10) {
+ res = res + i
+ i = i + 1
+ }
+ res
+ }
+
+Stainless will automatically generate a postcondition to the ``while`` loop, using
+the negation of the loop condition. It will automatically prove that
+verification condition and you should see an ``invariant postcondition`` marked
+as ``valid``.
+
+Stainless internally handles loops as a function with a postcondition. For the end-user, it
+means that Stainless is only going to rely on the postcondition of the loop to prove properties
+of code relying on loops. Usually that invariant is too weak to prove anything remotely
+useful and you will need to annotate the loop with a stronger invariant.
+
+You can annotate a loop with an invariant as follows:
+
+.. code-block:: scala
+
+ var res = 0
+ var i = 0
+ (while(i < 10) {
+ res = res + i
+ i = i + 1
+ }) invariant(i >= 0 && res >= i)
+
+The strange syntax comes from some Scala magic in order to make the keyword
+``invariant`` a valid keyword. Stainless is defining an implicit conversion from
+``Unit`` to an ``InvariantFunction`` object that provides an ``invariant``
+method. The ``invariant`` method takes a boolean expression as a parameter and
+its semantics is to hold at the following points during the execution of the loop:
+
+1. When first entering the loop: initialization.
+2. After each complete execution of the body.
+3. On exiting the loop.
+
+Stainless will generate verification conditions ``invariant inductive`` and
+``invariant postcondition`` to verify points (2) and (3) above. It will also
+generate a ``precondition`` corresponding to the line of the while loop. This
+verification condition is used to prove the invariant on initialization of the
+loop.
+
+Arrays
+------
+
+PureScala supports functional arrays, that is, the operations ``apply`` and
+``updated`` which do not modify an array but only returns some result. In
+particular, ``updated`` returns a new copy of the array.
+
+.. code-block:: scala
+
+ def f(a: Array[Int]): Array[Int] = {
+ a.updated(0, a(1))
+ }
+
+However, using functional arrays is not the most natural way to work with
+arrays, and arrays are often used in imperative implementations of algorithms.
+We add the usual ``update`` operation on arrays:
+
+.. code-block:: scala
+
+ val a = Array(1,2,3,4)
+ a(1) //2
+ a(1) = 10
+ a(1) //10
+
+Stainless simply rewrite arrays using ``update`` operation as the assignment of function arrays
+using ``updated``. This leverages the built-in algorithm for functional arrays
+and relies on the elimination procedure for assignments. Concretely, it would
+transform the above on the following equivalent implementation:
+
+.. code-block:: scala
+
+ var a = Array(1,2,3,4)
+ a(1) //2
+ a = a.updated(1, 10)
+ a(1) //10
+
+Stainless also has a ``swap`` operation in ``stainless.lang``, which is equivalent to two updates.
+
+.. code-block:: scala
+
+ def swap[@mutable T](a1: Array[T], i1: Int, a2: Array[T], i2: Int): Unit
+
+
+Mutable Objects
+---------------
+
+A restricted form of mutable classes is supported via case classes with ``var``
+arguments:
+
+.. code-block:: scala
+
+ case class A(var x: Int)
+ def f(): Int = {
+ val a = new A(10)
+ a.x = 13
+ a.x
+ }
+
+Mutable case classes are behaving similarly to ``Array``, and are handled with a
+rewriting, where each field updates becomes essentially a copy of the object with
+the modified parameter changed.
+
+Aliasing
+--------
+
+With mutable data structures comes the problem of aliasing. In Stainless, we
+maintain the invariant that in any scope, there is at most one pointer to some
+mutable structure. Stainless will issue an error if you try to create an alias to
+some mutable structure in the same scope:
+
+.. code-block:: scala
+
+ val a = Array(1,2,3,4)
+ val b = a //error: illegal aliasing
+ b(0) = 10
+ assert(a(0) == 10)
+
+However, Stainless correctly supports aliasing mutable structures when passing it
+as a parameter to a function (assuming its scope is not shared with the call
+site, i.e. not a nested function). Essentially you can do:
+
+.. code-block:: scala
+
+ case class A(var x: Int)
+ def updateA(a: A): Unit = {
+ a.x = 14
+ }
+ def f(): Unit = {
+ val a = A(10)
+ updateA(a)
+ assert(a.x == 14)
+ }
+
+The function ``updateA`` will have the side effect of updating its argument
+``a`` and this will be visible at the call site.
+
+Annotations for Imperative Programming
+--------------------------------------
+
+We introduce the special function ``old`` that can be used in postconditions to
+talk about the value of a variable before the execution of the block. When you refer to a variable
+or mutable structure in a post-condition, Stainless will always consider the current value of
+the object, so that in the case of a post-condition this would refer to the final value of the
+object. Using ``old``, you can refer to the original value of the variable and check some
+properties:
+
+.. code-block:: scala
+
+ case class A(var x: Int)
+ def inc(a: A): Unit = {
+ a.x = a.x + 1
+ } ensuring(_ => a.x == old(a).x + 1)
+
+``old`` can be wrapped around any identifier that is affected by the body. You can also use
+``old`` for variables in scope, in the case of nested functions:
+
+.. code-block:: scala
+
+ def f(): Int = {
+ var x = 0
+ def inc(): Unit = {
+ x = x + 1
+ } ensuring(_ => x == old(x) + 1)
+
+ inc(); inc();
+ assert(x == 2)
+ }
+
+Another useful and similar construct is ``snapshot`` that semantically makes a deep copy of a mutable object.
+Contrarily to ``old``, ``snapshot`` allows to refer to the state of an object prior to its mutation within
+the body of the function, as long as it is used in a :doc:`ghost context `.
+
+For instance:
+
+.. code-block:: scala
+
+ def updateArray(a: Array[BigInt], i: Int, x: BigInt): Unit = {
+ require(0 <= i && i < a.length - 1)
+ require(a(i) == 0 && a(i + 1) == 0)
+ @ghost val a0 = snapshot(a)
+ a(i) = x
+ // a0 is unaffected by the update of a
+ // Note: using StaticChecks assert, which introduces a ghost context
+ assert(a0(i) == 0 && a(i) == x)
+ @ghost val a1 = snapshot(a)
+ a(i + 1) = 2 * x
+ assert(a1(i + 1) == 0 && a(i + 1) == 2 * x)
+ }
+
+
+Extern functions and abstract methods
+-------------------------------------
+
+``@extern`` functions and abstract methods of non-sealed trait taking mutable objects as parameters are treated as-if
+they were applying arbitrary modifications to them.
+For instance, the assertions in the following snippet are invalid:
+
+.. code-block:: scala
+
+ @extern
+ def triple(mc: MutableClass): BigInt = ???
+
+ trait UnsealedTrait {
+ def quadruple(mc: MutableClass): BigInt
+ }
+
+ def test1(mc: MutableClass): Unit = {
+ val i = mc.i
+ triple(mc)
+ assert(i == mc.i) // Invalid, mc.i could be anything
+ }
+
+ def test2(ut: UnsealedTrait, mc: MutableClass): Unit = {
+ val i = mc.i
+ ut.quadruple(mc)
+ assert(i == mc.i) // Invalid as well
+ }
+
+Annotating such methods or functions with ``@pure`` tells Stainless to assume the parameters are not mutated:
+
+.. code-block:: scala
+
+ case class MutableClass(var i: BigInt)
+
+ @pure @extern
+ def triple(mc: MutableClass): BigInt = ???
+
+ trait UnsealedTrait {
+ @pure
+ def quadruple(mc: MutableClass): BigInt
+ }
+
+ def test1(mc: MutableClass): Unit = {
+ val i = mc.i
+ triple(mc)
+ assert(i == mc.i) // Ok
+ }
+
+ def test2(ut: UnsealedTrait, mc: MutableClass): Unit = {
+ val i = mc.i
+ ut.quadruple(mc)
+ assert(i == mc.i) // Ok
+ }
+
+Note that Stainless will enforce purity for visible implementations of ``quadruple``.
+
+Sometimes, a method or ``@extern`` function may mutate some parameters but not all of them.
+In such cases, the untouched parameters can be annotated with ``@pure``:
+
+.. code-block:: scala
+
+ case class MutableClass(var i: BigInt)
+
+ @extern
+ def sum(@pure mc1: MutableClass, mc2: MutableClass): BigInt = ???
+
+ trait UnsealedTrait {
+ def doubleSum(@pure mc1: MutableClass, mc2: MutableClass): BigInt
+ }
+
+ def test1(mc1: MutableClass, mc2: MutableClass): Unit = {
+ val i1 = mc1.i
+ val i2 = mc2.i
+ sum(mc1, mc2)
+ assert(i1 == mc1.i) // Ok
+ assert(i2 == mc2.i) // Invalid, mc2.i may have any value
+ }
+
+ def test2(ut: UnsealedTrait, mc1: MutableClass, mc2: MutableClass): Unit = {
+ val i1 = mc1.i
+ val i2 = mc2.i
+ ut.doubleSum(mc1, mc2)
+ assert(i1 == mc1.i) // Ok
+ assert(i2 == mc2.i) // Invalid
+ }
+
+Trait Variables
+---------------
+
+Traits are allowed to declare variables, with the restriction that these cannot be
+assigned a default value.
+
+.. code-block:: scala
+
+ trait MutableBox[A] {
+ var value: A
+ }
+
+Such abstract variables must be overridden at some point by either:
+
+a) a mutable field of a case class
+
+.. code-block:: scala
+
+ case class Box[A](var value: A) extends MutableBox[A]
+
+b) a pair of getter/setter
+
+.. code-block:: scala
+
+ case class WriteOnceBox[A](
+ var underlying: A,
+ var written: Boolean = false
+ ) extends MutableBox[A] {
+
+ def value: A = underlying
+
+ def value_=(newValue: A): Unit = {
+ if (!written) {
+ underlying = newValue
+ written = true
+ }
+ }
+ }
+
+Note: a setter is not required to actually perform any mutation, and the following
+is a perfectly valid sub-class of `MutableBox`:
+
+.. code-block:: scala
+
+ case class ImmutableBox[A](underlying: A) extends MutableBox[A] {
+ def value: A = underlying
+ def value_=(newValue: A): Unit = ()
+ }
+
+
+Return keyword
+--------------
+
+Stainless partially supports the `return` keyword. For verification, an internal
+phase of Stainless (called `ReturnElimination`) injects a data-structure named
+`ControlFlow` to simulate the control flow of programs with returns.
+
+.. code-block:: scala
+
+ sealed abstract class ControlFlow[Ret, Cur]
+ case class Return[Ret, Cur](value: Ret) extends ControlFlow[Ret, Cur]
+ case class Proceed[Ret, Cur](value: Cur) extends ControlFlow[Ret, Cur]
+
+Here is a function taken from `ControlFlow2.scala `_:
+
+.. code-block:: scala
+
+ def foo(x: Option[BigInt], a: Boolean, b: Boolean): BigInt = {
+ if (a && b) {
+ return 1
+ }
+
+ val y = x match {
+ case None() => return 0
+ case Some(x) if a => return x + 1
+ case Some(x) if b => return x + 2
+ case Some(x) => x
+ };
+
+ -y
+ }
+
+The program transformation can be inspected by running:
+
+ .. code-block:: bash
+
+ stainless ControlFlow2.scala --batched --debug=trees --debug-objects=foo --debug-phases=ReturnElimination
+
+We get the following output (with ``cf`` identifiers renamed for clarity; you can
+use the ``--print-ids`` option so that Stainless expressions get displayed with
+unique identifiers, at the cost of readability):
+
+ .. code-block:: scala
+
+ def foo(x: Option[BigInt], a: Boolean, b: Boolean): BigInt = {
+ val cf0: ControlFlow[BigInt, Unit] = if (a && b) {
+ Return[BigInt, Unit](1)
+ } else {
+ Proceed[BigInt, Unit](())
+ }
+ cf0 match {
+ case Return(retValue) =>
+ retValue
+ case Proceed(proceedValue) =>
+ val cf1: ControlFlow[BigInt, BigInt] = x match {
+ case None() => Return[BigInt, BigInt](0)
+ case Some(x) if a => Return[BigInt, BigInt](x + 1)
+ case Some(x) if b => Return[BigInt, BigInt](x + 2)
+ case Some(x) => Proceed[BigInt, BigInt](x)
+ }
+ cf1 match {
+ case Return(retValue) =>
+ retValue
+ case Proceed(proceedValue) =>
+ -proceedValue
+ }
+ }
+ }
+
+Stainless also supports ``return`` in while loops, and transforms them to local functions, also in
+the ``ReturnElimination`` phase. Here is a function taken from `ReturnInWhile.scala `_.
+
+ .. code-block:: scala
+
+ def returnN(n: Int): Int = {
+ require(n >= 0)
+ var i = 0
+ (while (true) {
+ decreases(n - i)
+ if (i == n) return i
+ i += 1
+ }).invariant(0 <= i && i <= n)
+
+ assert(false, "unreachable code")
+ 0
+ }.ensuring((res: Int) => res == n)
+
+After transformation, we get a recursive (local) function named ``returnWhile``
+that returns a control flow element to indicate whether the loop terminated
+normally or returned. We check that the invariant clause of the while loop is
+indeed an invariant by adding it to the pre and postconditions of the generated
+``returnWhile`` function. When the while loop returns, we check in addition that
+the postcondition of the top-level holds (see comment).
+
+ .. code-block:: scala
+
+ def returnN(n: Int): Int = {
+ require(n >= 0)
+
+ var i: Int = 0
+ val cf0: ControlFlow[Int, Unit] = {
+ def returnNWhile: ControlFlow[Int, Unit] = {
+ require(0 <= i && i <= n)
+ decreases(n - i)
+ {
+ val cf1: ControlFlow[Int, Unit] = if (i == n) {
+ Return[Int, Unit](i)
+ } else {
+ Proceed[Int, Unit](())
+ }
+ cf1 match {
+ case Return(retValue) => Return[Int, Unit](retValue)
+ case Proceed(proceedValue) =>
+ Proceed[Int, Unit]({
+ i = (i + 1)
+ ()
+ })
+ }
+ } match {
+ case Return(retValue) =>
+ Return[Int, Unit](retValue)
+ case Proceed(proceedValue) =>
+ if (true) {
+ returnNWhile
+ } else {
+ Proceed[Int, Unit](())
+ }
+ }
+ } ensuring {
+ (cfWhile: ControlFlow[Int, Unit]) => cfWhile match {
+ case Return(retValue) =>
+ // we check the postcondition `retValue == n` of the top-level function
+ retValue == n &&
+ 0 <= i && i <= n
+ case Proceed(proceedValue) =>
+ ¬true && 0 <= i && i <= n
+ }
+ }
+ if (true) {
+ returnNWhile
+ } else {
+ Proceed[Int, Unit](())
+ }
+ }
+ cf0 match {
+ case Return(retValue) => retValue
+ case Proceed(proceedValue) =>
+ assert(false, "unreachable code")
+ 0
+ }
+ } ensuring {
+ (res: Int) => res == n
+ }
+
+Finally, ``return`` is also supported for local function definitions, with the same transformation.
+It is however not supported for anonymous functions.
diff --git a/_sources/index.rst.txt b/_sources/index.rst.txt
new file mode 100644
index 0000000000..38ded73814
--- /dev/null
+++ b/_sources/index.rst.txt
@@ -0,0 +1,36 @@
+.. Stainless documentation master file, created by
+ sphinx-quickstart on Fri Feb 27 13:23:31 2015.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+
+Stainless documentation
+=======================
+
+Contents:
+
+.. toctree::
+ :maxdepth: 2
+
+ intro
+ installation
+ gettingstarted
+ tutorial
+ options
+ verification
+ laws
+ imperative
+ equivalence
+ ghost
+ wrap
+ purescala
+ library
+ genc
+ neon
+ limitations
+ casestudies
+ coq
+ faq
+ references
+ internals
+
+* :ref:`search`
diff --git a/_sources/installation.rst.txt b/_sources/installation.rst.txt
new file mode 100644
index 0000000000..63e5cf670e
--- /dev/null
+++ b/_sources/installation.rst.txt
@@ -0,0 +1,402 @@
+.. _installation:
+
+Installing Stainless
+====================
+
+.. _requirements:
+
+General Requirement
+-------------------
+
+- Java 17 JRE
+ It suffices to have headless OpenJDK JRE 17 (e.g. one that one gets with ``apt install openjdk-17-jre-headless`` on Debian/Ubuntu).
+ Make sure that ``java -version`` reports a version starting with 1.17, such as ``openjdk version "1.17`` or ``java version "1.17``.
+
+Stainless bundles Scala compiler front-end and runs it before it starts compilation. We recommend using the Scala 3 front end (originally named dotty), though Scala 2 is also available.
+
+.. _standalone-release:
+
+Use Standalone Release (recommended)
+------------------------------------
+
+1. Download the latest Stainless release from the `Releases page on GitHub `_, under the **Assets** section. Make sure to pick the appropriate ZIP for your operating system. This release is bundled with Z3 4.12.2 and cvc5 1.0.8.
+
+2. Unzip the the file you just downloaded to a directory.
+
+3. (Optional) Add this directory to your ``PATH``. This will let you invoke Stainless via the ``stainless`` command instead of its fully qualified path in step 5.
+
+4. Paste the following code in a file named ``HelloStainless.scala``:
+
+.. code-block:: scala
+
+ import stainless.collection._
+
+ object HelloStainless {
+ def myTail(xs: List[BigInt]): BigInt = {
+ require(xs.nonEmpty)
+ xs match {
+ case Cons(h, _) => h
+ // Match provably exhaustive
+ }
+ }
+ }
+
+5. In a terminal, type the following command, substituting the proper path to the directory where you unzipped the latest release:
+
+.. code-block:: bash
+
+ $ /path/to/unzipped/directory/stainless HelloStainless.scala
+
+6. The output should read:
+
+.. code-block:: text
+
+ [ Debug ] Generating VCs for functions: myTail
+ [ Debug ] Finished generating VCs
+ [ Info ] Starting verification...
+ [ Info ] Verified: 0 / 1
+ [ Debug ] - Checking cache: 'body assertion: match exhaustiveness' VC for myTail @6:5...
+ [ Debug ] Cache miss: 'body assertion: match exhaustiveness' VC for myTail @6:5...
+ [ Debug ] - Now solving 'body assertion: match exhaustiveness' VC for myTail @6:5...
+ [ Debug ]
+ [ Debug ] - Original VC:
+ [ Debug ] nonEmpty[BigInt](xs) ==> {
+ [ Debug ] val scrut: List[BigInt] = xs
+ [ Debug ] !scrut.isInstanceOf[Cons] ==> false
+ [ Debug ] }
+ [ Debug ]
+ [ Debug ] - Simplified VC:
+ [ Debug ] !nonEmpty[BigInt](xs) || xs.isInstanceOf[Cons]
+ [ Debug ]
+ [ Debug ] Solving with: nativez3
+ [ Debug ] - Result for 'body assertion: match exhaustiveness' VC for myTail @6:5:
+ [ Debug ] => VALID
+ [ Info ] Verified: 1 / 1
+ [ Info ] ┌───────────────────┐
+ [ Info ] ╔═╡ stainless summary ╞═════════════════════════════════════════════════════════════════════════════════╗
+ [ Info ] ║ └───────────────────┘ ║
+ [ Info ] ║ HelloStainless.scala:6:5: myTail body assertion: match exhaustiveness valid nativez3 0,2 ║
+ [ Info ] ╟┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄╢
+ [ Info ] ║ total: 1 valid: 1 (0 from cache, 0 trivial) invalid: 0 unknown: 0 time: 0,17 ║
+ [ Info ] ╚═══════════════════════════════════════════════════════════════════════════════════════════════════════╝
+ [ Info ] Verification pipeline summary:
+ [ Info ] cache, nativez3
+ [ Info ] Shutting down executor service.
+
+Note: If the warning above says something about falling back on the Princess solver, you might be missing the ``libgomp1`` library,
+which you can install with your favorite package manager. For example, on Debian/Ubuntu, just run ``apt-get install libgomp1``.
+
+
+.. _sbt-project:
+
+Usage Within An Existing Project
+********************************
+
+Stainless can also be used within an existing SBT 1.7.x project.
+
+1. Start by installing an external solver (see Section ":ref:`smt-solvers`").
+
+2. Download ``sbt-stainless`` from the `GitHub releases `_, and move it to the directory of the project. You should have the following project structure:
+
+.. code-block::
+
+ MyProject
+ ├── build.sbt
+ ├── project
+ │ └── build.properties
+ ├── sbt-stainless.zip <--------
+ └── src/
+
+3. Unzip ``sbt-stainless.zip``:
+
+.. code-block::
+
+ MyProject
+ ├── build.sbt
+ ├── project
+ │ ├── build.properties
+ │ └── lib <--------
+ │ └── sbt-stainless.jar <--------
+ ├── sbt-stainless.zip
+ ├── src/
+ └── stainless/ <--------
+
+4. In your project's build file, enable the ``StainlessPlugin`` on the modules that should be verified by Stainless. Below is an example:
+
+.. code-block:: scala
+
+ // build.sbt
+ lazy val algorithm = project
+ .in(file("algorithm"))
+ .enablePlugins(StainlessPlugin) // <-- Enabling Stainless verification on this module!
+ .settings(...)
+
+Note that if you are using ``.scala`` build files you need to use the fully qualified name ``ch.epfl.lara.sbt.stainless.StainlessPlugin``. Also, because Stainless accepts a subset of the Scala language, you may need to refactor your build a bit and code to successfully use Stainless on a module.
+
+5. After modifying the build, type ``reload`` if inside the sbt interactive shell. From now on, when executing ``compile`` on a module where the ``StainlessPlugin`` is enabled, Stainless will check your Scala code and report errors in the shell (just like any other error that would be reported during compilation).
+
+That's all there is to it. However, the ``sbt-stainless`` plugin is a more recent addition to Stainless compared to command-line script. Furthermore, there incremental compilation is not supported. All sources (included the stainless-library sources) are recompiled at every ``compile`` execution.ub
+
+Also, note that the plugin offers a ``stainlessEnabled`` setting that can help experimenting with Stainless. The ``stainlessEnabled`` setting is set to ``true`` by default, but you can flip the flag to false by typing ``set every stainlessEnabled := false`` while inside the sbt interactive shell.
+
+6. It is possible to specify extra source dependencies to be added to the set of files processed by Stainless via the ``stainlessExtraDeps`` setting. For example, to add both the ``stainless-algebra`` and ``stainless-actors`` packages, along with the latter's dependency on Akka,
+ one can add the following settings to their build:
+
+.. code-block:: scala
+
+ stainlessExtraDeps ++= Seq(
+ "ch.epfl.lara" %% "stainless-algebra" % "0.1.2",
+ "ch.epfl.lara" %% "stainless-actors" % "0.1.1",
+ )
+
+ libraryDependencies += "com.typesafe.akka" %% "akka-actor" % "2.5.21"
+
+Note that the dependencies specified in ``stainlessExtraDeps`` must be available as a source JAR from any of the resolvers configured in the build.
+
+.. _running-code:
+
+Running Code with Stainless dependencies
+----------------------------------------
+
+Using sources:
+
+1. Clone the sources from https://github.com/epfl-lara/stainless
+
+2. Create a folder to put compiled Scala objects: ``mkdir -p ~/.scala_objects``
+
+3. Compile your code (here in ``MyFile.scala``, though you can have more than one file) while referring to the Stainless library sources: ``scalac -d ~/.scala_objects $(find /path/to/stainless/frontends/library/stainless/ -name "*.scala") MyFile.scala``
+
+4. Run your code (replace ``MyMainClass`` with the name of your main object): ``scala -cp ~/.scala_objects MyMainClass``
+
+Using jar:
+
+You can package the Stainless library into a jar to avoid the need to compile it every time:
+
+.. code-block:: bash
+
+ $ cd path/to/stainless/
+ $ sbt stainless-library/packageBin
+
+Add the generated Stainless library jar file when invoking the compiler with ``scalac`` and the JVM with ``scala`` or ``java``. For instance:
+
+.. code-block:: bash
+
+ $ mkdir -p ~/.scala_objects
+ $ scalac -d ~/.scala_objects -cp /path/to/stainless/frontends/library/target/scala-2.13/stainless-library_2.13-X.Y.Z-A-BCDEFGHI.jar MyFile1.scala MyFile2.scala # and so on
+ $ scala -cp ~/.scala_objects:/path/to/stainless/frontends/library/target/scala-2.13/stainless-library_2.13-X.Y.Z-A-BCDEFGHI.jar MyMainClass
+
+where ``X.Y.Z`` is the Stainless version and ``A-BCDEFGHI`` is some hash (which can be autocompleted by the terminal).
+
+.. _smt-solvers:
+
+External Solver Binaries
+------------------------
+
+If no external SMT solvers (such as Z3 or cvc5) are found, Stainless will use the bundled Scala-based `Princess solver `_
+
+To improve performance, we highly recommend that you install the following two additional external SMT solvers as binaries for your platform:
+
+* cvc5 1.0.8, https://cvc5.github.io/
+* Z3 4.12.2, https://github.com/Z3Prover/z3
+
+You can enable these solvers using ``--solvers=smt-z3`` and ``--solvers=smt-cvc5`` flags.
+
+Solver binaries that you install should match your operating system and your architecture. We recommend that you install these solvers as a binary and have their binaries available in the ``$PATH`` (as ``z3`` or ``cvc5``).
+
+Note that somewhat lower version numbers of solvers should work as well and might even have different sets of soundness-related issues.
+
+You can use multiple solvers in portfolio mode, as with the options ``--timeout=15 --solvers=smt-z3,smt-cvc5``, where verification succeeds if at least one of the solvers proves (within the given number of seconds) each the verification conditions. We suggest to order the solvers starting from the one most likely to succeed quickly.
+
+For final verification runs of highly critical software, we recommend that (instead of the portfolio mode) you obtain several solvers and their versions, then try a single solver at a time and ensure that each verification run succeeds (thus applying N-version programming to SMT solver implementations).
+
+Install Z3 4.12.2
+*****************
+
+1. Download Z3 4.12.2 from https://github.com/Z3Prover/z3/releases/tag/z3-4.12.2
+2. Unzip the downloaded archive
+3. Copy the ``z3`` binary found in the ``bin/`` directory of the inflated archive to a directory in your ``$PATH``, eg., ``/usr/local/bin``.
+4. Make sure ``z3`` can be found, by opening a new terminal window and typing:
+
+.. code-block:: bash
+
+ $ z3 --version
+
+5. The output should read:
+
+.. code-block:: text
+
+ Z3 version 4.12.2 - 64 bit`
+
+
+Install cvc5 1.0.8
+******************
+
+1. Download cvc5 1.0.8 from https://github.com/cvc5/cvc5/releases/tag/cvc5-1.0.8 for your platform.
+
+2. Copy or link the downloaded binary under name ``cvc5`` to a directory in your ``$PATH``, eg., ``/usr/local/bin``.
+
+4. Make sure ``cvc5`` can be found, by opening a new terminal window and typing:
+
+.. code-block:: bash
+
+ $ cvc5 --version | head
+
+5. The output should begin with:
+
+.. code-block:: text
+
+ This is cvc5 version 1.0.8
+
+
+Build from Source on Linux & macOS
+----------------------------------
+
+To build Stainless, we use ``sbt``. In a typical configuration, ``sbt universal:stage`` in the root of the source tree should work, yet,
+in an attempt to be more reproducible and independent from SBT cache and path, the instructions below assume that the directory called ``stainless`` does not exist, they instruct ``sbt`` to use a relative path for its bootstrap, and do not require adding ``sbt`` to your path.
+
+**Install SBT**
+
+Follow the instructions at http://www.scala-sbt.org/ to install ``sbt`` 1.7.3 (or somewhat later version).
+
+**Check out sources**
+
+Get the sources of Stainless by cloning the official Stainless repository:
+
+.. code-block:: bash
+
+ $ git clone https://github.com/epfl-lara/stainless.git
+ Cloning into 'stainless'...
+
+**Run SBT**
+
+The following instructions will invoke SBT while using a stainless sub-directory to download files.
+
+.. code-block:: bash
+
+ $ cd stainless
+ $ sbt universal:stage
+
+**Where to find generated files**
+
+The compilation will automatically generate the bash script ``stainless-dotty`` (and the Scala2 one ``stainless-scalac``).
+
+You may want to introduce a soft-link from to a file called ``stainless``:
+
+.. code-block:: bash
+
+ $ ln -s frontends/dotty/target/universal/stage/bin/stainless-dotty stainless
+
+and, for the Scala2 version of the front end,
+
+ $ ln -s frontends/scalac/target/universal/stage/bin/stainless-scalac stainless-scalac-old
+
+Analogous scripts work for various platforms and allow additional control over the execution, such as passing JVM arguments or system properties:
+
+.. code-block:: bash
+
+ $ stainless -Dscalaz3.debug.load=true -J-Xmx6G --help
+
+Note that Stainless is organized as a structure of several projects. The main project lives in ``core`` while the two available frontends can be found in ``frontends/dotty`` (and ``frontends/scalac``). From a user point of view, this should most of the time be transparent and the build command should take care of everything.
+
+Build from Source on Windows 10
+-------------------------------
+
+Before following the infrequently updated instructions in this section, considering running Ubuntu on Windows 10 (through e.g. WSL) and following the instructions for Linux.
+
+Get the sources of Stainless by cloning the official Stainless repository. You will need a Git shell for windows, e.g. `Git for Windows `_.
+On Windows, please do not use ``sbt universal:stage`` as this generates a Windows batch file which is unusable, because it contains commands that are too long for Windows.
+Instead, please use ``sbt stainless-scalac-standalone/assembly`` as follows:
+
+.. code-block:: bash
+
+ $ git clone https://github.com/epfl-lara/stainless.git
+ Cloning into 'stainless'...
+ // ...
+ $ cd stainless
+ $ sbt stainless-scalac-standalone/assembly
+ // takes about 1 minutes
+
+Running Stainless can then be done with the command: ``java -jar frontends\stainless-dotty-standalone\target\scala-3.3.3\stainless-dotty-standalone-{VERSION}.jar``, where ``VERSION`` denotes Stainless version.
+
+Running Tests
+-------------
+
+Stainless comes with a test suite. Use the following commands to
+invoke different test suites:
+
+.. code-block:: bash
+
+ $ sbt test
+ $ sbt it:test
+
+It's also possible to run tests in isolation, for example, the following command runs ``Extraction`` tests on all files in ``termination/looping``:
+
+.. code-block:: bash
+
+ $ sbt 'it:testOnly *ExtractionSuite* -- -z "in termination/looping"'
+
+Building Stainless Documentation
+--------------------------------
+
+Stainless documentation is available at https://epfl-lara.github.io/stainless/ .
+To build the documentation locally, you will need Sphinx (
+http://sphinx-doc.org/ ), a restructured text toolkit that
+was originally developed to support Python documentation.
+
+* On Ubuntu 18, you can use ``sudo apt install sphinx-common``
+
+The documentation resides in the ``core/src/sphinx/`` directory and can be built using the provided ``Makefile``. To do this, in a Linux shell,
+type ``make html``, and open in your web browser the generated top-level local HTML file, by default stored in
+``core/src/sphinx/_build/html/index.html``. Also, you can open the ``*.rst`` documentation files in a text editor, as they are human-readable in their source form as well.
+
+Note for project maintainers: to build documentation on GitHub Pages, use ``make gh-pages`` in the same Makefile, or adapt it to you needs.
+
+Using IDEs with --no-colors option. Emacs illustration
+------------------------------------------------------
+
+Using command line option ``--no-colors`` asks stainless to produce clear 7-bit ASCII output with error messages in a standardized format:
+
+.. code-block:: bash
+
+ FileName.scala:LineNo:ColNo: text of the error message
+
+This helps IDEs to pick up line numbers and show error location in the source file.
+
+In ``emacs`` editor, you can invoke ``ansi-term`` and ``compilation-shell-minor-mode``. Then, run
+
+.. code-block:: bash
+
+ stainless --no-colors
+
+You may also consider using the ``--watch`` option.
+
+You should now be able to click on a message for verification condition to jump to the appropriate position in the appropriate file, as well as to use emacs commands ``previous-error`` and ``next-error`` to navigate through errors and other verification-condition outcomes.
+
+Here is a very simple illustration that introduces an interactive ``comp-ansi-term`` command that creates new window with ansi-term and minor compilation mode:
+
+.. code-block:: lisp
+
+ (setq comp-terminal-current-number 1)
+ (defun create-numbered-comp-terminal ()
+ (ansi-term "/bin/bash")
+ (rename-buffer (concat "q" (number-to-string comp-terminal-current-number)) 1)
+ (setq comp-terminal-current-number (+ comp-terminal-current-number 1))
+ (compilation-shell-minor-mode)
+ )
+ (defun comp-ansi-term (arg)
+ "Run ansi-term with bash and compilation-shell-minor-mode in buffer named q_N for increasing N" (interactive "P")
+ (create-numbered-comp-terminal)
+ (split-window-vertically)
+ (previous-buffer)
+ (other-window 1)
+ )
+
+The following globally binds the above command to the F3 key and binds F7 and F8 to commands for navigating reports:
+
+.. code-block:: lisp
+
+ (global-set-key [f3] 'comp-ansi-term)
+ (global-set-key [f7] 'previous-error)
+ (global-set-key [f8] 'next-error)
+
+For more information, please consult the documentation for ``emacs``.
diff --git a/_sources/internals.rst.txt b/_sources/internals.rst.txt
new file mode 100644
index 0000000000..106113f3f0
--- /dev/null
+++ b/_sources/internals.rst.txt
@@ -0,0 +1,12 @@
+.. _internals:
+
+Stainless' Internals
+====================
+
+The main component of Stainless and the dataflow in its pipeline:
+
+.. image:: static/images/pipeline.svg
+ :width: 90%
+
+
+
diff --git a/_sources/intro.rst.txt b/_sources/intro.rst.txt
new file mode 100644
index 0000000000..3203e7f894
--- /dev/null
+++ b/_sources/intro.rst.txt
@@ -0,0 +1,135 @@
+Introduction
+============
+
+The Stainless verification framework aims to help developers build
+verified Scala software. It encourages using a small set of core
+Scala features and provides unique verification functionality.
+In particular, Stainless can
+
+* verify statically that your program conforms to a given
+ specification and that it cannot crash at run-time
+
+* provide useful counterexamples when an implementation does
+ not satisfy its specification
+
+* verify that your program will terminate on all inputs
+
+
+Stainless and Scala
+-------------------
+
+Stainless attempts to strike a delicate balance between the
+convenience of use on the one hand and the simplicity of
+reasoning on the other hand. Stainless supports verification
+of Scala programs by applying a succession of semantic-preserving
+transformations to the :doc:`Pure Scala ` fragment until
+it fits into the fragment supported by
+`Inox `_.
+The Pure Scala fragment is at the core of
+the functional programming paradigm and should sound familiar to
+users of Scala, Haskell, ML, and fragments
+present in interactive theorem provers such as Isabelle and Coq. Thus,
+if you do not already know Scala, learning the Stainless subset should
+be easier as it is a smaller language. Moreover, thanks to the use of
+a Scala front end, Stainless supports implicits and ``for``
+comprehensions (which also serve as a syntax for monads in Scala).
+Stainless also comes with a simple library of useful data types, which
+are designed to work well with automated reasoning and Stainless's
+language fragment.
+
+In addition to this pure fragment, Stainless supports certain
+:doc:`imperative ` features.
+Features thus introduced are handled by
+a translation into Pure Scala concepts. They are often more
+than just syntactic sugar, because some of them require
+significant modification of the original program, such as
+introducing additional parameters to a set of functions. As
+an intended aspect of its current design, Stainless's language
+currently does not provide a default encoding of
+e.g. concurrency with a shared mutable heap, though it might
+support more manageable forms of concurrency in the future.
+
+If you would like to use Stainless now, check the
+:doc:`installation` section and follow :doc:`gettingstarted` and :doc:`Tutorial `.
+To learn more about the functionality that Stainless provides, read on below.
+
+Software Verification
+---------------------
+
+The Stainless program verifier collects a list of top-level functions,
+and verifies the *validity* of their *contracts*. Essentially, for each function,
+it will (try to) prove that the postcondition always holds, assuming a given
+precondition does hold. A simple example:
+
+.. code-block:: scala
+
+ def factorial(n: BigInt): BigInt = {
+ require(n >= 0)
+ if(n == 0) {
+ BigInt(1)
+ } else {
+ n * factorial(n - 1)
+ }
+ } ensuring(res => res >= 0)
+
+Stainless generates a ``postcondition`` verification condition for the above
+function, corresponding to the predicate parameter to the ``ensuring``
+expression. It attempts to prove it using a combination of an internal
+algorithm and external automated theorem proving. Stainless will return one of the
+following:
+
+* The postcondition is ``valid``. In that case, Stainless was able to prove that for **any**
+ input to the function satisfying the precondition, the postcondition will always hold.
+* The postcondition is ``invalid``. It means that Stainless disproved the postcondition and
+ that there exists at least one input satisfying the precondition such that the
+ postcondition does not hold. Stainless will always return a concrete counterexample, very
+ useful when trying to understand why a function is not satisfying its contract.
+* The postcondition is ``unknown``. It means Stainless is unable to prove or find a
+ counterexample. It usually happens after a timeout or an internal error occurring in
+ the external theorem prover.
+
+Stainless will also verify for each call site that the precondition of the invoked
+function cannot be violated.
+
+Stainless supports verification of a significant part of the Scala language, described in
+:doc:`purescala` and :doc:`imperative`.
+
+Program Termination
+-------------------
+
+A "verified" function in stainless is guaranteed to never crash, however, it can
+still lead to an infinite evaluation. Stainless therefore provides a termination
+checker that complements the verification of safety properties.
+
+For each function in the program, Stainless will try to automatically infer a
+decreasing metric associated with this function to prove termination. The
+termination checker will then report one of the following:
+
+* The function ``terminates``. In this case, Stainless was able to prove that for
+ all inputs (satisfying the function's precondition), evaluation of the function
+ under those inputs is guaranteed to terminate.
+* The function ``loops``. In this case, Stainless was able to construct an input
+ to the function such that evaluation under that input will be looping.
+* The function ``maybe loops``. In the case where recursive functions are passed
+ around as first-class functions, Stainless will sometimes over-approximate the
+ potential call sites and report loops that may never occur.
+* Termination of the function is ``unknown``. In this case, Stainless was neither
+ able to prove nor disprove termination of the relevant function. Automated
+ termination proving is a *hard* problem and such cases are thus to be expected.
+
+In cases where automated termination checking fails, Stainless provides the user
+with the ability to manually specify a measure under which termination should
+occur through the ``decreases`` construct. For example, the
+`McCarthy 91 function `_
+can be shown terminating as follows:
+
+.. code-block:: scala
+
+ def M(n: BigInt): BigInt = {
+ decreases(stainless.math.max(101 - n, 0))
+ if (n > 100) n - 10 else M(M(n + 11))
+ } ensuring (_ == (if (n > 100) n - 10 else BigInt(91)))
+
+
+It is also possible to add a pre-condition (``require(...)``) *before* ``decreases``.
+
diff --git a/_sources/laws.rst.txt b/_sources/laws.rst.txt
new file mode 100644
index 0000000000..06d5a5f713
--- /dev/null
+++ b/_sources/laws.rst.txt
@@ -0,0 +1,605 @@
+.. _laws:
+
+Specifying Algebraic Properties
+===============================
+
+Introduction
+------------
+
+Many datatypes that programmers deal with on a day-to-day basis often provide
+the same set of operations, for example:
+
+- They can be tested for equality to some other value
+- They can be ordered (partially or totally)
+- They can be composed together
+- They can be added or multiplied together
+- They have an inverse with respect to some operation
+
+Because those are very common properties, it is often useful to be able to
+abstract over them. In fact, each of these properties corresponds to an
+algebraic structure, and is governed by the set of laws which allow the
+programmer to reason at a higher level of abstraction, and to be able
+to rely on the behavior specified by the laws associated with the structure.
+
+While these properties can be modeled and implemented using Java interfaces,
+modern programming languages such as Scala or Haskell provide a better
+mechanism for expressing the properties: typeclasses.
+
+Typeclasses
+-----------
+
+Typeclasses were introduced by Wadler & Blott [WB89]_ as an extension
+to the Hindley/Milner type system to implement a certain kind of overloading,
+known as *ad-hoc* polymorphism.
+
+A typeclass is identified by its name, and is associated with a set of
+(usually polymorphic) functions signatures, its *methods*.
+
+It can then be *instantiated* at various types, given that the user is able
+to provide a concrete implementation for each method. A user can then apply
+these methods to any type for which there is a corresponding instance, which
+essentially corresponds to *overloading*.
+
+Using typeclasses, one can model algebraic properties of datatypes in a fairly natural way.
+Here is for example, the definition and implementation of a ``Monoid``, ie. a typeclass
+for datatypes which can be mashed together associatively, and which have an
+identity element w.r.t. to this operation:
+
+.. code-block:: scala
+
+ abstract class Monoid[A] {
+ def empty: A
+ def append(x: A, y: A): A
+
+ @law
+ def law_leftIdentity(x: A) = {
+ append(empty, x) == x
+ }
+
+ @law
+ def law_rightIdentity(x: A) = {
+ append(x, empty) == x
+ }
+
+ @law
+ def law_associativity(x: A, y: A, z: A) = {
+ append(x, append(y, z)) == append(append(x, y), z)
+ }
+ }
+
+ implicit val bigIntAdditiveMonoid: Monoid[BigInt] = new Monoid[BigInt] {
+ override def empty: BigInt = 0
+ override def append(x: BigInt, y: BigInt): BigInt = x + y
+ }
+
+Here, the abstract class specifies the two abstract operations which are required,
+but also the associated laws that the implementation of these operations must
+satisfy for the datatype to form a valid monoid.
+
+Stainless will then ensure that the implementation of ``Monoid`` for the ``BigInt`` type satisfy
+those laws. In this case, the above definition of ``bigIntAdditiveMonoid`` will generate the
+following verification conditions::
+
+ ┌───────────────────┐
+ ╔═╡ stainless summary ╞══════════════════════════════════════════════════════════════════════╗
+ ║ └───────────────────┘ ║
+ ║ law_associativity law valid nativez3 ../../test.scala:25:3 0.052 ║
+ ║ law_leftIdentity law valid nativez3 ../../test.scala:25:3 0.037 ║
+ ║ law_rightIdentity law valid nativez3 ../../test.scala:25:3 0.029 ║
+ ╟--------------------------------------------------------------------------------------------╢
+ ║ total: 9 valid: 9 (0 from cache) invalid: 0 unknown: 0 time: 0.729 ║
+ ╚════════════════════════════════════════════════════════════════════════════════════════════╝
+
+Armed with the knowledge that our ``Monoid`` will always be lawful, one can now fearlessly write
+the ``foldMap`` function, and get the expected result:
+
+.. code-block:: scala
+
+ def foldMap[A, M](xs: List[A])(f: A => M)(implicit M: Monoid[M]): M = xs match {
+ case Nil() => M.empty
+ case Cons(y, ys) => M.append(f(y), foldMap(ys)(f))
+ }
+
+ def sumBigInt(xs: List[BigInt]): BigInt = {
+ foldMap(xs)(x => x)
+ }
+
+Sometimes, Stainless will not be able to automatically prove that an instance is lawful,
+for example when the property of interest involves a recursive definition over an inductive
+data type, as in the following code:
+
+.. code-block:: scala
+
+ sealed abstract class Nat {
+ def +(m: Nat): Nat = this match {
+ case Zero => m
+ case Succ(n) => Succ(n + m)
+ }
+
+ def *(m: Nat): Nat = this match {
+ case Zero => Zero
+ case Succ(n) => n * m + m
+ }
+ }
+
+ final case object Zero extends Nat
+ final case class Succ(prev: Nat) extends Nat
+
+ final val One = Succ(Zero)
+
+ implicit def natAdditiveMonoid: Monoid[Nat] = new Monoid[Nat] {
+ def empty: nat = Zero
+ def append(x: Nat, y: Nat): Nat = x + y
+ }
+
+To help Stainless out, one needs to prove that ``Zero`` indeed the right identity of ``+``,
+as well as the associativity of the latter.
+
+.. code-block:: scala
+
+ @induct
+ def lemma_rightIdentity_plus(x: Nat): Boolean = {
+ x + Zero == x
+ }.holds
+
+ @induct
+ def lemma_associativity_plus(x: Nat, y: Nat, z: Nat): Boolean = {
+ x + (y + z) == (x + y) + z
+ }.holds
+
+One can then override the law of interest, and instantiate the lemma over the relevant parameters:
+
+.. code-block:: scala
+
+ implicit def natAdditiveMonoid: Monoid[Nat] = new Monoid[Nat] {
+ def empty: nat = Zero
+ def append(x: Nat, y: Nat): Nat = x + y
+
+ override def law_rightIdentity(x: Nat) = {
+ super.law_rightIdentity(x) because lemma_rightIdentity_plus(x)
+ }
+
+ override def law_associativity(x: Nat, y: Nat, z: Nat) = {
+ super.law_associativity(x, y, z) because lemma_associativity_plus(x, y, z)
+ }
+ }
+
+With these modifications, the example goes through without a hitch.
+
+Typeclass inheritance
+---------------------
+
+Some algebraic structures can be defined as some other algebraic structure plus some additional
+operations and/or laws, eg. a monoid can be seen as a semigroup with identity.
+
+In Scala, typeclasses allow to represent such relationship between algebraic structures by mean of inheritance.
+
+Let's take for example the ``Ord`` typeclass, which describes totally ordered datatypes.
+
+This class is defined as follows:
+
+.. code-block:: scala
+
+ trait Eq[A] {
+ def equals(x: A, y: A): Boolean
+ }
+
+ trait Ord[A] extends Eq[A] {
+ def lessThanEq(x: A, y: A): Boolean
+
+ def lessThan(x: A, y: A): Boolean = lessThanEq(x, y) && !equals(x, y)
+ }
+
+This can also be read as: if ``A`` is an instance of ``Ord``, then it also is a instance of ``Eq``.
+
+Associated methods
+------------------
+
+On top of abstract operations, a typeclass can also introduces concrete methods which
+do not need to (but can) be re-defined by the programmer at instance declaration time,
+just like the ``lessThan`` method of the ``Ord`` class above.
+
+While such methods could be defined as a standalone function with an ``Ord`` constraint,
+having it be a part of the class allows users to override it with e.g. a more efficient
+implementation specific to the datatype they are instantiating the class for, as shown below:
+
+.. code-block:: scala
+
+ case object BigIntOrd extends Ord[BigInt] {
+ def equal(x: BigInt, y: BigInt) = x == y
+ def lessThanEq(x: BigInt, y: BigInt) = x <= y
+
+ override def lessThan(x: BigInt, y: BigInt) x < y
+ }
+
+Coherence
+---------
+
+Let's now look at an issue that might arise when working with typeclasses in Scala.
+
+.. code-block:: scala
+
+ abstract class Monoid[A] {
+ def empty: A
+ def combine(x: A, y: A): A
+ }
+
+ implicit val bigIntAddMonoid: Monoid[BigInt] = new Monoid[BigInt] {
+ override def empty: BigInt = 0
+ override def combine(x: BigInt, y: BigInt): BigInt = x + y
+ }
+
+ implicit val bigIntProdMonoid: Monoid[BigInt] = new Monoid[BigInt] {
+ override def empty: BigInt = 1
+ override def combine(x: BigInt, y: BigInt): BigInt = x * y
+ }
+
+ def fold[A](list: List[A])(implicit M: Monoid[A]): A = {
+ list.foldRight(M.empty)(M.combine)
+ }
+
+ val list: List[BigInt] = List(2, 3)
+ val res: BigInt = fold(list) // ?
+
+Here, the Scala compiler bails out with an *ambiguous implicits* error but for good reasons this time.
+Indeed, depending on which instance of ``Monoid[BigInt]`` it picks, ``res`` can either be equal to 5 or 6.
+This issue arise because the two instances above are *overlapping*, which has the effect of making the
+type system *incoherent*. For a type system to be coherent, "every valid typing derivation for a program
+must lead to a resulting program that has the same dynamic semantics", which is clearly not the case here.
+While in this specific example, the compiler will rightfully reject the program, this might always be
+possible as one could import a different instance in scope in two different modules, and then a third module
+might assume that these modules actually make use of the same instance, silently breaking the program.
+Imagine trying to merge two ``Sets`` that have been created with two different ``Ord`` instances in scope.
+
+Haskell partially solves this problem by enforcing that instances defined in the same module do not overlap,
+that is to say that the compiler would reject the program above. We deem Haskell's approach only partial as
+it allows the programmer to define two or more overlapping instances, provided that they are not defined in the same module.
+A program is then only rejected when the programmer makes imports such overlapping instances in scope and
+attempts to make use of them. This decision stems from the will to allow linking together two different
+libraries which both define a class instance for the same type.
+
+Because Stainless operates under a closed-world assumption, we could go further and disallow overlapping
+instances altogether, but this has not been implemented yet.
+
+One might still want to provide both an additive and multiplicative ``Monoid`` instance for integers.
+To this end, one can wrap values of type ``BigInt`` with two different wrapper classes for which
+we will define the respective instances:
+
+.. code-block:: scala
+
+ case class Sum(value: BigInt) extends AnyVal
+ case class Product(value: BigInt) extends AnyVal
+
+ implicit val bigIntSumMonoid: Monoid[Sum] = new Monoid[Sum] {
+ override def empty: Sum = Sum(0)
+ override def combine(x: Int, y: Int): Sum = Sum(x.value + y.value)
+ }
+
+ implicit val bigIntProductMonoid: Monoid[Product] = new Monoid[Product] {
+ override def empty: Product = Product(1)
+ override def combine(x: Int, y: Int): Product = Product(x.value * y.value)
+ }
+
+.. code-block:: scala
+
+ def foldMap[A, B](list: List[A])(f: A => B)(implicit M: Monoid[B]): B = {
+ list.map(f).foldRight(M.empty)(M.combine)
+ }
+
+It then becomes possible to unambiguously pick which instance to use depending on the semantics one wants:
+
+.. code-block:: scala
+
+ val list: List[BigInt] = List(2, 3)
+
+ val sum: BigInt = foldMap(list)(Sum(_)).value // 5
+ val product: BigInt = foldMap(list)(Product(_)).value // 6
+
+Under the hood
+--------------
+
+In this section we describe how laws are encoded within Stainless.
+
+Let's take as an example the Semigroup+Monoid hierarchy, slightly
+amended to exercise at once all the features described above.
+
+.. code-block:: scala
+
+ abstract class Semigroup[A] {
+ def append(x: A, y: A): A
+
+ @law
+ def law_associativity(x: A, y: A, z: A): Boolean = {
+ append(x, append(y, z)) == append(append(x, y), z)
+ }
+ }
+
+ abstract class Monoid[A] extends Semigroup[A] {
+ def empty: A
+
+ @law
+ def law_leftIdentity(x: A): Boolean = {
+ append(empty, x) == x
+ }
+
+ @law
+ def law_rightIdentity(x: A): Boolean = {
+ append(x, empty) == x
+ }
+
+ override def law_associativity(x: A, y: A, z: A): Boolean = {
+ // We refine the Semigroup associativity law with a dummy
+ // predicate `refineLaw` to demonstrate this feature.
+ super.law_associativity(x, y, z) && refineLaw(x, y, z)
+ }
+ }
+
+ def refineLaw[A](x: A, y: A, z: A): Boolean = true
+
+Together with a simple implementation for ``BigInt``:
+
+.. code-block:: scala
+
+ def bigIntAdditiveMonoid: Monoid[BigInt] = new Monoid[BigInt] {
+ def empty: BigInt = 0
+ def append(x: BigInt, y: BigInt): BigInt = x + y
+
+ override def law_rightIdentity(x: BigInt): Boolean = {
+ // no manual proof is needed in this case, but we include
+ // a dummy one for the sake of this example.
+ someProof
+ }
+ }
+
+ def someProof: Boolean = true
+
+Here is the internal Stainless AST pretty much right after extraction
+from the Scala compiler.
+
+Each symbol (class, method, variable) is annotated with its internal identifier
+(ie. the number after the ``$`` sign at the end of its name) which will prove useful
+for reading the code after the next phase, as it introduces new symbols with the same
+name but different identifiers.
+
+.. code-block:: scala
+
+ abstract class Semigroup$0[A$85] {
+
+ @abstract
+ def append$3(x$108: A$85, y$24: A$85): A$85 = [A$85]
+
+ @law
+ def law_associativity$0(x$109: A$85, y$25: A$85, z$11: A$85): Boolean = {
+ this.append$3(x$109, this.append$3(y$25, z$11)) ==
+ this.append$3(this.append$3(x$109, y$25), z$11)
+ }
+ }
+
+ abstract class Monoid$0[A$86] extends Semigroup$0[A$86] {
+
+ @abstract
+ def empty$6: A$86 = [A$86]
+
+ @law
+ def law_leftIdentity$0(x$110: A$86): Boolean =
+ this.append$3(this.empty$6, x$110) == x$110
+
+ @law
+ def law_rightIdentity$0(x$111: A$86): Boolean =
+ this.append$3(x$111, this.empty$6) == x$111
+
+ def law_associativity$1(x$112: A$86, y$26: A$86, z$12: A$86): Boolean =
+ super.law_associativity$0(x$112, y$26, z$12) && refineLaw$0[A$86](x$112, y$26, z$12)
+ }
+
+ def refineLaw$0[A$87](x$113: A$87, y$27: A$87, z$13: A$87): Boolean = true
+
+ case class $anon$0() extends Monoid$0[BigInt] {
+ def empty$7: BigInt = 0
+ def append$4(x$112: BigInt, y$26: BigInt): BigInt = x$112 + y$26
+
+ def law_rightIdentity$1(x$113: BigInt): Boolean = someProof$0
+ }
+
+ def bigIntAdditiveMonoid$0: Monoid$0[BigInt] = $anon$0()
+
+ def someProof$0: Boolean = true
+
+The code above maps in straightforward way to the original code.
+
+Let's now take a look at the output of the ``Laws`` phase. This is
+the phase which desugars the law definitions and their overrides
+into methods with explicit postconditions.
+
+.. code-block:: scala
+
+ abstract class Semigroup$0[A$85] {
+
+ @abstract
+ def append$3(x$108: A$85, y$24: A$85): A$85 = [A$85]
+
+ @final
+ @inlineOnce
+ @derived(law_associativity$0)
+ def law_associativity$2(x$120: A$85, y$30: A$85, z$14: A$85): Boolean = {
+ this.append$3(x$120, this.append$3(y$30, z$14)) ==
+ this.append$3(this.append$3(x$120, y$30), z$14)
+ }
+
+ @abstract
+ def law_associativity$0(x$109: A$85, y$25: A$85, z$11: A$85): Boolean = {
+ [Boolean]
+ } ensuring {
+ (res$82: Boolean) => res$82 && this.law_associativity$2(x$109, y$25, z$11)
+ }
+ }
+
+ abstract class Monoid$0[A$86] extends Semigroup$0[A$86] {
+
+ @abstract
+ def empty$6: A$86 = [A$86]
+
+ @final
+ @inlineOnce
+ @derived(law_leftIdentity$0)
+ def law_leftIdentity$1(x$116: A$86): Boolean =
+ this.append$3(this.empty$6, x$116) == x$116
+
+ @abstract
+ def law_leftIdentity$0(x$110: A$86): Boolean = {
+ [Boolean]
+ } ensuring {
+ (res$77: Boolean) => res$77 && this.law_leftIdentity$1(x$110)
+ }
+
+ @final
+ @inlineOnce
+ @derived(law_rightIdentity$0)
+ def law_rightIdentity$2(x$117: A$86): Boolean =
+ this.append$3(x$117, this.empty$6) == x$117
+
+ @abstract
+ def law_rightIdentity$0(x$111: A$86): Boolean = {
+ [Boolean]
+ } ensuring {
+ (res$80: Boolean) => res$80 && this.law_rightIdentity$2(x$111)
+ }
+
+ @law
+ def law_associativity$1(x$112: A$86, y$26: A$86, z$12: A$86): Boolean = {
+ this.law_associativity$2(x$112, y$26, z$12) && refineLaw$0[A$86](x$112, y$26, z$12)
+ } ensuring {
+ (res$84: Boolean) => res$84 && this.law_associativity$2(x$112, y$26, z$12)
+ }
+ }
+
+ @derived(bigIntAdditiveMonoid$0)
+ case class $anon$0() extends Monoid$0[BigInt] {
+
+ def empty$7: BigInt = 0
+ def append$4(x$114: BigInt, y$27: BigInt): BigInt = x$114 + y$27
+
+ @law
+ @derived(law_leftIdentity$0)
+ def law_leftIdentity$2(x$119: BigInt): Boolean = {
+ true
+ } ensuring {
+ (res$84: Boolean) => this.law_leftIdentity$1(x$119)
+ }
+
+ @law
+ def law_rightIdentity$1(x$115: BigInt): Boolean = {
+ someProof$0
+ } ensuring {
+ (res$79: Boolean) => res$79 && this.law_rightIdentity$2(x$115)
+ }
+
+ @law
+ @derived(law_associativity$0)
+ def law_associativity$2(x$120: BigInt, y$29: BigInt, z$13: BigInt): Boolean = {
+ true
+ } ensuring {
+ (res$85: Boolean) => this.law_associativity$1(x$120, y$29, z$13)
+ }
+ }
+
+ def bigIntAdditiveMonoid$0: Monoid$0[BigInt] = $anon$0()
+
+ def someProof$0: Boolean = true
+
+There are a few things going on here:
+
+1. First of all, each method marked ``@law`` introduces a new method which
+ holds the original body of the law. The law's body is then rewritten to
+ be empty, and is provided with a postcondition which refers to the newly
+ introduced method. This desugaring step basically turns the laws
+ into abstract methods which must be overridden at some point with
+ methods whose body can be proven to be true, while also satisfying the law
+ itself.
+
+ The helper method will be used in subsequent steps to refer to the
+ law's body, without having to inline it or call the law itself,
+ which is disallowed since it is conceptually an abstract method, as
+ evidenced by its newly added ``@abstract`` flag.
+
+ .. code-block:: scala
+
+ // In class `Semigroup`...
+
+ // This is the helper method.
+ @final
+ @inlineOnce
+ @derived(law_associativity$0)
+ def law_associativity$2(x$120: A$85, y$30: A$85, z$14: A$85): Boolean = {
+ this.append$3(x$120, this.append$3(y$30, z$14)) ==
+ this.append$3(this.append$3(x$120, y$30), z$14)
+ }
+
+ // This is the original law definition, which now became an abstract method.
+ @abstract
+ def law_associativity$0(x$109: A$85, y$25: A$85, z$11: A$85): Boolean = {
+ [Boolean]
+ } ensuring {
+ (res$82: Boolean) => res$82 && this.law_associativity$2(x$109, y$25, z$11)
+ }
+
+2. Laws which are overridden into abstract subclasses, are provided with a
+ postcondition that ensures that their body can be proven true,
+ while still satisfying the original law via a call to the helper
+ method introduced in the previous step. This step ensures that laws
+ cannot be fully redefined, and thus potentially weakened, in subclasses.
+
+ .. code-block:: scala
+
+ // In class `Monoid`...
+
+ @law
+ def law_associativity$1(x$112: A$86, y$26: A$86, z$12: A$86): Boolean = {
+ this.law_associativity$2(x$112, y$26, z$12) && refineLaw$0[A$86](x$112, y$26, z$12)
+ } ensuring {
+ (res$84: Boolean) => res$84 && this.law_associativity$2(x$112, y$26, z$12)
+ }
+
+3. In the typeclass implementations (eg. class ``$anon$0``), methods which override laws
+ are provided with a postcondition which again ensures that their body holds,
+ while still satisfying the law they override, again via a call to the helper
+ method introduced in step 1.
+
+ .. code-block:: scala
+
+ // In class `$anon$0`...
+
+ @law
+ def law_rightIdentity$1(x$115: BigInt): Boolean = {
+ someProof$0
+ } ensuring {
+ (res$79: Boolean) => res$79 && this.law_rightIdentity$2(x$115)
+ }
+
+4. If a law is not overridden in a typeclass implementation, a stub override is
+ automatically defined by Stainless, to ensure that a verification condition
+ will be generated. Those stubs just have ``true`` as a body, and a postcondition
+ which calls to the appropriate law helper introduced in step 1.
+ This expresses the fact that the law holds on its own, without any additional proof steps.
+
+ .. code-block:: scala
+
+ // In class `$anon$0`
+
+ @law
+ @derived(law_leftIdentity$0)
+ def law_leftIdentity$2(x$119: BigInt): Boolean = {
+ true
+ } ensuring {
+ (res$84: Boolean) => this.law_leftIdentity$1(x$119)
+ }
+
+.. note::
+
+ As can be seen above, calling the super method when refining (such as in ``law_associativity``)
+ or proving (such as in ``law_rightIdentity``) a law is superfluous, since it is done anyway
+ during the encoding as to ensure that laws cannot be weakened. Doing so can nonetheless help
+ readability, since it makes the code match more closely to the semantics of Scala.
+
+.. [WB89] P. Wadler and S. Blott. 1989. How to make ad-hoc polymorphism less ad hoc.
+
diff --git a/_sources/library.rst.txt b/_sources/library.rst.txt
new file mode 100644
index 0000000000..a78ce33add
--- /dev/null
+++ b/_sources/library.rst.txt
@@ -0,0 +1,388 @@
+.. _library:
+
+Stainless Library
+=================
+
+Stainless defines its own library with some core data types and
+operations on them, which work with the fragment supported
+by Stainless, available in ``frontends/library/stainless``, which
+we encourage the reader to consult as it is always up to date.
+
+One of the reasons for a separate library is to
+ensure that these operations can be correctly mapped to
+mathematical functions and relations inside of SMT solvers,
+largely defined by the SMT-LIB standard (see
+http://www.smt-lib.org/). Thus for some data types, such as
+``BigInt``, Stainless provides a dedicated mapping to support reasoning.
+(If you are a fan
+of growing the language only through libraries, keep in mind that
+growing operations together with the ability to reason about them
+is what the development of mathematical theories is all about, and
+is a process slower than putting together
+libraries of unverified code--efficient automation of reasoning about a
+single decidable theory generally results in multiple research papers.)
+For other operations (e.g., `List[T]`), the library
+is much like Stainless user-defined code, but specifies some
+useful preconditions and postconditions of the operations, thus
+providing reasoning abilities using mechanisms entirely available
+to the user.
+
+.. note::
+
+ The ScalaDoc for the library is `available online <_static/stainless-library/index.html>`_.
+
+ For the most up-to-date version of the source code of library,
+ please consult the ``library/`` directory in your Stainless distribution.
+
+To use Stainless' libraries, you need to use the appropriate
+`import` directive at the top of Stainless' compilation units.
+Here is a quick summary of what to import.
+
+
++--------------------------------+-----------------------------------------------------------------+
+| Package to import | What it gives access to |
++================================+=================================================================+
+| `stainless.annotation._` | Stainless annotations, e.g. @induct |
++--------------------------------+-----------------------------------------------------------------+
+| `stainless.lang._` | `Map`, `Set`, `PartialFunction`, `holds`, `passes`, `invariant` |
++--------------------------------+-----------------------------------------------------------------+
+| `stainless.collection._` | List[T] and subclasses, Option[T] and subclasses |
++--------------------------------+-----------------------------------------------------------------+
+
+To learn more, we encourage you to look in the `library/` subdirectory of Stainless distribution.
+
+Annotations
+-----------
+
+Stainless provides some special annotations in the package ``stainless.annotation``,
+which instruct Stainless to handle some functions or objects in a specialized way.
+
++-------------------+----------------------------------------------------------------+
+| Annotation | Meaning |
++===================+================================================================+
+| ``@library`` | Treat this object/function as library, don't try |
+| | to verify its specification. Can be overridden by |
+| | including a function name in the ``--functions`` |
+| | command line option. |
++-------------------+----------------------------------------------------------------+
+| ``@induct`` | Use the inductive tactic when generating |
+| | verification conditions. |
++-------------------+----------------------------------------------------------------+
+| ``@invariant`` | Treat the annotated method as an invariant of the enclosing |
+| | class. Can be used instead of ``require`` within a value class |
+| | body. For soundness, invariants can only refer to fields of |
+| | their class, and thus cannot call methods on ``this``. |
++-------------------+----------------------------------------------------------------+
+| ``@ghost`` | Drop the annotated field or method during compilation. |
+| | See the :doc:`corresponding section ` for more |
+| | information. |
++-------------------+----------------------------------------------------------------+
+| ``@extern`` | Only extract the contracts of a function, replacing |
+| | its body by a ``choose`` expression. |
++-------------------+----------------------------------------------------------------+
+| ``@opaque`` | Used to hide a function ``f``'s body when doing verification |
+| | of functions (``f`` itself, or others) invoking ``f``. Does |
+| | not hide pre and postconditions. |
++-------------------+----------------------------------------------------------------+
+| ``@dropVCs`` | Do not generate verification conditions for this function. |
++-------------------+----------------------------------------------------------------+
+| ``@pure`` | Specify that this function is pure, which will then |
+| | be checked. If the function is also annotated with |
+| | ``@extern``, it will not be checked, but assumed pure. |
++-------------------+----------------------------------------------------------------+
+| ``@ignore`` | Ignore this definition when extracting Stainless trees. |
+| | This annotation is useful to define functions |
+| | that are not in Stainless's language but will be |
+| | hard-coded into specialized trees, or to include |
+| | code written in full Scala which is not verifiable |
+| | by Stainless. Can also be used on class fields whose type |
+| | cannot be understood by Stainless, eg. because it comes from |
+| | an external library, the JDK, or some other code which |
+| | does not understand. |
+| | See the corresponding :doc:`documentation page `. |
++-------------------+----------------------------------------------------------------+
+| ``@inline`` | Inline this function. Stainless will refuse to inline |
+| | (mutually) recursive functions. |
++-------------------+----------------------------------------------------------------+
+| ``@inlineOnce`` | Inline this function but only once, which is allowed |
+| | even on (mutually) recursive functions. |
+| | Note: A recursive function will not be inlined within itself. |
++-------------------+----------------------------------------------------------------+
+| ``@partialEval`` | Partially evaluate calls to this function. |
+| | Note: ``stainless.lang.partialEval`` can also be used to |
+| | partially evaluate an expression. |
++-------------------+----------------------------------------------------------------+
+
+Stainless also has some special keywords defined in ``stainless.lang`` that can be used around
+function calls. `Here `_ is an example for ``unfold``.
+
++-------------------+----------------------------------------------------------------+
+| Annotation | Meaning |
++===================+================================================================+
+| ``inline`` | Call-site inlining |
++-------------------+----------------------------------------------------------------+
+| ``unfold`` | Inject an equality assumption between a function call and its |
+| | unfolded version. Can be useful to locally override an |
+| | ``@opaque`` annotation. |
++-------------------+----------------------------------------------------------------+
+
+List[T]
+-------
+
+As there is no special support for Lists in SMT solvers, Stainless Lists are encoded
+as an ordinary algebraic data type:
+
+.. code-block:: scala
+
+ sealed abstract class List[T]
+ case class Cons[T](h: T, t: List[T]) extends List[T]
+ case class Nil[T]() extends List[T]
+
+
+List API
+********
+
+Stainless Lists support a rich and strongly specified API.
+
++---------------------------------------------------+---------------------------------------------------+
+| Method signature for ``List[T]`` | Short description |
++===================================================+===================================================+
+| ``size: BigInt`` | Number of elements in this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``content: Set[T]`` | The set of elements in this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``contains(v: T): Boolean`` | Returns true if this List contains ``v``. |
++---------------------------------------------------+---------------------------------------------------+
+| ``++(that: List[T]): List[T]`` | Append this List with ``that``. |
++---------------------------------------------------+---------------------------------------------------+
+| ``head: T`` | Returns the head of this List. Can only be called |
+| | on a nonempty List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``tail: List[T]`` | Returns the tail of this List. Can only be called |
+| | on a nonempty List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``apply(index: BigInt): T`` | Return the element in index ``index`` in this |
+| | List (0-indexed). |
++---------------------------------------------------+---------------------------------------------------+
+| ``::(t:T): List[T]`` | Prepend an element to this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``:+(t:T): List[T]`` | Append an element to this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``reverse: List[T]`` | The reverse of this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``take(i: BigInt): List[T]`` | Take the first ``i`` elements of this List, or |
+| | the whole List if it has less than ``i`` elements.|
++---------------------------------------------------+---------------------------------------------------+
+| ``drop(i: BigInt): List[T]`` | This List without the first ``i`` elements, |
+| | or the Nil() if this List has less than ``i`` |
+| | elements. |
++---------------------------------------------------+---------------------------------------------------+
+| ``slice(from: BigInt, to: BigInt): List[T]`` | Take a sublist of this List, from index ``from`` |
+| | to index ``to``. |
++---------------------------------------------------+---------------------------------------------------+
+| ``replace(from: T, to: T): List[T]`` | Replace all occurrences of ``from`` in this List |
+| | with ``to``. |
++---------------------------------------------------+---------------------------------------------------+
+| ``chunks(s: BigInt): List[List[T]]`` | |
++---------------------------------------------------+---------------------------------------------------+
+| ``zip[B](that: List[B]): List[(T, B)]`` | Zip this list with ``that``. In case the Lists |
+| | do not have equal size, take a prefix of the |
+| | longer. |
++---------------------------------------------------+---------------------------------------------------+
+| ``-(e: T): List[T]`` | Remove all occurrences of ``e`` from this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``--(that: List[T]): List[T]`` | Remove all occurrences of any element in ``that`` |
+| | from this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``&(that: List[T]): List[T]`` | A list of all elements that occur both in |
+| | ``that`` and this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``pad(s: BigInt, e: T): List[T]`` | Add ``s`` instances of ``e`` at the end of this |
+| | List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``find(e: T): Option[BigInt]`` | Look for the element ``e`` in this List, and |
+| | optionally return its index if it is found. |
++---------------------------------------------------+---------------------------------------------------+
+| ``init: List[T]`` | Return this List except for the last element. |
+| | Can only be called on nonempty Lists. |
++---------------------------------------------------+---------------------------------------------------+
+| ``last: T`` | Return the last element of this List. |
+| | Can only be called on nonempty Lists. |
++---------------------------------------------------+---------------------------------------------------+
+| ``lastOption: Option[T]`` | Optionally return the last element of this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``headOption: Option[T]`` | Optionally return the first element of this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``unique: List[T]`` | Return this List without duplicates. |
++---------------------------------------------------+---------------------------------------------------+
+| ``splitAt(e: T): List[List[T]]`` | Split this List to chunks separated by an |
+| | occurrence of ``e``. |
++---------------------------------------------------+---------------------------------------------------+
+| ``split(seps: List[T]): List[List[T]]`` | Split this List in chunks separated by an |
+| | occurrence of any element in ``seps``. |
++---------------------------------------------------+---------------------------------------------------+
+| ``count(e: T): BigInt`` | Count the occurrences of ``e`` in this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``evenSplit: (List[T], List[T])`` | Split this List in two halves. |
++---------------------------------------------------+---------------------------------------------------+
+| ``insertAt(pos: BigInt, l: List[T]): List[T]`` | Insert an element after index ``pos`` in this |
+| | List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``replaceAt(pos: BigInt, l: List[T]): List[T]`` | Replace the ``l.size`` elements after index |
+| | ``pos``, or all elements after index ``pos`` |
+| | if there are not enough elements, |
+| | with the elements in ``l``. |
++---------------------------------------------------+---------------------------------------------------+
+| ``rotate(s: BigInt): List[T]`` | Rotate this list by ``s`` positions. |
++---------------------------------------------------+---------------------------------------------------+
+| ``isEmpty: Boolean`` | Returns whether this List is empty. |
++---------------------------------------------------+---------------------------------------------------+
+| ``map[R](f: T => R): List[R]`` | Builds a new List by applying a predicate ``f`` |
+| | to all elements of this list. |
++---------------------------------------------------+---------------------------------------------------+
+| ``foldLeft[R](z: R)(f: (R,T) => R): R`` | Applies the binary operator ``f`` to a start value|
+| | ``z`` and all elements of this List, going left |
+| | to right. |
++---------------------------------------------------+---------------------------------------------------+
+| ``foldRight[R](f: (T,R) => R)(z: R): R`` | Applies a binary operator ``f`` to all elements of|
+| | this list and a start value ``z``, going right to |
+| | left. |
++---------------------------------------------------+---------------------------------------------------+
+| ``scanLeft[R](z: R)(f: (R,T) => R): List[R]`` | Produces a List containing cumulative results |
+| | of applying the operator ``f`` going left to |
+| | right. |
++---------------------------------------------------+---------------------------------------------------+
+| ``scanRight[R](f: (T,R) => R)(z: R): List[R]`` | Produces a List containing cumulative results |
+| | of applying the operator ``f`` going right to |
+| | left. |
++---------------------------------------------------+---------------------------------------------------+
+| ``flatMap[R](f: T => List[R]): List[R]`` | Builds a new List by applying a function ``f`` |
+| | to all elements of this list and using the |
+| | elements of the resulting Lists. |
++---------------------------------------------------+---------------------------------------------------+
+| ``filter(p: T => Boolean): List[T]`` | Selects all elements of this List |
+| | which satisfy the predicate ``p`` |
++---------------------------------------------------+---------------------------------------------------+
+| ``forall(p: T => Boolean): Boolean`` | Tests whether predicate ``p`` holds |
+| | for all elements of this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``exists(p: T => Boolean): Boolean`` | Tests whether predicate ``p`` holds for some of |
+| | the elements of this List. |
++---------------------------------------------------+---------------------------------------------------+
+| ``find(p: T => Boolean): Option[T]`` | Finds the first element of this List satisfying |
+| | predicate ``p``, if any. |
++---------------------------------------------------+---------------------------------------------------+
+| ``takeWhile(p: T => Boolean): List[T]`` | Takes longest prefix of elements that satisfy |
+| | predicate ``p`` |
++---------------------------------------------------+---------------------------------------------------+
+
+Additional operations on Lists
+******************************
+
+The object ``ListOps`` offers this additional operations:
+
++--------------------------------------------------------+---------------------------------------------------+
+| Function signature | Short description |
++========================================================+===================================================+
+| ``flatten[T](ls: List[List[T]]): List[T]`` | Converts the List of Lists ``ls`` into a List |
+| | formed by the elements of these Lists. |
++--------------------------------------------------------+---------------------------------------------------+
+| ``isSorted(ls: List[BigInt]): Boolean`` | Returns whether this list of mathematical integers|
+| | is sorted in ascending order. |
++--------------------------------------------------------+---------------------------------------------------+
+| ``sorted(ls: List[BigInt]): List[BigInt]`` | Sorts this list of mathematical integers |
+| | is sorted in ascending order. |
++--------------------------------------------------------+---------------------------------------------------+
+| ``insSort(ls: List[BigInt], v: BigInt): List[BigInt]`` | Sorts this list of mathematical integers |
+| | is sorted in ascending order using insertion sort.|
++--------------------------------------------------------+---------------------------------------------------+
+
+Theorems on Lists
+*****************
+
+The following theorems on Lists have been proven by Stainless and are included
+in the object ``ListSpecs``:
+
++---------------------------------------------------------------+--------------------------------------------------------+
+| Theorem signature | Proven Claim |
++===============================================================+========================================================+
+| ``snocIndex[T](l: List[T], t: T, i: BigInt)`` | ``(l :+ t).apply(i) == (if (i < l.size) l(i) else t)`` |
++---------------------------------------------------------------+--------------------------------------------------------+
+| ``reverseIndex[T](l: List[T], i: BigInt)`` | ``l.reverse.apply(i) == l.apply(l.size - 1 - i)`` |
++---------------------------------------------------------------+--------------------------------------------------------+
+| ``appendIndex[T](l1: List[T], l2: List[T], i: BigInt)`` | ``(l1 ++ l2).apply(i) ==`` |
+| | ``(if (i < l1.size) l1(i) else l2(i - l1.size))`` |
++---------------------------------------------------------------+--------------------------------------------------------+
+| ``appendAssoc[T](l1: List[T], l2: List[T], l3: List[T])`` | ``((l1 ++ l2) ++ l3) == (l1 ++ (l2 ++ l3))`` |
++---------------------------------------------------------------+--------------------------------------------------------+
+| ``snocIsAppend[T](l: List[T], t: T)`` | ``(l :+ t) == l ++ Cons[T](t, Nil())`` |
++---------------------------------------------------------------+--------------------------------------------------------+
+| ``snocAfterAppend[T](l1: List[T], l2: List[T], t: T)`` | ``(l1 ++ l2) :+ t == (l1 ++ (l2 :+ t))`` |
++---------------------------------------------------------------+--------------------------------------------------------+
+| ``snocReverse[T](l: List[T], t: T)`` | ``(l :+ t).reverse == Cons(t, l.reverse)`` |
++---------------------------------------------------------------+--------------------------------------------------------+
+| ``reverseReverse[T](l: List[T])`` | ``l.reverse.reverse == l`` |
++---------------------------------------------------------------+--------------------------------------------------------+
+| ``scanVsFoldRight[A,B](l: List[A], z: B, f: (A,B) => B)`` | ``l.scanRight(f)(z).head == l.foldRight(f)(z)`` |
++---------------------------------------------------------------+--------------------------------------------------------+
+
+Set[T], Map[T]
+--------------
+
+Stainless uses its own Sets and Maps, which are defined in the ``stainless.lang`` package.
+However, these classes are not implemented within Stainless.
+Instead, they are parsed into specialized trees.
+Methods of these classes are mapped to specialized trees within SMT solvers.
+For code generation, we rely on Java Sets and Maps.
+
+The API of these classes is a subset of the Scala API and can be found
+in the :doc:`purescala` section.
+
+Additionally, the following functions for Sets are provided in the
+``stainless.collection`` package:
+
+
++-----------------------------------------------------------+-------------------------------------------+
+| Function signature | Short description |
++===========================================================+===========================================+
+| ``setToList[A](set: Set[A]): List[A]`` | Transforms the Set ``set`` into a List. |
++-----------------------------------------------------------+-------------------------------------------+
+| ``setForall[A](set: Set[A], p: A => Boolean): Boolean`` | Tests whether predicate ``p`` holds |
+| | for all elements of Set ``set``. |
++-----------------------------------------------------------+-------------------------------------------+
+| ``setExists[A](set: Set[A], p: A => Boolean): Boolean`` | Tests whether predicate ``p`` holds |
+| | for all elements of Set ``set``. |
++-----------------------------------------------------------+-------------------------------------------+
+
+
+PartialFunction[A, B]
+---------------------
+
+To define anonymous functions with preconditions, Stainless has a ``PartialFunction[A, B]`` type
+with the corresponding annotation ``A ~> B``. To construct a partial function, you must use
+``PartialFunction.apply`` as in the ``unOpt`` function below. The precondition written in the
+``require`` becomes the ``pre`` field of the partial function (as in the call to ``f.pre`` in ``map1``).
+
+.. code-block:: scala
+
+ def map1[A, B](l: List[A], f: A ~> B): List[B] = {
+ require(l.forall(f.pre))
+ l match {
+ case Cons(x, xs) => Cons[B](f(x), map1(xs, f))
+ case Nil() => Nil[B]()
+ }
+ }
+
+ def unOpt[T](l: List[Option[T]]): List[T] = {
+ require(l.forall(_.nonEmpty))
+ map1(l, PartialFunction {(x:Option[T]) => require(x.nonEmpty); x.get})
+ }
+
+Partial functions can also be written using pattern matching:
+
+.. code-block:: scala
+
+ def unOptCase[T](l: List[Option[T]]): List[T] = {
+ require(l.forall { case Some(_) => true; case _ => false })
+ map1(l, PartialFunction[Option[T], T] { case Some(v) => v })
+ }
diff --git a/_sources/limitations.rst.txt b/_sources/limitations.rst.txt
new file mode 100644
index 0000000000..4f332629fd
--- /dev/null
+++ b/_sources/limitations.rst.txt
@@ -0,0 +1,40 @@
+.. _limitations:
+
+Limitations of Verification
+---------------------------
+
+A goal of Stainless is to ensure that proven properties hold in
+all program executions so that, for example, verified programs
+do not crash and all of the preconditions and postconditions
+are true in all executions.
+For this to be the case, there needs
+to be a precise correspondence between runtime execution
+semantics and the semantics used in verification, including
+the SMT solvers invoked.
+
+Below we document several cases where we are aware that the
+discrepancy exists and provide suggested workarounds.
+
+Out of Memory Errors
+^^^^^^^^^^^^^^^^^^^^
+
+By default, Stainless assumes that unbounded data types can
+be arbitrarily large and that all well-founded recursive
+functions have enough stack space to finish their computation.
+Thus a verified program may crash at run-time due to:
+
+ * stack overflow
+ * heap overflow
+
+The set of values for recursive algebraic data types is assumed to be infinite.
+In any given execution, there will be actual bounds on the
+total available memory. The program could thus crash
+with an out-of-memory error when trying to allocate another
+value of algebraic data type.
+
+For a safety critical application you may wish to resort to
+tail-recursive programs only, and also write preconditions
+and postconditions that enforce a bound on the maximum size
+of the data structures that your application
+manipulates. For this purpose, you can define size functions
+that return `BigInt` data types.
diff --git a/_sources/neon.rst.txt b/_sources/neon.rst.txt
new file mode 100644
index 0000000000..866dbfe454
--- /dev/null
+++ b/_sources/neon.rst.txt
@@ -0,0 +1,1039 @@
+.. _neon:
+
+Proving Theorems
+================
+
+Verifying the contract of a function is really proving a mathematical
+theorem. Stainless can be seen as a (mostly) automated theorem prover. It is
+automated in the sense that once the property stated, Stainless will proceed with searching
+for a proof without any user interaction. In practice, however, many theorems will be fairly
+difficult to prove, and it is possible for the user to provide hints to Stainless.
+
+Hints typically take the form of simpler properties that combine in order to prove
+more complicated ones. In the remaining subsections, we provide code patterns and introduce
+simple domain-specific language operators that can help in constructing complex Stainless proofs.
+
+A practical introduction to proofs
+----------------------------------
+
+When writing logical propositions such as preconditions or
+postconditions in Stainless, one is basically writing Boolean
+predicates. They can be as simple as testing whether a list is empty
+or not, to more complex combinations of properties. Lemmas or
+theorems are simply logical tautologies, that is, propositions that
+always hold. They can be expressed using Boolean-valued methods that
+return ``true`` for all their inputs.
+
+To make this more concrete, let's take a simple lemma as an
+example [#example-dir]_. Here we want to prove that the append operation (``++``) on
+lists preserves the content of the two lists being concatenated. This
+proposition is relatively straightforward and Stainless is able to verify
+that it always holds.
+
+.. code-block:: scala
+
+ import stainless.collection._ // for List
+ import stainless.lang._ // for holds
+
+ object Example {
+ def appendContent[A](l1: List[A], l2: List[A]): Boolean = {
+ l1.content ++ l2.content == (l1 ++ l2).content
+ }.holds
+ }
+
+Here we wrote ``.holds`` which is a method implicitly available on ``Boolean``
+that ensure the returned value is ``true``. It is equivalent to writing
+``ensuring { res => res }``.
+
+Now let's look at another example that looks trivial but for which Stainless
+needs some help with the proof: we want to prove that adding ``Nil``
+at the end of a list has no effect.
+
+.. code-block:: scala
+
+ import stainless.collection._ // for List
+ import stainless.lang._ // for holds
+
+ object Example {
+ def rightUnitAppend[T](l1: List[T]): Boolean = {
+ l1 ++ Nil() == l1
+ }.holds
+ }
+
+If you try to verify this last example you'll face a delicate
+situation: Stainless runs indeterminately until it is either killed or
+times out. But why does this happen? The proposition doesn't seem
+more complicated than ``appendContent``. Perhaps even more
+surprisingly, Stainless *is* able to verify the following:
+
+.. code-block:: scala
+
+ def leftUnitAppend[T](l1: List[T]): Boolean = {
+ Nil() ++ l1 == l1
+ }.holds
+
+How is this possible? The two propositions are completely symmetric!
+The problem is that Stainless doesn't know anything about lists, a priori.
+It can only reason about lists thanks to their definition in terms of
+the case classes ``Cons`` and ``Nil`` and associated methods such as
+``++``. In particular, Stainless doesn't know that ``Nil`` represents the
+empty list, and hence that appending it to some other list is a no-op.
+What then, is the difference between the two examples above? To
+answer this question, we need to have a look at the definition of the
+``++`` method:
+
+.. code-block:: scala
+
+ def ++(that: List[T]): List[T] = (this match {
+ case Nil() => that
+ case Cons(x, xs) => Cons(x, xs ++ that)
+ }) ensuring { res => /* ... */ }
+
+Note that the implementation of ``++`` is recursive in its first
+argument ``this`` but *not* in its second argument ``that``. This is
+why Stainless was able to verify ``leftUnitAppend`` easily: it is true *by
+definition*, i.e. ``Nil() ++ l1`` is actually defined to be ``l1``.
+What about the symmetric case? How is ``l1 ++ Nil()`` defined? Well,
+it depends on whether ``l1`` is the empty list or not. So in order to
+prove ``rightUnitAppend``, we need to proceed with a case analysis. The
+resulting proof has a recursive (i.e. inductive) structure reminiscent
+of the definition of ``++``:
+
+.. code-block:: scala
+
+ import stainless.collection._ // for List
+ import stainless.lang._ // for holds
+ import stainless.proof._ // for because
+
+ object Example {
+ def rightUnitAppend[T](l1: List[T]): Boolean = {
+ (l1 ++ Nil() == l1) because {
+ l1 match {
+ case Nil() => true
+ case Cons(x, xs) => rightUnitAppend(xs)
+ }
+ }
+ }.holds
+ }
+
+With this new implementation of the ``rightUnitAppend`` lemma, Stainless is capable
+of verifying that it holds. If you look closely at it, you can distinguish three
+parts:
+
+1. the claim we want to prove ``l1 ++ Nil() == l1``;
+2. ``because``, which is just some syntactic sugar for conjunction -- remember,
+ every proposition is a Boolean formula;
+3. and a recursion on ``l1`` that serves as a hint for Stainless to perform
+ induction.
+
+The recursion is based here on pattern matching, which Stainless will also check for
+exhaustiveness. It has essentially the same structure as
+the implementation of ``++``: the base case is when ``l1`` is the empty list
+and the inductive case is performed on ``Cons`` objects.
+
+
+Techniques for proving non-trivial propositions
+-----------------------------------------------
+
+In the previous section, we saw that "proof hints" can improve the odds
+of Stainless successfully verifying a given proposition. In this section,
+we will have a closer look at what constitutes such a proof and
+discuss a few techniques for writing them.
+
+As mentioned earlier, propositions are represented by Boolean
+expressions in Stainless. But how are proofs represented? They are just
+Boolean expressions as well [#props-not-types]_. The difference
+between propositions and proofs is not their representation, but how
+they are used by Stainless. Intuitively, a proof ``p: Boolean`` for a
+proposition ``x: Boolean`` is an expression such that
+
+ 1. Stainless is able to verify ``p``, and
+ 2. Stainless is able to verify that ``p`` implies ``x``.
+
+This is what we mean when we say that proofs are "hints". Typically,
+a proof ``p`` of a proposition ``x`` is a more complex-looking but
+equivalent version of ``x``, i.e. an expression such that ``p == x``.
+This might seem a bit counter-intuitive: why should it be easier for
+Stainless to verify an equivalent but more complex expression? The answer
+is that the more complex version may consist of sub-expressions that
+more closely resemble the definitions of functions used in ``x``. We
+have already seen an example of this principle in the previous
+section: let's have another look at the proof of ``rightUnitAppend``:
+
+.. code-block:: scala
+
+ def rightUnitAppend[T](l1: List[T]): Boolean = {
+ val x = l1 ++ Nil() == l1
+ val p = l1 match {
+ case Nil() => true
+ case Cons(x, xs) => rightUnitAppend(xs)
+ }
+ x because p
+ }.holds
+
+Here, we have rewritten the example to make the distinction between
+the proposition ``x`` and its proof ``p`` more explicit. It's easy to
+check that indeed ``x == p``, and hence the overall result of
+``rightUnitAppend`` is equivalent to ``x`` (recall that ``because`` is
+just an alias of ``&&``, so ``(x because p) == (x && x) == x``).
+However, the proof term ``p`` closely resembles the definition of
+``++`` and its sub-expressions are easier to verify for Stainless than
+``x`` itself. The only non-trivial expression is the recursive call
+to ``rightUnitAppend(xs)``, which serves as the inductive hypothesis.
+We will discuss induction in more detail in Section
+":ref:`induction`".
+
+
+Divide and Conquer
+******************
+
+Before we delve into the details of particular proof techniques, it is
+worth revisiting a guiding principle for writing proofs -- whether it
+be in Stainless, by hand, or using some other form of mechanized proof
+checker -- namely to *modularize* proofs, i.e. to split the proofs of
+complex propositions into manageable *sub-goals*. This can be
+achieved in various ways.
+
+ * Use *helper lemmas* -- these are propositions that are lemmas on
+ their own, i.e. they state and prove simple but self-contained
+ propositions that can be reused elsewhere. As such, they play a
+ role akin to helper methods in normal programming, and indeed, are
+ implemented in the same way, except that they carry a ``.holds``
+ suffix.
+
+ * Use *case analysis* to split complex propositions into simpler
+ sub-cases. This is especially helpful in the presence of
+ recursion, where it leads to inductive proofs (see Section
+ ":ref:`induction`").
+
+ * Use *relational reasoning* to split complex relationships into
+ conjunctions of elementary ones. This often requires one to make
+ use of relational properties such as transitivity (e.g. to break a
+ single equation ``a == b`` into a chain of equations ``a == x1 &&
+ x1 == x2 && ... && xN == b``), symmetry (e.g. to use a previously
+ proven inequality ``a <= b`` where ``b >= a`` is expected),
+ anti-symmetry (to unify variables), and so on (see Section
+ ":ref:`rel-reasoning`").
+
+ * Separate specification form implementation. It is sometimes easier
+ to prove the fact that a given function fulfills its specification
+ as a separate lemma (although the proof techniques are roughly the
+ same, see Section ":ref:`post-cond`").
+
+ * Generalize (or specialize) propositions. Sometimes, propositions
+ are more easily proved in a stronger (or weaker) form and
+ subsequently instantiated (or combined with other propositions) to
+ yield a proof of the original proposition.
+
+While it is good practice to factor common propositions into helper
+lemmas, one sometimes wants to verify simple, specific sub-goals in a
+proof without going through the trouble of introducing an additional
+method. This is especially true while one is exploring the branches
+of a case analysis or wants to quickly check whether Stainless is able to
+prove a seemingly trivial statement automatically (we will see
+examples of such situations in the coming sections). For such cases,
+one can use the ``check`` function from ``stainless.proof``. The ``check``
+function behaves as the identity function on Booleans but additionally
+assumes its argument in its precondition. As a result, Stainless will
+check that ``x`` holds while verifying the call to ``check(x)``.
+For example, when verifying the following function:
+
+.. code-block:: scala
+
+ import stainless.proof.check
+
+ def foo(x: BigInt): Boolean = {
+ check(x >= 0 || x < 0) && check(x + 0 == 0)
+ }
+
+Stainless will check (separately) that ``x >= 0 || x < 0`` and ``x + 0 ==
+0`` hold for all ``x``, even though the function ``foo`` does not
+specify any pre or postconditions, and report a counter example for
+the second case::
+
+ [ Info ] - Now considering 'precond. (call check(x >= 0 || x < 0))' VC for foo @40:5...
+ [ Info ] => VALID
+ [ Info ] - Now considering 'precond. (call check(x + 0 == 0))' VC for foo @40:31...
+ [ Error ] => INVALID
+ [ Error ] Found counter-example:
+ [ Error ] x -> 1
+
+This is especially helpful when "debugging" proofs.
+
+
+.. _proofcontrol:
+
+Proof control using ``assert`` and ``check``
+********************************************
+
+Both the ``assert`` and ``check`` keywords generate a verification condition for
+the corresponding formula in the current context. The difference in these
+keywords is in how they affect the context of other verification conditions. As
+a rule of thumb, assertions do not affect the context of verification conditions
+outside the block of the assertion, while ``check`` does. Thus you can use
+assertions to prove local properties, and use ``check`` to have the property
+(checked and) visible outside the block.
+
+.. code-block:: scala
+
+ def foo(): Unit = {
+ val x = {
+ assert(b1) // verification condition: b1
+ check(b2) // verification condition: b1 ==> b2
+ }
+ assert(b3) // verification condition: b2 ==> b3 (b1 not visible to the solver)
+ }
+
+Similarly, ``assert``'s are not guaranteed to be visible when generating
+verification conditions for postconditions, while ``check``'s are.
+
+.. code-block:: scala
+
+ def foo(): Unit = {
+ assert(b1) // verification condition: b1
+ check(b2) // verification condition: b1 ==> b2
+ }.ensuring(_ => b3) // verification condition b2 ==> b3 (b1 might not be visible to the solver)
+
+
+.. _induction:
+
+Induction
+*********
+
+The vast majority of functional programs are written as functions over
+:ref:`ADTs `, and consequently, Stainless comes with some special
+support for verifying properties of ADTs. Among other things, Stainless
+provides an annotation ``@induct``, which can be used to automatically
+prove postconditions of recursive functions defined on ADTs by way of
+*structural induction*. We have already seen an example of such an
+inductive property, namely ``rightUnitAppend``. In fact, using
+``@induct``, Stainless is able to prove ``rightUnitAppend`` directly:
+
+.. code-block:: scala
+
+ import stainless.annotation._ // for @induct
+
+ @induct
+ def rightUnitAppend[T](l1: List[T]): Boolean = {
+ l1 ++ Nil() == l1
+ }.holds
+
+This is possible because the inductive step follows (more or less)
+directly from the inductive hypothesis and Stainless can verify the base
+case automatically. However, Stainless may fail to verify more complex
+functions with non-trivial base cases or inductive steps. In such
+cases, one may still try to provide proof hints by performing *manual
+case analysis*. Consider the following lemma about list reversal:
+
+.. code-block:: scala
+
+ import stainless.collection._ // for List
+ import stainless.lang._ // for holds
+
+ object Example {
+ def reverseReverse[T](l: List[T]): Boolean = {
+ l.reverse.reverse == l
+ }.holds
+ }
+
+Stainless is unable to verify ``reverseReverse`` even using ``@induct``.
+So let's try and prove the lemma using manual case analysis. We start
+by adding an "unrolled" version of the proposition and inserting calls
+to ``check`` in each branch of the resulting pattern match:
+
+.. code-block:: scala
+
+ def reverseReverse[T](l: List[T]): Boolean = {
+ l.reverse.reverse == l because {
+ l match {
+ case Nil() => check { Nil[T]().reverse.reverse == Nil[T]() }
+ case Cons(x, xs) => check { (x :: xs).reverse.reverse == (x :: xs) }
+ }
+ }
+ }.holds
+
+Clearly, the two versions of the lemma are equivalent: all we did was
+expand the proposition using a pattern match and add some calls to
+``check`` (remember ``check`` acts as the identity function on its
+argument). Let's see what output Stainless produces for the expanded
+version::
+
+ [ Info ] - Now considering 'postcondition' VC for reverseReverse @615:5...
+ [Warning ] => UNKNOWN
+ [ Info ] - Now considering 'precond. (call check(List[T]().reverse().reverse() ...)' VC for reverseReverse @617:28...
+ [ Info ] => VALID
+ [ Info ] - Now considering 'precond. (call check({val x$27 = l.h; ...)' VC for reverseReverse @618:28...
+ [Warning ] => UNKNOWN
+ [ Info ] - Now considering 'match exhaustiveness' VC for reverseReverse @616:7...
+ [ Info ] => VALID
+
+As expected, Stainless failed to verify the expanded version. However, we
+get some additional information due to the extra pattern match and the
+calls to ``check``. In particular, Stainless tells us that the match is
+exhaustive, which means we covered all the cases in our case analysis
+-- that's certainly a good start. Stainless was also able to automatically
+verify the base case, so we can either leave the call to ``check`` as
+is, or replace it by ``trivial``. Unfortunately, Stainless wasn't able to
+verify the inductive step, something is missing. Let's try to
+manually reduce the inductive case and see where we get.
+
+.. code-block:: scala
+
+ def reverseReverse[T](l: List[T]): Boolean = {
+ l.reverse.reverse == l because {
+ l match {
+ case Nil() => trivial
+ case Cons(x, xs) => check { (xs.reverse :+ x).reverse == (x :: xs) }
+ }
+ }
+ }.holds
+
+And now we're stuck. We can't apply the inductive hypothesis here,
+nor can we reduce the inductive case further, unless we perform
+case analysis on ``xs``, which would grow the term further without
+changing its shape. To make any headway, we need to use an additional
+property of ``reverse``, given by the following lemma (which Stainless *is*
+able to prove using ``@induct``):
+
+.. code-block:: scala
+
+ @induct
+ def snocReverse[T](l: List[T], t: T): Boolean = {
+ (l :+ t).reverse == t :: l.reverse
+ }.holds
+
+The lemma states that appending an element ``t`` to a list ``l`` and
+reversing it is equivalent to first reversing ``l`` and then
+prepending ``t``. Using this lemma, we can write the proof of
+``reverseReverse`` as
+
+.. code-block:: scala
+
+ def reverseReverse[T](l: List[T]): Boolean = {
+ l.reverse.reverse == l because {
+ l match {
+ case Nil() => trivial
+ case Cons(x, xs) => check {
+ (xs.reverse :+ x).reverse == x :: xs.reverse.reverse &&
+ x :: xs.reverse.reverse == (x :: xs) because
+ snocReverse(xs.reverse, x) && reverseReverse(xs)
+ }
+ }
+ }
+ }.holds
+
+Stainless is able to verify this version of the lemma. Note that Stainless
+doesn't actually require us to include the two equations as they are
+equivalent to the applications ``snocReverse(xs.reverse, x)`` and
+``reverseReverse(xs)``. Similarly, the call to ``check`` is somewhat
+redundant now that Stainless is able to verify the entire proof. We could
+thus "simplify" the above to
+
+.. code-block:: scala
+
+ def reverseReverse[T](l: List[T]): Boolean = {
+ l.reverse.reverse == l because {
+ l match {
+ case Nil() => trivial
+ case Cons(x, xs) => snocReverse(xs.reverse, x) && reverseReverse(xs)
+ }
+ }
+ }.holds
+
+However, the previous version is arguably more readable for a human
+being, and therefore preferable. In Section ":ref:`rel-reasoning`" we
+will see how readability can be improved even further through the use
+of a DSL for equational reasoning.
+
+So far, we have only considered structurally inductive proofs.
+However, Stainless is also able to verify proofs using *natural induction*
+-- the form of induction that is perhaps more familiar to most
+readers. Consider the following definition of the exponential
+function :math:`exp(x, y) = x^y` over integers:
+
+.. code-block:: scala
+
+ def exp(x: BigInt, y: BigInt): BigInt = {
+ require(y >= 0)
+ if (x == 0) 0
+ else if (y == 0) 1
+ else x * exp(x, y - 1)
+ }
+
+The function ``exp`` is again defined recursively, but this time using
+``if`` statements rather than pattern matching. Let's try and prove
+some properties of this function using natural induction. One such
+property is that for any pair of positive numbers :math:`x, y \geq 0`,
+the exponential :math:`x^y` is again a positive number.
+
+.. code-block:: scala
+
+ def positive(x: BigInt, y: BigInt): Boolean = {
+ require(y >= 0 && x >= 0)
+ exp(x, y) >= 0
+ }
+
+Since Stainless doesn't know anything about exponentials, it isn't able to
+verify the lemma without hints. As with the previous example, we
+start writing our inductive proof by expanding the top-level ``if``
+statement in the definition of ``exp``.
+
+.. code-block:: scala
+
+ def positive(x: BigInt, y: BigInt): Boolean = {
+ require(y >= 0 && x >= 0)
+ exp(x, y) >= 0 because {
+ if (x == 0) check { exp(x, y) >= 0 } // <-- valid
+ else if (y == 0) check { exp(x, y) >= 0 } // <-- valid
+ else check { exp(x, y) >= 0 } // <-- unknown
+ }
+ }.holds
+
+Stainless was able to verify the first two (base) cases, but not the
+inductive step, so let's continue unfolding ``exp`` for that case.
+
+.. code-block:: scala
+
+ def positive(x: BigInt, y: BigInt): Boolean = {
+ require(y >= 0 && x >= 0)
+ exp(x, y) >= 0 because {
+ if (x == 0) trivial
+ else if (y == 0) trivial
+ else check { x * exp(x, y - 1) >= 0 }
+ }
+ }.holds
+
+Although Stainless still isn't able to verify the lemma, we now see a way
+to prove the inductive step: ``x`` is positive (by the second
+precondition) and so is ``exp(x, y - 1)`` (by the inductive
+hypothesis). Hence the product ``x * exp(x, y - 1)`` is again
+positive.
+
+.. code-block:: scala
+
+ def positive(x: BigInt, y: BigInt): Boolean = {
+ require(y >= 0 && x >= 0)
+ exp(x, y) >= 0 because {
+ if (x == 0) trivial
+ else if (y == 0) trivial
+ else check {
+ x >= 0 && exp(x, y - 1) >= 0 because positive(x, y - 1)
+ }
+ }
+ }.holds
+
+With these hints, Stainless is able to verify the proof. Again, we could
+shorten the proof by omitting inequalities that Stainless can infer
+directly, albeit at the expense of readability.
+
+.. code-block:: scala
+
+ def positiveShort(x: BigInt, y: BigInt): Boolean = {
+ require(y >= 0 && x > 0)
+ exp(x, y) >= 0 because {
+ if (x == 0) trivial
+ else if (y == 0) trivial
+ else positiveShort(x, y - 1)
+ }
+ }.holds
+
+We conclude the section with the inductive proof of another, somewhat
+more interesting property of the exponential function, namely that
+:math:`(x y)^z = x^z y^z`.
+
+.. code-block:: scala
+
+ def expMultCommute(x: BigInt, y: BigInt, z: BigInt): Boolean = {
+ require(z >= 0)
+ exp(x * y, z) == exp(x, z) * exp(y, z) because {
+ if (x == 0) trivial
+ else if (y == 0) trivial
+ else if (z == 0) trivial
+ else check {
+ x * y * exp(x * y, z - 1) ==
+ x * exp(x, z - 1) * y * exp(y, z - 1) because
+ expMultCommute(x, y, z - 1)
+ }
+ }
+ }.holds
+
+.. _rel-reasoning:
+
+Relational reasoning
+********************
+
+The majority of the example propositions we have seen so far related
+some expression (e.g. ``l.reverse ++ Nil()`` or ``exp(x, y)``) to some
+other expression (e.g. ``... == l1`` or ``... >= 0``). This is
+certainly a common case among the sorts of propositions about
+functions and data structures one might wish to prove. The proofs of
+such propositions typically involve some form of *relational
+reasoning*, i.e. reasoning involving properties (such as transitivity,
+reflexivity or symmetry) of the relations in question. Stainless knows
+about these properties for built-in relations such as ``==`` or orders
+on numbers. For user-defined relations, they first need to be
+established as lemmas. In this section, we discuss how to make
+effective use of built-in relations, but the general principles extend
+to their user-defined counterparts.
+
+When working with simple structural equality, we can rely on the default ``==``
+operator and Stainless will happily understand when the reflexivity, symmetry and
+transitivity properties apply and use them to conclude bigger proofs. Similarly,
+when working on ``BigInt``, Stainless knows about reflexivity, antisymmetry and
+transitivity over ``>=`` or ``<=``, and also antireflexivity, antisymmetry
+and transitivity of ``>`` and ``<``.
+
+However, even for relatively simple proofs about ADTs, Stainless needs
+hints when combining, say equality, with user-defined operations, such
+as ``++`` or ``reverse`` on lists. For example, Stainless is not able to
+verify that the following holds for arbitrary pairs of lists ``l1``
+and ``l2``:
+
+.. code-block:: scala
+
+ (l1 ++ l2).reverse == l2.reverse ++ l1.reverse
+
+The hard part of giving hints to Stainless is often to find them in the
+first place. Here we can apply a general principle on top of
+structural induction (as discussed in the previous section): we start
+from the left-hand side of an equation and build a chain of
+intermediate equations to the right-hand side. Using ``check``
+statements we can identify where Stainless times out and hence potentially
+needs hints.
+
+.. code-block:: scala
+
+ def reverseAppend[T](l1: List[T], l2: List[T]): Boolean = {
+ ( (l1 ++ l2).reverse == l2.reverse ++ l1.reverse ) because {
+ l1 match {
+ case Nil() =>
+ /* 1 */ check { (Nil() ++ l2).reverse == l2.reverse } &&
+ /* 2 */ check { l2.reverse == l2.reverse ++ Nil() } &&
+ /* 3 */ check { l2.reverse ++ Nil() == l2.reverse ++ Nil().reverse }
+ case Cons(x, xs) =>
+ /* 4 */ check { ((x :: xs) ++ l2).reverse == (x :: (xs ++ l2)).reverse } &&
+ /* 5 */ check { (x :: (xs ++ l2)).reverse == (xs ++ l2).reverse :+ x } &&
+ /* 6 */ check { (xs ++ l2).reverse :+ x == (l2.reverse ++ xs.reverse) :+ x } &&
+ /* 7 */ check { (l2.reverse ++ xs.reverse) :+ x == l2.reverse ++ (xs.reverse :+ x) } &&
+ /* 8 */ check { l2.reverse ++ (xs.reverse :+ x) == l2.reverse ++ (x :: xs).reverse }
+ }
+ }
+ }.holds
+
+If we run the above code with a decent timeout, Stainless reports four
+*UNKNOWN* cases: the postcondition of the ``reverseAppend`` function itself and
+checks number 2, 6 and 7.
+
+ * Check #2 fails because, as we saw earlier, Stainless is not capable of
+ guessing the ``rightUnitAppend`` lemma by itself. We fix this case
+ by simply instantiating the lemma, i.e. by appending ``&&
+ rightUnitAppend(l2.reverse)`` to the base case.
+
+ * Check #6 fails because, at this point, we need to inject the
+ induction hypothesis on ``xs`` and ``l2`` by adding ``&&
+ reverseAppend(xs, l2)``.
+
+ * Finally, check #7 fails for a similar reason as check #2: we need
+ an additional "associativity" lemma to prove that ``(l1 ++ l2) :+ t
+ == l1 ++ (l2 :+ t)`` holds for any ``l1``, ``l2`` and ``t``. We
+ call this lemma ``snocAfterAppend`` and leave it as an exercise for
+ the reader.
+
+Once we have a valid proof, we can try to optimize it for readability.
+As it stands, the resulting code is rather verbose because both sides
+of most equations are duplicated. One option is to completely remove
+the equations (they are implied by the instantiations of the lemmas)
+and simply write
+
+.. code-block:: scala
+
+ def reverseAppend[T](l1: List[T], l2: List[T]): Boolean = {
+ ( (l1 ++ l2).reverse == l2.reverse ++ l1.reverse ) because {
+ l1 match {
+ case Nil() =>
+ rightUnitAppend(l2.reverse)
+ case Cons(x, xs) =>
+ reverseAppend(xs, l2) && snocAfterAppend(l2.reverse, xs.reverse, x)
+ }
+ }
+ }.holds
+
+Or we can employ the equational reasoning DSL provided by the
+``stainless.proofs`` package to remove the duplicate expressions and
+interleave the equations with their associated proofs. This has the
+advantage of not losing information that is still useful for a human
+being reading the proof later on:
+
+.. code-block:: scala
+
+ def reverseAppend[T](l1: List[T], l2: List[T]): Boolean = {
+ ( (l1 ++ l2).reverse == l2.reverse ++ l1.reverse ) because {
+ l1 match {
+ case Nil() => {
+ (Nil() ++ l2).reverse ==| trivial |
+ l2.reverse ==| rightUnitAppend(l2.reverse) |
+ l2.reverse ++ Nil() ==| trivial |
+ l2.reverse ++ Nil().reverse
+ }.qed
+ case Cons(x, xs) => {
+ ((x :: xs) ++ l2).reverse ==| trivial |
+ (x :: (xs ++ l2)).reverse ==| trivial |
+ (xs ++ l2).reverse :+ x ==| reverseAppend(xs, l2) |
+ (l2.reverse ++ xs.reverse) :+ x ==|
+ snocAfterAppend(l2.reverse, xs.reverse, x) |
+ l2.reverse ++ (xs.reverse :+ x) ==| trivial |
+ l2.reverse ++ (x :: xs).reverse
+ }.qed
+ }
+ }
+ }.holds
+
+The idea is to group statements in a block
+(``{ }``) and call ``qed`` on it. Then, instead of writing ``a == b && b == c
+&& hint1 && hint2`` we write ``a ==| hint1 | b ==| hint2 | c``. And when no
+additional hint is required, we can use ``trivial`` which simply stands for
+``true``.
+
+Additionally, by using this DSL, we get the same feedback granularity from Stainless
+as if we had used ``check`` statements. This way we can construct proofs based
+on equality more easily and directly identify where hints are vital.
+
+One shortcoming of the relational reasoning DSL is that it relies on
+Stainless' knowledge of the relational properties of the built-in
+relations, and in particular those of equality. Consequently it works
+badly (if at all) with user-defined relations. However, since the DSL
+is defined as a library (in ``library/proof/package.scala``), it can
+in principle be extended and modified to include specific user-defined
+relations on a case-by-case basis.
+
+.. TODO add a word about requirement in ctor (e.g. Rational)
+
+.. TODO Footnote linking to Etienne's answer on SO.
+
+
+Limits of the approach: HOFs, quantifiers and termination
+*********************************************************
+
+While the techniques discussed in this section are useful in general,
+their applicability has, of course, its limitations in practice. These
+limitations are mostly due to Stainless' limited support for certain
+language constructs, such as higher-order functions (HOFs) or
+quantifiers (which in turn is due, mostly, to the limited support of
+the corresponding theories in the underlying SMT solvers).
+
+Still, even using these "experimental" features, one manages to prove
+some interesting propositions. Here is another list example, which
+relates the ``foldLeft``, ``foldRight`` and ``reverse`` operations
+defined on lists and makes crucial use of HOFs:
+
+.. code-block:: scala
+
+ import stainless.collection._
+ import stainless.lang._
+ import stainless.proof._
+
+ def folds[A, B](xs: List[A], z: B, f: (B, A) => B): Boolean = {
+ val f2 = (x: A, z: B) => f(z, x)
+ xs.foldLeft(z)(f) == xs.reverse.foldRight(z)(f2) because {
+ xs match {
+ case Nil() => true
+ case Cons(x, xs) => {
+ (x :: xs).foldLeft(z)(f) ==| trivial |
+ xs.foldLeft(f(z, x))(f) ==| folds(xs, f(z, x), f) |
+ xs.reverse.foldRight(f(z, x))(f2) ==| trivial |
+ xs.reverse.foldRight(f2(x, z))(f2) ==|
+ snocFoldRight(xs.reverse, x, z, f2) |
+ (xs.reverse :+ x).foldRight(z)(f2) ==| trivial |
+ (x :: xs).reverse.foldRight(z)(f2)
+ }.qed
+ }
+ }
+ }.holds
+
+A rather different, more general issue that arises when proving
+propositions using Stainless is related to *termination checking*. When
+verifying inductive proofs (and more generally the postconditions of
+recursive methods), Stainless assumes that the corresponding proofs are
+*well-founded*, or equivalently, that the corresponding recursive
+methods terminate on all inputs. It is thus possible -- and indeed rather
+easy -- to write bogus proofs (intentionally or accidentally) which
+Stainless recognizes as valid, but which are not well-founded. Consider
+the following lemma, which apparently establishes that all lists are
+empty:
+
+.. code-block:: scala
+
+ import stainless.collection._
+ import stainless.lang._
+ import stainless.proof._
+
+ object NotWellFounded {
+
+ // This proof is not well-founded. Since Stainless doesn't run the
+ // termination checker by default, it will accept the proof as
+ // valid.
+ def allListsAreEmpty[T](xs: List[T]): Boolean = {
+ xs.isEmpty because {
+ xs match {
+ case Nil() => trivial
+ case Cons(x, xs) => allListsAreEmpty(x :: xs)
+ }
+ }
+ }.holds
+ }
+
+Stainless hences performs termination checking by default to minimize
+the risk of accidentally writing bogus proofs such as the one above.
+It will thus emit a warning if it cannot prove that a function terminates, or
+if it can show that its measure (inferred or user-defined) does not decreases between
+recursive calls.
+
+.. TODO example: folds + future work (alt. version of folds)
+
+.. _post-cond:
+
+Techniques for proving non-trivial postconditions
+-------------------------------------------------
+
+When proving a mathematical lemma, the return type of the
+corresponding function is most of
+the time, if not always, ``Boolean``. For those proofs it is rather easy to
+write a postcondition: using ``holds`` is generally enough.
+
+But when it comes to writing postconditions for more general functions, such as
+the addition of rational numbers, we are no longer dealing with ``Boolean`` so
+we need a strategy to properly write ``ensuring`` statements.
+
+
+Rationals: a simple example
+***************************
+
+Let's take rational numbers as an example: we define them as a case class with
+two attributes, `n` for the numerator and `d` for the denominator. We also
+define three simple properties on them: ``isRational``, ``isNonZero`` and
+``isPositive``.
+
+.. code-block:: scala
+
+ case class Rational(n: BigInt, d: BigInt) {
+ def isRational = d != 0
+ def isPositive = isRational && (n * d >= 0)
+ def isNonZero = isRational && (n != 0)
+
+ // ...
+ }
+
+And on top of that, we want to support addition on ``Rational`` in a way that
+the rationality and positiveness properties are correctly preserved:
+
+.. code-block:: scala
+
+ def +(that: Rational): Rational = {
+ require(isRational && that.isRational)
+ Rational(n * that.d + that.n * d, d * that.d)
+ } ensuring { res =>
+ res.isRational &&
+ (this.isPositive == that.isPositive ==> res.isPositive == this.isPositive)
+ }
+
+In this simple case, things work nicely and we can write the
+multiplication in a similar fashion:
+
+.. code-block:: scala
+
+ def *(that: Rational): Rational = {
+ require(isRational && that.isRational)
+ Rational(n * that.n, d * that.d)
+ } ensuring { res =>
+ res.isRational &&
+ (res.isNonZero == (this.isNonZero && that.isNonZero)) &&
+ (res.isPositive == (!res.isNonZero || this.isPositive == that.isPositive))
+ }
+
+
+Measures: a slightly more complex example
+*****************************************
+
+Now let's look at a slightly more complex example: measures on
+discrete probability spaces. We represent such measures using a
+``List``-like recursive data structure: a generic abstract class
+``Meas[A]`` that has two subclasses, ``Empty[A]`` and ``Cons[A]``.
+The constructor of the class ``Empty[A]`` takes no arguments; it
+represents an "empty" measure that evaluates to 0 when applied to any
+set of values of type ``A``. The constructor of ``Cons[A]``, on the
+other hand, takes three parameters: a value ``x``, its associated
+weight ``w`` expressed as a ``Rational`` (since Stainless doesn't quite yet
+support real numbers out of the box), and another measure ``m`` on
+``A``. The value ``Cons(x, w, m)`` represents the measure obtained by
+adding to ``m`` the "single-point" measure that evaluates to ``w`` at
+``x`` and to 0 everywhere else. We also define an ``isMeasure``
+property -- similar to the ``isRational`` property presented above --
+which recursively checks that all the weights in a measure are
+positive rationals (note that all our measures have finite support).
+
+.. code-block:: scala
+
+ /** Measures on discrete probability spaces. */
+ sealed abstract class Meas[A] {
+
+ /** All weights must be positive. */
+ def isMeasure: Boolean = this match {
+ case Empty() => true
+ case Cons(x, w, m) => w.isPositive && m.isMeasure
+ }
+
+ // ...
+ }
+
+ /** The empty measure maps every subset of the space A to 0. */
+ case class Empty[A]() extends Meas[A]
+
+ /**
+ * The 'Cons' measure adjoins an additional element 'x' of type 'A'
+ * to an existing measure 'm' over 'A'. Note that 'x' might already
+ * be present in 'm'.
+ */
+ case class Cons[A](x: A, w: Rational, m: Meas[A]) extends Meas[A]
+
+
+The defining operation on a measure ``m`` is its evaluation ``m(xs)``
+(or equivalently ``m.apply(xs)``) on some set ``xs: Set[A]``, i.e. on a
+subset of the "space" ``A``. The value of ``m`` should be a positive
+rational for any such set ``xs``, provided ``m.isMeasure`` holds.
+This suggests ``_.isPositive`` as the postcondition for ``apply``,
+but simply claiming that the result is positive is not enough for Stainless
+to verify this postcondition.
+
+We can provide the necessary hint to Stainless by performing structural
+induction on ``this`` inside the postcondition as follows:
+
+.. code-block:: scala
+
+ /** Compute the value of this measure on a subset of the space 'A'. */
+ def apply(xs: Set[A]): Rational = {
+ require (isMeasure)
+ this match {
+ case Empty() => Rational(0, 1)
+ case Cons(x, w, m) => if (xs contains x) w + m(xs) else m(xs)
+ }
+ } ensuring { res =>
+ res.isPositive because {
+ this match {
+ case Empty() => trivial
+ case Cons(x, w, m) => m(xs).isPositive
+ }
+ }
+ }
+
+Notice the similarity between the pattern match in the body of the
+``apply`` function and that in the postcondition. With this hint,
+Stainless is able to verify the postcondition.
+
+
+A complex example: additivity of measures
+-----------------------------------------
+
+Using the principles and techniques discussed so far, one can prove
+quite advanced propositions using Stainless. Returning to the
+measure-theoretic example from the previous section, we would like to
+prove that our implementation of measures is properly *additive*.
+Formally, a measure :math:`\mu \colon A \to \mathbb{R}` on a countable
+set :math:`A` must fulfill the following additivity property
+[#dicrete-meas]_:
+
+.. math::
+
+ \forall A_1, A_2 \subseteq A . A_1 \cap A_2 = \emptyset \Rightarrow
+ \mu(A_1 \cup A_2) = \mu(A_1) + \mu(A_2)
+
+which we can express in Stainless as
+
+.. code-block:: scala
+
+ def additivity[A](m: Meas[A], xs: Set[A], ys: Set[A]): Boolean = {
+ require(m.isMeasure && (xs & ys).isEmpty)
+ m(xs ++ ys) == m(xs) + m(ys)
+ }.holds
+
+We can prove this property using structural induction on the parameter
+``m``, case analysis on the parameters ``xs`` and ``ys``, equational
+reasoning, and properties of rational numbers (in the form of
+user-defined lemmas) as well as sets (using Stainless's built-in support).
+
+.. code-block:: scala
+
+ def additivity[A](m: Meas[A], xs: Set[A], ys: Set[A]): Boolean = {
+ require(m.isMeasure && (xs & ys).isEmpty)
+ m(xs ++ ys) == m(xs) + m(ys) because {
+ m match {
+ case Empty() => trivial
+ case Cons(x, w, n) => if (xs contains x) {
+ w + n(xs ++ ys) ==| additivity(n, xs, ys) |
+ w + (n(xs) + n(ys)) ==| plusAssoc(w, n(xs), n(ys)) |
+ (w + n(xs)) + n(ys) ==| !(ys contains x) |
+ m(xs) + m(ys)
+ }.qed else if (ys contains x) {
+ w + n(xs ++ ys) ==| additivity(n, xs, ys) |
+ w + (n(xs) + n(ys)) ==| plusComm(w, (n(xs) + n(ys))) |
+ (n(xs) + n(ys)) + w ==| plusAssoc(n(xs), n(ys), w) |
+ n(xs) + (n(ys) + w) ==| plusComm(n(ys), w) |
+ n(xs) + (w + n(ys)) ==| !(xs contains x) |
+ m(xs) + m(ys)
+ }.qed else {
+ n(xs ++ ys) ==| additivity(n, xs, ys) |
+ n(xs) + n(ys)
+ }.qed
+ }
+ }
+ }.holds
+
+The full proof (including the proofs of all helper lemmas) as well as
+its generalization to *sub-additivity* can be found in the
+``testcases/verification/proof/measure/`` directory of the Stainless
+distribution [#example-dir]_.
+
+
+Quick Recap
+-----------
+
+Let's summarize what we've learned here. To write proofs efficiently,
+it's good to keep the following in mind:
+
+1. Always use a proper timeout and ask Stainless for more information about
+ what he tries to verify, e.g. ``--timeout=5 --debug=verification``.
+
+2. Use ``@induct`` when working on structurally inductive proofs to
+ get a more precise feedback from Stainless: this will decompose the
+ proof into a base case and an inductive case for the first argument
+ of the function under consideration.
+
+ If Stainless isn't able to verify the proof using ``@induct``, try
+ performing manual case analysis.
+
+3. Modularize your proofs and verify *sub-goals*!
+
+ - use plenty of helper lemmas;
+ - use ``check`` abundantly;
+ - if possible use the relational reasoning DSL presented above.
+
+ This is especially handy when you can connect the two sides of a relational
+ claim with sub-statements.
+
+
+.. rubric:: Footnotes
+
+.. [#example-dir] The source code of this example and all others in
+ this chapter is included in the Stainless distribution. Examples about
+ lists can be found in ``library/collection/List.scala``, other
+ examples are located in the ``testcases/verification/proof/``
+ directory.
+
+.. [#props-not-types] Propositions and proofs
+ live in the same universe in Stainless. This is contrary to
+ e.g. type-theoretic proof assistants where propositions are
+ represented by types and proofs are terms inhabiting such types.
+
+.. [#dicrete-meas] To be precise, we are assuming here the underlying
+ measurable space :math:`(A, \mathcal{P}(A))`, where :math:`A` is
+ countable and :math:`\mathcal{P}(A)` denotes its discrete σ-algebra
+ (i.e. the power set of :math:`A`).
diff --git a/_sources/options.rst.txt b/_sources/options.rst.txt
new file mode 100644
index 0000000000..ec5017e56e
--- /dev/null
+++ b/_sources/options.rst.txt
@@ -0,0 +1,399 @@
+.. _cmdlineoptions:
+
+Specifying Options
+==================
+
+Stainless's command line options have the form ``--option`` or ``--option=value``.
+To enable a flag option, use ``--option=true`` or ``on`` or ``yes``,
+or just ``--option``. To disable a flag option, use ``--option=false``.
+
+Additionally, if you need to pass options to the ``scalac`` frontend of Stainless,
+you can do it by using a single dash ``-``. For example, try ``-Ybrowse:typer``.
+
+The rest of this section presents some of the command-line options that Stainless recognizes.
+For a short (but always up-to-date) summary, you can also invoke ``stainless --help``.
+
+Choosing which Stainless feature to use
+---------------------------------------
+
+The first group of options determines which feature of Stainless will be used.
+By default, ``--verification`` is chosen.
+
+* ``--verification``
+
+ Proves or disproves function contracts, as explained in the :doc:`verification` section.
+
+* ``--eval``
+
+ Evaluate parameterless functions and report their body's value and whether
+ or not their postcondition holds.
+
+* ``--genc``
+
+ Convert stainless code to C (implies --batched, default: false).
+ See documentation section for generating C code.
+
+* ``--coq``
+
+ Transform the program into a Coq program, and let Coq generate subgoals automatically
+
+* ``--type-checker``
+
+ Use type checker inspired by System FR to generate verification conditions.
+ Default is ``true`` and is strongly recommended; using ``false`` reverts to
+ an old verification-condition generator.
+
+* ``--infer-measures=[yes|no|only] (default: yes)``
+
+ Infers measures for recursive functions which do not already have one.
+
+* ``--check-measures=[true|false] (default: true)``
+
+ Check termination of functions with measures, ie. whether measures decrease between recursive calls.
+
+* ``--testgen``
+
+ Proves or disproves function contracts (like ``--verification``) and attempts to create Scala test cases from reported counter-examples.
+
+* ``--genc-testgen``
+
+ Like ``--testgen``, but generates C test cases using GenC.
+
+* ``--help``
+
+ Prints a helpful message, then exits.
+
+
+Additional top-level options
+----------------------------
+
+These options are available to all Stainless components:
+
+* ``--watch``
+
+ Re-run the selected analysis components upon file changes, making the program analysis
+ interactive and significantly more efficient than restarting stainless manually.
+
+* ``--no-colors``
+
+ Disable colored output and non-ascii characters (consider this option for better support in IDEs)
+
+* ``--compact``
+
+ Reduces the components' summaries to only the invalid elements (e.g. invalid VC).
+
+* ``--debug=d1,d2,...``
+
+ Enables printing detailed messages for the components d1,d2,... .
+ Available components include:
+
+ * ``solver`` (SMT solvers and their wrappers)
+
+ * ``termination`` (Termination analysis)
+
+ * ``timers`` (Timers, timer pools)
+
+ * ``trees`` (Manipulation of trees)
+
+ * ``verification`` (Verification)
+
+ * ``full-vc`` (Display VCs before and after simplification)
+
+ * ``type-checker`` (Type checking of the final program for VC generation)
+
+ * ``type-checker-vcs`` (Generation of VCs by the type-checker)
+
+ * ``derivation`` (Dump typing derivations)
+
+* ``--functions=f1,f2,...``
+
+ Only consider functions f1, f2, ... . This applies to all functionalities
+ where Stainless manipulates the input in a per-function basis.
+
+ Stainless will match against suffixes of qualified names. For instance:
+ ``--functions=List.size`` will match the method ``stainless.collection.List.size``,
+ while ``--functions=size`` will match all methods and functions named ``size``.
+ This option supports ``_`` as wildcard: ``--functions=List._`` will
+ match all ``List`` methods.
+
+* ``--solvers=s1,s2,...``
+
+ Use solvers s1, s2,... . If more than one solver is chosen, all chosen
+ solvers will be used in parallel, and the best result will be presented.
+ By default, the ``nativez3`` solver is picked.
+
+ Some solvers are specialized in proving verification conditions
+ and will have a hard time finding a counterexample in the case of an invalid
+ verification condition, whereas some are specialized in finding
+ counterexamples, and some provide a compromise between the two.
+ Also, some solvers do not as of now support higher-order functions.
+
+ Available solvers include:
+
+ * ``nativez3``
+
+ Native Z3 with z3-templates for unfolding recursive functions (default).
+
+ * ``smt-cvc5``
+
+ cvc5 through SMT-LIB. An algorithm within Stainless takes up the unfolding
+ of recursive functions, handling of lambdas etc. To use this or any
+ of the following cvc5-based solvers, you need to have the ``cvc5``
+ executable in your system path (the latest unstable version is recommended).
+
+ * ``smt-z3``
+
+ Z3 through SMT-LIB. To use this or the next solver, you need to
+ have the ``z3`` executable in your program path (the latest stable version
+ is recommended). Inductive reasoning happens on the Stainless side
+ (similarly to ``smt-cvc5``).
+
+ * ``unrollz3``
+
+ Native Z3, but inductive reasoning happens within Stainless (similarly to ``smt-z3``).
+
+ * ``princess``
+
+ Princess solver through its native interface (uses princess-templates) during
+ unfolding. This is a full-stack JVM solver and enables Stainless to run without
+ external solver dependencies.
+
+* ``--timeout=t``
+
+ Set a timeout for each attempt to prove one verification condition/
+ repair one function (in sec.) When using the ``--eval`` component, one
+ should use ``--max-calls`` instead.
+
+* ``--cache``
+
+ Use persistent cache on disk to save the state of the verification and/or
+ termination analyses.
+
+* ``--cache-dir=``
+
+ Specify in which directory the cache files generated by ``--cache`` and other
+ options should be stored. Defaults to ``.stainless-cache/``.
+
+* ``--json=``
+
+ Export the verification and/or termination analyses to the given file.
+
+* ``--extra-deps=org:name_scalaVersion:version,...``
+
+ Fetch the specified dependencies, and add their sources to the set of files
+ processed by Stainless. Each dependency must be available as a source JAR
+ from MavenCentral, the EPFL-LARA bintray organization, your local Ivy database,
+ or through another resolver specified via ``--extra-resolvers``.
+
+ Note: Stainless will not pull transitive dependencies, so one has to specify
+ all transitive dependencies explicitely via this option.
+
+ Example: ``--extra-deps=ch.epfl.lara:stainless-algebra_2.12:0.1.2``
+
+* ``--extra-resolvers=URL,...``
+
+ Specify additional resolvers to be used to fetch the dependencies specified via
+ the ``--extra-deps`` option.
+
+ Note: The full URL of the resolver must be used.
+
+ Example: ``--extra-resolvers=https://oss.sonatype.org/content/repositories/snapshots/``
+
+ See the `Coursier source code `_ for the list of most common repositories URLs.
+
+
+Additional Options (by component)
+---------------------------------
+
+The following options relate to specific components in Stainless.
+
+
+Verification
+************
+
+* ``--strict-aritmetic``
+
+ Check arithmetic operations for unintended behaviour and
+ overflows. Note that reasoning about bitvectors is sound
+ even if this option is false, but in that case no warnings
+ are generated for overflows and underflows because these
+ have well-defined semantics in Scala.
+
+* ``--vc-cache``
+
+ Use a persistent cache mechanism to speed up verification; on by default.
+
+* ``--fail-early``
+
+ Aborts verification as soon as a VC cannot be proven to be correct.
+
+* ``--fail-invalid``
+
+ Aborts verification as soon as an invalid VC is found.
+
+
+
+Termination
+***********
+
+* ``--ignore-posts``
+
+ Ignore postconditions during termination verification.
+
+
+
+Unrolling Solver
+****************
+
+* ``--check-models``
+
+ Double-check counterexamples with the evaluator.
+
+* ``--feeling-lucky``
+
+ Use evaluator to find counterexamples early.
+
+* ``--unroll-assumptions``
+
+ Use unsat-assumptions to drive unrolling while remaining fair.
+
+* ``--silent-errors``
+
+ Don't crash on errors, simply return ``Unknown``.
+
+* ``--unroll-factor=n``
+
+ Speeds up unrolling by a factor ``n``.
+
+* ``--model-finding=n``
+
+ Boosts model-finding capabilities by a factor ``n``. This may come at
+ the cost of proof construction.
+
+* ``--no-simplifications``
+
+ Disables program simplification heuristics.
+
+
+
+cvc5 Solver
+***********
+
+* ``--solver:cvc5=``
+
+ Pass extra command-line arguments to cvc5.
+
+
+
+Evaluators
+**********
+
+* ``--codegen``
+
+ Use compiled evaluator instead of an interpreter.
+
+* ``--small-arrays``
+
+ Assume all arrays can fit into memory during compiled evaluation.
+
+* ``--instrument``
+
+ Instrument ADT field access during code generation.
+
+* ``--max-calls=n``
+
+ Bounds the total number of function call evaluations (before crashing).
+
+* ``--ignore-contracts``
+
+ Ignores function contracts during evaluation.
+
+
+
+Tests generation
+****************
+
+* ``testgen-file=``
+
+ Specifies the output file for the generated tests.
+
+* ``genc-testgen-includes=header1.h,header2,...``
+
+ Only applies for ``--genc-testgen``. Indicates the headers to ``#include`` in the generated test file.
+
+Configuration File
+------------------
+
+Stainless supports setting default values for command line options configuration files.
+To specify configuration file you can use the option ```--config-file=FILE``. The default is
+``stainless.conf`` or ``.stainless.conf``. The file should be a valid HOCON file.
+
+For example, consider the config file containin the following lines:
+
+.. code-block:: text
+
+ vc-cache = false
+ debug = [verification, trees]
+ timeout = 5
+ check-models = true
+ print-ids = true
+
+
+The file will translate to the following command line options:
+
+``--vc-cache=false --debug=verification,trees --timeout=5 --print-ids``
+
+Stainless searches for a configuration file recursively
+starting from the current directory and walking up the
+directory hierarchy. For example, if one runs stainless
+from ``/a/b/c`` and there is a config file in any of `c`,
+`b` or `a`, the first of those is going to be loaded.
+
+Library Files
+-------------
+
+Purpose of library files
+************************
+
+Stainless contains library source Scala files that define types and functions that are meant to be always available
+via import statements such as ``import stainless.lang._``, ``import stainless.annotation._``,
+``import stainless.collection._``, and so on. Many of these types have special treatment inside the extraction
+pipeline and will map directly to mathematical data types of the underlying SMT solvers.
+At build time, the ``build.sbt`` script computes the list of these files by traversing the ``frontends/library/`` directory.
+
+Changing the list of library files
+**********************************
+
+To support further customization, if at run time stainless finds
+a file ``libfiles.txt`` in the current directory, it replaces the list of library files files with the list contained
+in this file, one file per line, with paths relative to the directory ``frontends/library/``. For example, ``libfiles.txt``
+may contain:
+
+.. code:: text
+
+ stainless/util/Random.scala
+ stainless/lang/Option.scala
+ stainless/lang/StaticChecks.scala
+ stainless/lang/Real.scala
+ stainless/lang/Either.scala
+ stainless/lang/Set.scala
+ stainless/lang/MutableMap.scala
+ stainless/lang/package.scala
+ stainless/lang/Bag.scala
+ stainless/lang/Map.scala
+ stainless/collection/List.scala
+ stainless/math/BitVectors.scala
+ stainless/math/Nat.scala
+ stainless/math/package.scala
+ stainless/io/StdIn.scala
+ stainless/io/package.scala
+ stainless/annotation/annotations.scala
+ stainless/annotation/isabelle.scala
+ stainless/annotation/cCode.scala
+ stainless/proof/Internal.scala
+ stainless/proof/package.scala
+
+Shortening this list may reduce the startup time, but also cause Stainless to not work propertly, so
+using the ``--watch`` and ``--functions`` options is the first option to try.
+
+For further customization by advanced users, please examine the ``build.sbt`` file.
diff --git a/_sources/purescala.rst.txt b/_sources/purescala.rst.txt
new file mode 100644
index 0000000000..290e13ce03
--- /dev/null
+++ b/_sources/purescala.rst.txt
@@ -0,0 +1,856 @@
+ .. _purescala:
+
+Pure Scala
+==========
+
+The input to Stainless is a purely functional **subset** of `Scala
+`_, which we call
+**Pure Scala**. Constructs specific for Stainless are defined inside
+Stainless's libraries in package `stainless` and its subpackages.
+Stainless invokes standard `scalac` compiler on the input file, then
+performs additional checks to ensure that the given program
+belongs to Pure Scala.
+
+Pure Scala supports two kinds of top-level declarations:
+
+1. Algebraic Data Type (ADT) definitions in the form of an
+ abstract class and case classes/objects
+
+.. code-block:: scala
+
+ abstract class MyList
+ case object MyEmpty extends MyList
+ case class MyCons(elem: BigInt, rest: MyList) extends MyList
+
+2. Objects/modules, for grouping classes and functions
+
+.. code-block:: scala
+
+ object Specs {
+ def increment(a: BigInt): BigInt = {
+ a + 1
+ }
+
+ case class Identifier(id: BigInt)
+ }
+
+Booleans
+--------
+
+Booleans are used to express truth conditions in Stainless.
+Unlike some proof assistants, there is no separation
+at the type level between
+Boolean values and the truth conditions of conjectures
+and theorems.
+
+Typical propositional operations are available using Scala
+notation, along
+with a new shorthand for implication. The `if` expression
+is also present.
+
+.. code-block:: scala
+
+ a && b
+ a || b
+ a == b
+ !a
+ a ==> b // Stainless syntax for boolean implication
+
+Stainless uses short-circuit interpretation of `&&`, `||`, and `==>`,
+which evaluates the second argument only when needed:
+
+.. code-block:: scala
+
+ a && b === if (a) b else false
+
+ a || b === if (a) true else b
+
+ a ==> b === if (a) b else true
+
+This aspect is important because of:
+
+1. evaluation of expressions, which is kept compatible with Scala
+
+2. verification condition generation for safety: arguments of Boolean operations
+may be operations with preconditions; these preconditions apply only in case
+that the corresponding argument is evaluated.
+
+3. termination checking, which takes into account that only one of the paths in an if expression is evaluated for a given truth value of the condition.
+
+.. _adts:
+
+Algebraic Data Types
+--------------------
+
+Abstract Classes
+****************
+
+ADT roots need to be defined as abstract, unless the ADT is defined with only one case class/object. Unlike in Scala, abstract classes cannot define fields or constructor arguments.
+
+.. code-block:: scala
+
+ abstract class MyType
+
+An abstract class can be extended by other abstract classes.
+
+Case Classes
+************
+
+The abstract root can also be extended by a case-class, defining several fields:
+
+.. code-block:: scala
+
+ case class MyCase1(f: Type, f2: MyType) extends MyType
+ case class MyCase2(f: Int) extends MyType
+
+.. note::
+ You can also define single case-class, for Tuple-like structures.
+
+You can add invariants to case classes using a ``require`` clause, as follows:
+
+.. code-block:: scala
+
+ case class Positive(value: BigInt = 0) {
+ require(value >= 0)
+ }
+
+For classes without type parameters, when all fields have a default value, Stainless generates a
+verification condition to check that the default instance respects the invariant. In this example,
+the verification condition will be seen as coming from an internal function called
+``PositiveRequireForDefault``.
+
+.. note::
+
+ Invariants are only allowed to refer to fields of their class, and
+ cannot call any methods on ``this`` (but calls to methods on their
+ fields are allowed).
+
+Case Objects
+************
+
+It is also possible to defined case objects, without fields:
+
+.. code-block:: scala
+
+ case object BaseCase extends MyType
+
+Value Classes
+*************
+
+One can define a value class just like in standard Scala,
+by extending the ``AnyVal`` class.
+
+.. code-block:: scala
+
+ case class Positive(value: BigInt) extends AnyVal {
+ @invariant
+ def isPositive: Boolean = value >= 0
+ }
+
+In the code block above, we also specify an invariant of the value
+class, using the ``@invariant`` annotation. Such invariants are
+subsequently lifted into a refinement type of the underlying type.
+
+.. note::
+
+ Same remark as above: invariants are only allowed to refer to fields of their class.
+
+Generics
+--------
+
+Stainless supports type parameters for classes and functions.
+
+.. code-block:: scala
+
+ object Test {
+ abstract class List[T]
+ case class Cons[T](hd: T, tl: List[T]) extends List[T]
+ case class Nil[T]() extends List[T]
+
+ def contains[T](l: List[T], el: T) = { ... }
+ }
+
+
+.. note::
+ Type parameters can also be marked as co- or contra-variant, eg.
+
+ .. code-block:: scala
+
+ abstract class List[+T]
+ case class Cons[T](hd: T, tl: List[T]) extends List[T]
+ case object Nil extends List[Nothing]
+
+Methods
+-------
+
+You can define methods in classes.
+
+.. code-block:: scala
+
+ abstract class List[T] {
+ def contains(e: T) = { .. }
+ }
+
+ case class Cons[T](hd: T, tl: List[T]) extends List[T]
+ case object Nil extends List[Nothing]
+
+ def test(a: List[Int]) = a.contains(42)
+
+It is possible to define abstract methods in abstract classes and implement them in case classes.
+Multiple layers of inheritance are allowed, as is the ability to override concrete methods.
+
+.. code-block:: scala
+
+ abstract class A {
+ def x(a: Int): Int
+ }
+
+ abstract class B extends A {
+ def x(a: Int) = {
+ require(a > 0)
+ 42
+ } ensuring { _ >= 0 }
+ }
+
+ case class C(c: Int) extends B {
+ override def x(i: Int) = {
+ require(i >= 0)
+ if (i == 0) 0
+ else c + x(i-1)
+ } ensuring ( _ == c * i )
+ }
+
+ case class D() extends B
+
+It is also possible to call methods of a superclass with the ``super`` keyword.
+
+.. code-block:: scala
+
+ sealed abstract class Base {
+ def double(x: BigInt): BigInt = x * 2
+ }
+
+ case class Override() extends Base {
+ override def double(x: BigInt): BigInt = {
+ super.double(x + 1) + 42
+ }
+ }
+
+Abstract methods may have contracts in terms of pre- and postconditions. The
+syntax uses ``???`` and is as follows:
+
+.. code-block:: scala
+
+ abstract class Set[T] {
+ def contains[T](t: T): Boolean
+
+ def add[T](t: T): Set[T] = {
+ require(!this.contains(t))
+ (??? : Set[T])
+ }.ensuring(res => res.contains(t))
+ }
+
+You can then extend such abstract classes by concrete implementations, and
+Stainless will generate verification conditions to make sure that the
+implementation respects the specification.
+
+You can also add implementations and assume that they are correct with respect
+to the specification of the abstract class, without having Stainless check the
+specification (e.g. if you want to use existing Scala data-structures inside).
+In that case, mark the concrete class with ``@extern`` (see Section :doc:`wrap`
+for more info on ``@extern``) or place the concrete implementation in files
+which are not inspected by Stainless (see e.g.
+https://github.com/epfl-lara/stainless-project.g8 for an example of how to setup
+such a hybrid project).
+
+
+Copy Method
+***********
+
+The ``copy`` method of classes with immutable fields is extracted as well,
+and ensures that the class invariant (if any) is maintained by requiring it
+to be satisfied as a precondition.
+
+.. code-block:: scala
+
+ case class Foo(x: BigInt) {
+ require(x > 0)
+ }
+
+ def prop(foo: Foo, y: BigInt) = {
+ require(y > 1)
+ foo.copy(x = y)
+ }
+
+.. note::
+ The example above would not verify without the precondition in function ``prop``,
+ as ``Foo`` require its field ``x`` to be positive.
+
+
+Initialization
+**************
+
+In Pure Scala, initialization of ``val``'s may not have future or self-references:
+
+.. code-block:: scala
+
+ object Initialization {
+ case class C(x: BigInt) {
+ val y = x // ok
+ val z = y + x // ok
+ val a = b // Error: "because field `a` can only refer to previous fields, not to `b`"
+ val b = z + y // ok
+ }
+ }
+
+
+Overriding
+**********
+
+Stainless supports overriding methods with some constraints:
+* A ``val`` in an abstract class can only be overridden by a concrete class parameter.
+* Methods and ``lazy val``s in abstract classes can be overridden by concrete methods or
+``lazy val``'s (interchangably), or by a concrete class parameter, but not by
+a ``val``.
+
+Here are a few examples that are rejected by Stainless:
+
+.. code-block:: scala
+
+ object BadOverride1 {
+ sealed abstract class Abs {
+ require(x != 0)
+ val x: Int
+ }
+
+ // Error: "Abstract values `x` must be overridden with fields in concrete subclass"
+ case class AbsInvalid() extends Abs {
+ def x: Int = 1
+ }
+ }
+
+.. code-block:: scala
+
+ object BadOverride2 {
+ sealed abstract class Abs {
+ val y: Int
+ }
+
+ // Error: "Abstract values `y` must be overridden with fields in concrete subclass"
+ case class AbsInvalid() extends Abs {
+ val y: Int = 2
+ }
+ }
+
+.. code-block:: scala
+
+ object BadOverride3 {
+ sealed abstract class AAA {
+ def f: BigInt
+ }
+
+ // Error: "because abstract methods BadOverride3.AAA.f were not overridden by
+ // a method, a lazy val, or a constructor parameter"
+ case class BBB() extends AAA {
+ val f: BigInt = 0
+ }
+ }
+
+
+Default Parameters
+******************
+
+Functions and methods can have default values for their parameters.
+
+.. code-block:: scala
+
+ def test(x: Int = 21): Int = x * 2
+
+ assert(test() == 42) // valid
+
+
+
+Type Definitions
+----------------
+
+Type Aliases
+************
+
+Type aliases can be defined the usual way:
+
+.. code-block:: scala
+
+ object testcase {
+ type Identifier = String
+
+ def newIdentifier: Identifier = /* returns a String */
+ }
+
+Type aliases can also have one or more type parameters:
+
+.. code-block:: scala
+
+ type Collection[A] = List[A]
+
+ def singleton[A](x: A): Collection[A] = List(x)
+
+Type Members
+************
+
+Much like classes can have field members and method members, they can also
+define type members. Much like other members, those can also be declared
+abstract within an abstract class and overridden in implementations:
+
+.. code-block:: scala
+
+ case class Grass()
+
+ abstract class Animal {
+ type Food
+ val happy: Boolean
+ def eat(food: Food): Animal
+ }
+
+ case class Cow(happy: Boolean) extends Animal {
+ type Food = Grass
+ def eat(g: Grass): Cow = Cow(happy = true)
+ }
+
+Note: Like regular type aliases, type members can also have one or more type parameters.
+
+Type members then give rise to path-dependent types, where the type of a variable
+can depend on another variable, by selecting a type member on the latter:
+
+.. code-block:: scala
+
+ // Path-dependent type
+ // vvvvvvvvvvv
+ def giveFood(animal: Animal)(food: animal.Food): Animal = {
+ animal.eat(food)
+ }
+
+ def test = {
+ val cow1 = Cow(false)
+ val cow2 = giveFood(cow1)(Grass())
+ assert(cow2.happy) // VALID
+ }
+
+Specifications
+--------------
+
+Stainless supports three kinds of specifications to functions and methods:
+
+Preconditions
+*************
+
+Preconditions constraint the argument and is expressed using `require`. It should hold for all calls to the function.
+
+.. code-block:: scala
+
+ def foo(a: Int, b: Int) = {
+ require(a > b)
+ ...
+ }
+
+Postconditions
+**************
+
+Postconditions constraint the resulting value, and is expressed using `ensuring`:
+
+.. code-block:: scala
+
+ def foo(a: Int): Int = {
+ a + 1
+ } ensuring { res => res > a }
+
+Body Assertions
+***************
+
+Assertions constrain intermediate expressions within the body of a function.
+
+.. code-block:: scala
+
+ def foo(a: Int): Int = {
+ val b = -a
+ assert(a >= 0 || b >= 0, "This will fail for -2^31")
+ a + 1
+ }
+
+The error description (last argument of ``assert``) is optional.
+
+Expressions
+-----------
+
+Stainless supports most purely-functional Scala expressions:
+
+Pattern matching
+****************
+
+.. code-block:: scala
+
+ expr match {
+ // Simple (nested) patterns:
+ case CaseClass( .. , .. , ..) => ...
+ case v @ CaseClass( .. , .. , ..) => ...
+ case v : CaseClass => ...
+ case (t1, t2) => ...
+ case 42 => ...
+ case _ => ...
+
+ // can also be guarded, e.g.
+ case CaseClass(a, b, c) if a > b => ...
+ }
+
+Custom pattern matching with ``unapply`` methods are also supported:
+
+.. code-block:: scala
+
+ object :: {
+ def unapply[A](l: List[A]): Option[(A, List[A])] = l match {
+ case Nil() => None()
+ case Cons(x, xs) => Some((x, xs))
+ }
+ }
+
+ def empty[A](l: List[A]) = l match {
+ case x :: xs => false
+ case Nil() => true
+ }
+
+Values
+******
+
+.. code-block:: scala
+
+ val x = ...
+
+ val (x, y) = ...
+
+ val Cons(h, _) = ...
+
+.. note::
+ The latter two cases are actually syntactic sugar for pattern matching with one case.
+
+
+Inner Functions
+***************
+
+.. code-block:: scala
+
+ def foo(x: Int) = {
+ val y = x + 1
+ def bar(z: Int) = {
+ z + y
+ }
+ bar(42)
+ }
+
+
+Local and Anonymous Classes
+***************************
+
+Functions and methods can declare local classes, which can close over
+the fields of the enclosing class, as well as the parameters of the enclosing
+function or method.
+
+.. code-block:: scala
+
+ abstract class Foo {
+ def bar: Int
+ }
+
+ def makeFoo(x: Int): Foo = {
+ case class Local() extends Foo {
+ def bar: Int = x
+ }
+ Local()
+ }
+
+.. note:: Functions and methods which return an instance of a local class
+ must have an explicit return type, which will typically be that of the parent class.
+ Otherwise, a structural type will be inferred by the Scala compiler, and those are
+ currently unsupported.
+
+Anonymous classes with an explicit parent are supported as well:
+
+.. code-block:: scala
+
+ abstract class Foo {
+ def bar: Int
+ }
+
+ def makeFoo(x: Int): Foo = new Foo {
+ def bar: Int = x
+ }
+
+.. note:: Anonymous classes cannot declare more public members than their parent class,
+ ie. the following is not supported:
+
+.. code-block:: scala
+
+ abstract class Foo {
+ def bar: Int
+ }
+
+ def makeFoo(x: Int): Foo = new Foo {
+ def bar: Int = x
+ def hi: String = "Hello, world"
+ }
+
+Predefined Types
+----------------
+
+TupleX
+******
+
+.. code-block:: scala
+
+ val x = (1,2,3)
+ val y = 1 -> 2 // alternative Scala syntax for Tuple2
+ x._1 // == 1
+
+
+Int
+***
+
+.. code-block:: scala
+
+ a + b
+ a - b
+ -a
+ a * b
+ a / b
+ a % b // a modulo b
+ a < b
+ a <= b
+ a > b
+ a >= b
+ a == b
+
+.. note::
+ Integers are treated as 32bits integers and are subject to overflows.
+
+BigInt
+******
+
+.. code-block:: scala
+
+ val a = BigInt(2)
+ val b = BigInt(3)
+
+ -a
+ a + b
+ a - b
+ a * b
+ a / b
+ a % b // a modulo b
+ a < b
+ a > b
+ a <= b
+ a >= b
+ a == b
+
+.. note::
+ BigInt are mathematical integers (arbitrary size, no overflows).
+
+Real
+****
+
+``Real`` represents the mathematical real numbers (different from floating points). It is an
+extension to Scala which is meant to write programs closer to their true semantics.
+
+.. code-block:: scala
+
+ val a: Real = Real(2)
+ val b: Real = Real(3, 5) // 3/5
+
+ -a
+ a + b
+ a - b
+ a * b
+ a / b
+ a < b
+ a > b
+ a <= b
+ a >= b
+ a == b
+
+.. note::
+ Real have infinite precision, which means their properties differ from ``Double``.
+ For example, the following holds:
+
+ .. code-block:: scala
+
+ def associativity(x: Real, y: Real, z: Real): Boolean = {
+ (x + y) + z == x + (y + z)
+ } holds
+
+ While it does not hold with floating point arithmetic.
+
+
+Set
+***
+
+.. code-block:: scala
+
+ import stainless.lang.Set // Required to have support for Sets
+
+ val s1 = Set(1,2,3,1)
+ val s2 = Set[Int]()
+
+ s1 ++ s2 // Set union
+ s1 & s2 // Set intersection
+ s1 -- s2 // Set difference
+ s1 subsetOf s2
+ s1 contains 42
+
+
+Functional Array
+****************
+
+.. code-block:: scala
+
+ val a = Array(1,2,3)
+
+ a(index)
+ a.updated(index, value)
+ a.length
+
+
+Map
+***
+
+.. code-block:: scala
+
+ import stainless.lang.Map // Required to have support for Maps
+
+ val m = Map[Int, Boolean](42 -> false)
+
+ m(index)
+ m isDefinedAt index
+ m contains index
+ m.updated(index, value)
+ m + (index -> value)
+ m + (value, index)
+ m.get(index)
+ m.getOrElse(index, value2)
+
+
+Function
+********
+
+.. code-block:: scala
+
+ val f1 = (x: Int) => x + 1 // simple anonymous function
+
+ val y = 2
+ val f2 = (x: Int) => f1(x) + y // closes over `f1` and `y`
+ val f3 = (x: Int) => if (x < 0) f1 else f2 // anonymous function returning another function
+
+ list.map(f1) // functions can be passed around ...
+ list.map(f3(1) _) // ... and partially applied
+
+.. note::
+ No operators are defined on function-typed expressions, so specification is
+ currently quite limited.
+
+
+
+Bitvectors
+**********
+
+Bitvectors are currently only supported in GenC and for verification, but
+`not for compilation `_.
+
+These examples are taken from `BitVectors3.scala
+`_.
+
+.. code-block:: scala
+
+ import stainless.math.BitVectors._
+
+ val x1: UInt8 = 145
+ val x2: Int8 = x1.toSigned[Int8] // conversion from unsigned to signed ints
+
+ // Bitvectors can be compared to literal constants, which are encoded as a bitvector of the same
+ // type as the left-hand-side bitvector.
+ // In the line below, `-111` get encoded internally as an `Int8`.
+ assert(x2 == -111)
+
+ // In Stainless internals, `Int8` and `Byte` are the same type, but not for the surface language,
+ // so `toByte` allows to go from `Int8` to `Byte`.
+ // Similarly, we support `toShort`, `toInt`, `toLong` for conversions
+ // respectively from `Int16` to `Short`, `Int32` to `Int`, `Int64` to `Long`,
+ // and `fromByte`, `fromShort`, `fromInt`, `fromLong` for the other direction
+ val x3: Byte = x2.toByte
+ assert(x3 == -111)
+
+ // Unsigned ints can be cast to larger unsigned types
+ val x4: UInt12 = x1.widen[UInt12]
+ assert(x4 == 145)
+
+ // or truncated to smaller unsigned types.
+ val x5: UInt4 = x1.narrow[UInt4]
+ assert(x5 == 1) // 145 % 2^4 == 1
+
+ // Signed ints can also be cast to larger signed types (using sign extension)
+ val x6: Int8 = 120
+ val x7: Int12 = x6.widen[Int12]
+ assert(x7 == 120)
+
+ // and cast to smaller signed types.
+ // This corresponds to extracting the least significant bits of the representation
+ // (see `extract` here http://smtlib.cs.uiowa.edu/logics-all.shtml).
+ val x8: Int4 = x6.narrow[Int4]
+ assert(x8 == -8)
+
+ // the `toByte`, `toShort`, `toInt`, and `toLong` methods described above
+ // can be used on any bitvector type. For signed integers, this corresponds
+ // to a narrowing or a widening operation depending on the bitvector size.
+ // For unsigned integers, this corresponds to first doing a widening/narrowing
+ // operation, and then applying `toSigned`
+ val x9: UInt2 = 3
+ assert(x9.toInt == x9.widen[UInt32].toSigned[Int32].toInt)
+
+ // The library also provide constants for maximum and minimum values.
+ assert(max[Int8] == 127)
+ assert(min[Int8] == -128)
+
+
+Arrays, which are usually indexed using ``Int``, may also be indexed using the bitvector types.
+This is similar to first converting the bitvector index using ``toInt``.
+
+Bitvector types can be understood as finite intervals of integers
+(two's complement representation). For ``X`` an integer larger than ``1``
+(and at most ``256`` in Stainless):
+
+* ``UIntX`` is the interval :math:`[0, 2^X - 1]`,
+* ``IntX`` is the interval :math:`[-2^{X-1}, 2^{X-1} - 1]`.
+
+Conversions between these types can be interpreted as operations on the
+arrays of bits of the bitvectors, or as operations on the integers they
+represent.
+
+* ``widen`` from ``UIntX`` to ``UIntY`` with :math:`Y > X` adds :math:`Y-X` (most significant) 0-bits, and corresponds to the identity transformation on integers.
+
+* ``widen`` from ``IntX`` to ``IntY`` with :math:`Y > X` copies :math:`Y-X` times the sign bit (sign-extension), and corresponds to the identity transformation on integers.
+
+* ``narrow`` from ``UIntX`` to ``UIntY`` with :math:`Y < X` removes the :math:`X-Y` most significant bits,
+ and corresponds to taking the number modulo :math:`2^Y`.
+ When the ``strict-arithmetic`` option is enabled, narrowing a number ``n`` to ``UIntY`` generates
+ a check ``n < 2^Y``.
+
+* ``narrow`` from ``IntX`` to ``IntY`` with :math:`Y < X` removes the :math:`X-Y` most significant bits (including the sign bit),
+ and corresponds to the identity for integers in the interval :math:`[-2^{Y-1}, 2^{Y-1} - 1]`. Outside this range,
+ the narrowing operation on a number ``n`` can be described as: 1) (unsigning) adding ``2^X`` if ``n`` is negative,
+ 2) (unsigned narrowing) taking the result modulo ``2^Y``, 3) (signing) removing ``2^Y`` if the result of (2) is
+ greater or equal than ``2^{Y-1}``.
+ In ``strict-arithmetic`` mode, narrowing a number ``n`` to ``IntY`` generates two checks: ``-2^{Y-1} <= n`` and ``n <= 2^{Y-1} - 1``.
+
+* ``toSigned`` from ``UIntX`` to ``IntX`` does not change the bitvector, and behaves as the identity for integers not larger than :math:`2^{X-1}-1`,
+ and subtracts :math:`2^{X}` for integers in the interval :math:`[2^{X-1}, 2^{X} - 1]`.
+ In ``strict-arithmetic`` mode, making a number ``n`` signed generates a check ``n <= 2^{X-1}-1``.
+
+* ``toUnsigned`` from ``IntX`` to ``UIntX`` does not change the bitvector, and behaves as the identity
+ for non-negative integers, and adds :math:`2^{X}` for negative integers (in the interval :math:`[-2^{X-1}, 0[`).
+ In ``strict-arithmetic`` mode, making a number ``n`` unsigned generates a check ``n >= 0``.
diff --git a/_sources/references.rst.txt b/_sources/references.rst.txt
new file mode 100644
index 0000000000..e27e69c991
--- /dev/null
+++ b/_sources/references.rst.txt
@@ -0,0 +1,45 @@
+.. _references:
+
+References
+==========
+
+The Stainless/Inox stack has emerged as a cleaner and leaner version of the Leon
+synthesis and verification framework. Leon is documented in several
+papers and talks, which provide additional information on the algorithms
+and techniques we used in Leon (and now Stainless/Inox).
+
+
+Videos
+******
+
+ - `Verifying and Synthesizing Software with Recursive Functions `_ (ICALP 2014)
+ - `Executing Specifications using Synthesis and Constraint Solving `_ (RV 2013)
+ - `Video of Verifying Programs in Leon `_ (2013)
+
+
+Papers
+******
+
+ - `System FR: Formalized Foundations for the Stainless Verifier `_, by *Jad Hamza*, *Nicolas Voirol*, and *Viktor Kuncak*. Object-Oriented Programming, Systems, Languages & Applications (OOPSLA), 2019.
+ - `Translating Scala Programs to Isabelle/HOL (System Description) `_, by *Lars Hupel* and *Viktor Kuncak*. International Joint Conference on Automated Reasoning (IJCAR), 2016.
+ - `Counter-example complete verification for higher-order functions `_, by *Nicolas Voirol*, *Etienne Kneuss*, and *Viktor Kuncak*. Scala Symposium, 2015.
+ - `Sound reasoning about integral data types with a reusable SMT solver interface `_, by *Régis Blanc* and *Viktor Kuncak*. Scala Symposium, 2015.
+ - `Deductive program repair `_, by *Etienne Kneuss*, *Manos Koukoutos*, and *Viktor Kuncak*. Computer-Aided Verification (CAV), 2015.
+ - `Symbolic resource bound inference for functional programs `_, by *Ravichandhran Madhavan* and *Viktor Kuncak*. Computer Aided Verification (CAV), 2014.
+ - `Checking data structure properties orders of magnitude faster `_, by *Emmanouil Koukoutos* and *Viktor Kuncak*. Runtime Verification (RV), 2014
+ - `Synthesis Modulo Recursive Functions `_, by *Etienne Kneuss*, *Viktor Kuncak*, *Ivan Kuraj*, and *Philippe Suter*. OOPSLA 2013
+ - `Executing specifications using synthesis and constraint solving (invited talk) `_, by Viktor Kuncak, Etienne Kneuss, and Philippe Suter. Runtime Verification (RV), 2013
+ - `An Overview of the Leon Verification System `_, by *Régis Blanc*, *Etienne Kneuss*, *Viktor Kuncak*, and *Philippe Suter*. Scala Workshop 2013
+ - `Reductions for synthesis procedures `_, by *Swen Jacobs*, *Viktor Kuncak*, and *Phillippe Suter*. Verification, Model Checking, and Abstract Interpretation (VMCAI), 2013
+ - `Constraints as Control `_, *Ali Sinan Köksal*, *Viktor Kuncak*, *Philippe Suter*, Principles of Programming Languages (POPL), 2012
+ - `Satisfiability Modulo Recursive Programs `_, by *Philippe Suter*, *Ali Sinan Köksal*, *Viktor Kuncak*, Static Analysis Symposium (SAS), 2011
+ - `Scala to the power of Z3: Integrating SMT and programming `_, by *Ali Sinan Köksal*, *Viktor Kuncak*, and *Philippe Suter*. Computer-Aideded Deduction (CADE) Tool Demo, 2011
+ - `Decision Procedures for Algebraic Data Types with Abstractions `_, by *Philippe Suter*, *Mirco Dotta*, *Viktor Kuncak*. Principles of Programming Languages (POPL), 2010
+ - `Complete functional synthesis `_, by *Viktor Kuncak*, *Mikael Mayer*, *Ruzica Piskac*, and *Philippe Suter*. ACM SIGPLAN Conf. Programming Language Design and Implementation (PLDI), 2010.
+
+
+
+Books
+*****
+
+ - `Concrete Semantics with Isabelle/HOL `_, by *Tobias Nipkow* and *Gerwin Klein*.
diff --git a/_sources/tutorial.rst.txt b/_sources/tutorial.rst.txt
new file mode 100644
index 0000000000..cc4eb0a501
--- /dev/null
+++ b/_sources/tutorial.rst.txt
@@ -0,0 +1,448 @@
+.. _tutorial:
+
+Tutorial: Sorting
+=================
+
+This tutorial shows how to:
+
+ * use `ensuring`, `require`, and `holds` constructs
+ * learn the difference between `Int` and `BigInt`
+ * define lists as algebraic data types
+ * use sets and recursive function to specify data structures
+
+See :doc:`gettingstarted` about how to setup the command line
+tool.
+
+Warm-up: Max
+------------
+
+As a warm-up illustrating verification, we define and debug a `max` function
+and specify its properties. Stainless uses Scala constructs
+`require` and `ensuring` to document preconditions and
+postconditions of functions. Note that, in addition to
+checking these conditions at run-time (which standard Scala
+does), Stainless can analyze the specifications statically and
+prove them for *all* executions, or, if they are wrong, automatically find
+inputs for which the conditions fail.
+
+Consider the following definition inside of an object `TestMax`.
+
+.. code-block:: scala
+
+ object TestMax {
+ def max(x: Int, y: Int): Int = {
+ val d = x - y
+ if (d > 0) x
+ else y
+ } ensuring(res =>
+ x <= res && y <= res && (res == x || res == y))
+ }
+
+A Stainless program consists of one or more modules delimited by
+`object` and `class` declarations.
+The code of `max` attempts to compute the maximum of two given arguments
+by subtracting them. If the result is positive, it returns
+the first one, otherwise, it returns the second one.
+
+To specify the correctness of the computed result, we use
+the `ensuring` clause. In this case, the clause specifies
+that the result is larger than `x` and than `y`, and that it
+equals to one of them. The construct `ensuring(res => P)`
+denotes that, if we denote by `res` the return value of the
+function, then `res` satisfies the boolean-valued expression
+`P`. The name `res` we chose is an arbitrary bound variable
+(even though we often tend to use `res`).
+
+We can evaluate this code on some values by writing
+parameterless functions and inspecting what they evaluate
+to. The web interface will display these results for us.
+
+.. code-block:: scala
+
+ def test1 = max(10, 5)
+ def test2 = max(-5, 5)
+ def test3 = max(-5, -7)
+
+The code seems to work correctly on the example values.
+However, Stainless automatically finds that it is not correct:
+
+.. code-block:: text
+
+ [ Info ] - Now solving 'postcondition' VC for max @6:16...
+ [ Info ] - Result for 'postcondition' VC for max @6:16:
+ [Warning ] => INVALID
+ [Warning ] Found counter-example:
+ [Warning ] y: Int -> 2147483647
+ [Warning ] x: Int -> -2147483648
+
+ [ Info ] - Now solving 'postcondition' VC for max @7:10...
+ [ Info ] - Result for 'postcondition' VC for max @7:10:
+ [Warning ] => INVALID
+ [Warning ] Found counter-example:
+ [Warning ] y: Int -> -2147483648
+ [Warning ] x: Int -> 1
+
+ [ Info ] - Now solving 'body assertion: Subtraction overflow' VC for max @5:13...
+ [ Info ] - Result for 'body assertion: Subtraction overflow' VC for max @5:13:
+ [Warning ] => INVALID
+ [Warning ] Found counter-example:
+ [Warning ] y: Int -> -2147483648
+ [Warning ] x: Int -> 0
+
+Here, Stainless emits three distinct verification conditions:
+
+* One which corresponds to the postcondition of ``max`` when we take the `then` branch
+ of the ``if`` statement, on line 6.
+
+* Another one for the postcondition of ``max`` when we take the `else` branch
+ of the ``if`` statement, on line 7.
+
+* A last one with an overflow check for the subtraction on line 5.
+
+Let us look at the first verification condition:
+
+.. code-block:: text
+
+ - Now solving 'postcondition' VC for max @6:16...
+ - Result for 'postcondition' VC for max @6:16:
+ => INVALID
+ Found counter-example:
+ y: Int -> 2147483647
+ x: Int -> -2147483648
+
+Stainless tells us that it found two input for which the ``ensuring`` clause of the
+``max`` function evaluates to ``false``. The second verification is similar.
+
+We may wish to define a test method
+
+.. code-block:: scala
+
+ def test4 = max(-1639624704, 1879048192)
+
+whose evaluation indeed results in ``ensuring`` condition being violated.
+The problem is due to overflow of 32-bit integers, due to which
+the value `d` becomes positive, even though `x` is negative and thus smaller than
+the large positive value `y`.
+
+In fact, Stainless alerts us of this very problem in the third verification condition,
+to help us pin point the place where the overflow occured.
+
+.. note::
+
+ As in Scala, the `Int` type denotes 32-bit integers with the usual signed arithmetic
+ operations from computer architecture and the JVM specification.
+
+To use unbounded integers, we simply change the types to
+`BigInt`, obtaining a program that verifies (and, as
+expected, passes all the test cases).
+
+.. code-block:: scala
+
+ def max(x: BigInt, y: BigInt): BigInt = {
+ val d = x - y
+ if (d > 0) x
+ else y
+ } ensuring(res =>
+ x <= res && y <= res && (res == x || res == y))
+
+As a possibly simpler specification, we could have also
+defined the reference implementation
+
+.. code-block:: scala
+
+ def rmax(x: BigInt, y: BigInt) = {
+ if (x <= y) y else x
+ }
+
+and then used as the postcondition of `max` simply
+
+.. code-block:: scala
+
+ ensuring (res => res == rmax(x,y))
+
+In general, Stainless uses both function body and function
+specification when reasoning about the function and its
+uses. Thus, we need not repeat in the postcondition those
+aspects of function body that follow directly through
+inlining the function, but we may wish to state those
+that require induction to prove.
+
+The fact that we can use functions in preconditions
+and postconditions allows us to state fairly general
+properties. For example, the following lemma verifies
+a number of algebraic properties of `max`.
+
+.. code-block:: scala
+
+ def max_lemma(x: BigInt, y: BigInt, z: BigInt): Boolean = {
+ max(x,x) == x &&
+ max(x,y) == max(y,x) &&
+ max(x,max(y,z)) == max(max(x,y), z) &&
+ max(x,y) + z == max(x + z, y + z)
+ } holds
+
+Here `holds` operator on the function body is an
+abbreviation for the postcondition stating that the returned
+result is always true, that is, for
+
+.. code-block:: scala
+
+ ensuring(res => res==true)
+
+As a guideline, we typically use `holds` to express such
+algebraic properties that relate multiple invocations of
+functions, whereas we use `ensuring` to document property of
+an arbitrary single invocation of a function. Stainless is more likely to automatically
+use the property of a function if it is associated with it using
+`ensuring` than using an external lemma.
+
+Going back to our buggy implementation of `max` on `Int`-s,
+an alternative to using `BigInt`-s is to decide that
+the method should only be used under certain conditions,
+such as `x` and `y` being non-negative. To specify the
+conditions on input, we use the `require` clause.
+
+.. code-block:: scala
+
+ def max(x: Int, y: Int): Int = {
+ require(0 <= x && 0 <= y)
+ val d = x - y
+ if (d > 0) x
+ else y
+ } ensuring (res =>
+ x <= res && y <= res && (res == x || res == y))
+
+This program verifies and indeed works correctly on
+non-negative 32-bit integers as inputs.
+
+**Question:** What if we restrict the inputs to `max` to be
+`a)` non-positive, or `b)` strictly negative? Modify the
+`require` clause for each case accordingly and explain the
+behavior of Stainless. See the note below, as well.
+
+.. note::
+
+ By default, Stainless will emit verification conditions to
+ check that arithmetic operations on sized integers such as
+ `Int` cannot overflow. To opt-out of this behavior, eg. when
+ such wrapping semantics are desired, one can wrap the offending
+ expression in a call to `stainless.math.wrapping`:
+
+ .. code-block:: scala
+
+ import stainless.math.wrapping
+
+ def doubleOverflow(x: Int): Int = {
+ wrapping { x + x }
+ }
+
+In the sequel, we will mostly use `BigInt` types.
+
+Defining Lists and Their Properties
+-----------------------------------
+
+We next consider sorting an unbounded number of elements.
+For this purpose, we define a data structure for lists of
+integers. Stainless has a built-in data type of parametric
+lists, see :doc:`library`, but here we define
+our own variant instead.
+
+Lists
+^^^^^
+
+We use a recursive algebraic data type
+definition, expressed using Scala's **case classes**.
+
+.. code-block:: scala
+
+ sealed abstract class List
+ case object Nil extends List
+ case class Cons(head: BigInt, tail: List) extends List
+
+We can read the definition as follows: the set of lists is
+defined as the least set that satisfies them:
+
+ * empty list `Nil` is a list
+ * if `head` is an integer and `tail` is a `List`, then
+ `Cons(head,tail)` is a `List`.
+
+Each list is constructed by applying the above two rules
+finitely many times. A concrete list containing elements 5,
+2, and 7, in that order, is denoted
+
+.. code-block:: scala
+
+ Cons(5, Cons(2, Cons(7, Nil)))
+
+Having defined the structure of lists, we can move on to
+define some semantic properties of lists that are of
+interests. For this purpose, we use recursive functions
+defined on lists.
+
+Size of a List
+^^^^^^^^^^^^^^
+
+As the starting point, we define the size of a list.
+
+.. code-block:: scala
+
+ def size(l: List) : BigInt = (l match {
+ case Nil => 0
+ case Cons(x, rest) => 1 + size(rest)
+ })
+
+The definition uses *pattern matching* to define size of the
+list in the case it is empty (where it is zero) and when it
+is non-empty, or, if it's non-empty, then it has a head `x`
+and the rest of the list `rest`, so the size is one plus the
+size of the rest. Thus `size` is a recursive function. A
+strength of Stainless is that it allows using such recursive
+functions in specifications.
+
+It makes little sense to try to write a complete
+specification of `size`, given that its recursive definition
+is already a pretty clear description of its
+meaning. However, it is useful to add a consequence of this
+definition, namely that the size is non-negative. The reason
+is that Stainless most of the time reasons by unfolding `size`,
+and the property of size being non-negative is not revealed
+by such unfolding. Once specified, the non-negativity is
+easily proven and Stainless will make use of it.
+
+.. code-block:: scala
+
+
+ def isize(l: List) : Int = (l match {
+ case Nil => 0
+ case Cons(x, rest) => {
+ val rSize = isize(rest)
+ if (rSize == Int.MaxValue) rSize
+ else 1 + rSize
+ }
+ }).ensuring(res => res >= 0)
+
+In some cases, it may be helpful to define a size function
+that returns a bounded integer type, such as the 32-bit signed integer ```Int``.
+One useful way to do this is to define function as follows:
+
+.. code-block:: scala
+
+ def isize(l: List) : Int = (l match {
+ case Nil => 0
+ case Cons(x, rest) => {
+ val rSize = isize(rest)
+ if (rSize == Int.Max) rSize
+ else 1 + rSize
+ }
+ }) ensuring(res => res >= 0)
+
+The above ``isize`` function satisfies the usual recursive definition for all but a huge
+lists, returns a non-negative integer, and ensures that if isize returns a small
+number, then the list is indeed small.
+
+Sorted Lists
+^^^^^^^^^^^^
+
+We define properties of values simply as executable
+predicates that check if the property holds. The following
+is a property that a list is sorted in a strictly ascending
+order.
+
+.. code-block:: scala
+
+ def isSorted(l : List) : Boolean = l match {
+ case Nil => true
+ case Cons(_,Nil) => true
+ case Cons(x1, Cons(x2, rest)) =>
+ x1 < x2 && isSorted(Cons(x2,rest))
+ }
+
+Insertion into Sorted List
+--------------------------
+
+Consider the following specification of insertion into a sorted list. It's a
+building block for an insertion sort.
+
+.. code-block:: scala
+
+ def sInsert(x : BigInt, l : List) : List = {
+ require(isSorted(l))
+ l match {
+ case Nil => Cons(x, Nil)
+ case Cons(e, rest) if (x == e) => l
+ case Cons(e, rest) if (x < e) => Cons(x, Cons(e,rest))
+ case Cons(e, rest) if (x > e) => Cons(e, sInsert(x,rest))
+ }
+ } ensuring {(res:List) => isSorted(res)}
+
+Stainless verifies that the returned list is indeed sorted. Note
+how we are again using a recursively defined function to
+specify another function. We can introduce a bug into the
+definition above and examine the counterexamples that Stainless
+finds.
+
+Being Sorted is Not Enough
+--------------------------
+
+Note, however, that a function such as this one is also correct.
+
+.. code-block:: scala
+
+ def fsInsert(x : BigInt, l : List) : List = {
+ require(isSorted(l))
+ Nil
+ } ensuring {(res:List) => isSorted(res)}
+
+So, our specification may be considered weak, because it does
+not say anything about the elements.
+
+Using Size in Specification
+---------------------------
+
+Consider a stronger additional postcondition property:
+
+.. code-block:: scala
+
+ size(res) == size(l) + 1
+
+Does it hold? If we try to add it, we obtain a counterexample.
+A correct strengthening, taking into account that the element
+may or may not already be in the list, is the following.
+
+.. code-block:: scala
+
+ size(l) <= size(res) && size(res) <= size(l) + 1
+
+Using Content in Specification
+------------------------------
+
+A stronger specification needs to talk about the `content`
+of the list.
+
+.. code-block:: scala
+
+ def sInsert(x : BigInt, l : List) : List = {
+ require(isSorted(l))
+ l match {
+ case Nil => Cons(x, Nil)
+ case Cons(e, rest) if (x == e) => l
+ case Cons(e, rest) if (x < e) => Cons(x, Cons(e,rest))
+ case Cons(e, rest) if (x > e) => Cons(e, sInsert(x,rest))
+ }
+ } ensuring {(res:List) =>
+ isSorted(res) && content(res) == content(l) ++ Set(x)}
+
+To compute `content`, in this example we use sets (even
+though in general, it might be better to use bags
+i.e. multisets).
+
+.. code-block:: scala
+
+ def content(l: List): Set[BigInt] = l match {
+ case Nil => Set()
+ case Cons(i, t) => Set(i) ++ content(t)
+ }
+
+
+This completes the tutorial. To learn more, check the rest of this
+documentation and browse the examples provided with Stainless.
diff --git a/_sources/verification.rst.txt b/_sources/verification.rst.txt
new file mode 100644
index 0000000000..06f05b71b7
--- /dev/null
+++ b/_sources/verification.rst.txt
@@ -0,0 +1,281 @@
+.. _verification:
+
+Verification conditions
+=======================
+
+Software verification aims at making software safer. In its typical use case,
+it is a tool that takes as input the source code of a program with
+specifications as annotations and attempt to prove --- or disprove --- their
+validity.
+
+One of the core modules of Stainless is a verifier for the subset of Scala described
+in the sections :doc:`purescala` and :doc:`imperative`. In this
+section, we describe the specification language that can be used to declare
+properties of programs, as well as the safety properties automatically checked
+by Stainless. We also discuss how Stainless can be used to prove mathematical theorems.
+
+
+Given an input program, Stainless generates individual verification conditions
+corresponding to different properties of the program. A program is correct if
+all of the generated verification conditions are ``valid``. The validity of some
+conditions depends on the validity of other conditions --- typically a
+postcondition is ``valid`` assuming the precondition is ``valid``.
+
+For each function, Stainless attempts to verify its contract, if there is one. A
+*contract* is the combination of a *precondition* and a *postcondition*. A
+function meets its contract if, for any input parameter that passes the
+precondition, the postcondition holds after executing the function.
+Preconditions and postconditions are annotations given by the user --- they are
+the specifications and hence cannot be inferred by a tool and must be provided.
+
+In addition to user-provided contracts, Stainless will also generate a few safety
+verification conditions of its own. It will check that all of the array
+accesses are within proper bounds, and that pattern matching always covers all
+possible cases, even given complex precondition. The latter is different from
+the Scala compiler checks on pattern matching exhaustiveness, as Stainless considers
+information provided by (explicit or implicit) preconditions to the ``match``
+expression.
+
+Postconditions
+--------------
+
+One core concept in verification is to check the contract of functions. The most
+important part of a contract is the postcondition. The postcondition specifies
+the behavior of the function. It takes into account the precondition and only
+asserts the property of the output when the input satisfies the precondition.
+
+Formally, we consider a function with a single parameter (one can generalize
+the following for any number of parameters):
+
+.. code-block:: scala
+
+ def f(x: A): B = {
+ require(prec)
+ body
+ } ensuring(r => post)
+
+where, :math:`\mbox{prec}(x)` is a Boolean expression with free variables
+contained in :math:`\{ x \}`, :math:`\mbox{body}(x)` is an expression with
+free variables contained in :math:`\{ x \}` and :math:`\mbox{post}(x, r)` is a
+Boolean expression with free variables contained in :math:`\{ x, r \}`. The
+types of :math:`x` and :math:`r` are respectively ``A`` and ``B``. We write
+:math:`\mbox{expr}(a)` to mean the substitution in :math:`\mbox{expr}` of its
+free variable by :math:`a`.
+
+Stainless attempts to prove the following theorem:
+
+.. math::
+
+ \forall x. \mbox{prec}(x) \implies \mbox{post}(x, \mbox{body}(x))
+
+If Stainless is able to prove the above theorem, it returns ``valid`` for the
+function ``f``. This gives you a guarantee that the function ``f`` is correct
+with respect to its contract.
+
+However, if the theorem is not valid, Stainless will return a counterexample to the
+theorem. The negation of the theorem is:
+
+.. math::
+
+ \exists x. \mbox{prec}(x) \land \neg \mbox{post}(x, \mbox{body}(x))
+
+and to prove the validity of the negation, Stainless finds a witness :math:`x` --- a
+counterexample --- such that the precondition is verified and the postcondition
+is not.
+
+The general problem of verification is undecidable for a Turing-complete
+language, and the Stainless language is Turing-complete. So Stainless has to be
+incomplete in some sense. Generally, Stainless will eventually find a counterexample
+if one exists. However, in practice, some program structures require too many
+unrollings and Stainless is likely to timeout (or being out of memory) before
+finding the counterexample. When the postcondition is valid, it could also
+happen that Stainless keeps unrolling the program forever, without being able to
+prove the correctness. We discuss the exact conditions for this in the
+chapter on Stainless's algorithms.
+
+Preconditions
+-------------
+
+Preconditions are used as part of the contract of functions. They are a way to
+restrict the input to only relevant inputs, without having to implement guards
+and error handling in the functions themselves.
+
+Preconditions are contracts that the call sites should respect, and thus are
+not checked as part of verifying the function. Given the following definition:
+
+.. code-block:: scala
+
+ def f(x: A): B = {
+ require(prec)
+ body
+ }
+
+
+For each call site in the whole program (including in ``f`` itself):
+
+.. code-block:: scala
+
+ ...
+ f(e)
+ ...
+
+where the expression :math:`\mbox{e}(x)` is an expression of type ``A`` with
+free variables among :math:`\{ x \}`. Let us define the path condition on :math:`x`
+at that program point as :math:`\mbox{pc}(x)`. The path condition is a formula that
+summarizes the facts known about :math:`x` at that call site. A typical example is
+when the call site is inside an if expression:
+
+.. code-block:: scala
+
+ if(x > 0)
+ f(x)
+
+The path condition on :math:`x` would include the fact that :math:`x > 0`. This
+path condition is then used as a precondition of proving the validity of the
+call to :math:`\mbox{f}`. Formally, for each such call site, Stainless will attempt
+to prove the following theorem:
+
+.. math::
+
+ \forall x. \mbox{pc}(x) \implies \mbox{prec}(\mbox{e}(x))
+
+Stainless will generate one such theorem for each static call site of a function with
+a precondition.
+
+.. note::
+
+ Stainless only assumes an open program model, where any function could be called from
+ outside of the given program. In particular, Stainless will not derive a precondition
+ to a function based on known information in the context of the calls, such as
+ knowing that the function is always given positive parameters. Any information needed
+ to prove the postcondition will have to be provided as part of the precondition
+ of a function.
+
+
+Sharing bindings between specifications and function body
+---------------------------------------------------------
+
+The example `ValEnsuring `_
+shows that Stainless supports multiple ``require``'s (in functions, but not for ADT invariants), and
+shows how to share a `val` binding between precondition, postcondition, and function body.
+
+
+Loop invariants
+---------------
+
+Stainless supports annotations for loop invariants in :doc:`imperative`. To
+simplify the presentation we will assume a single variable :math:`x` is in
+scope, but the definitions generalize to any number of variables. Given the
+following program:
+
+.. code-block:: scala
+
+ (while(cond) {
+ body
+ }) invariant(inv)
+
+where the Boolean expression :math:`\mbox{cond}(x)` is over the free variable
+:math:`x` and the expression :math:`\mbox{body}(x, x')` relates the value of
+:math:`x` when entering the loop to its updated value :math:`x'` on loop exit.
+The expression :math:`\mbox{inv}(x)` is a Boolean formula over the free
+variable :math:`x`.
+
+A loop invariant must hold:
+ (1) when the program enters the loop initially
+ (2) after each completion of the body
+ (3) right after exiting the loop (when the condition turns false)
+
+Stainless will prove the points (1) and (2) above. Together, and by induction, they imply
+that point (3) holds as well.
+
+Stainless also supports ``noReturnInvariant`` (see `ReturnInWhile3 `_) to describe loop invariants that are allowed to be broken
+after a :doc:`return ` (can be combined with ``invariant``).
+
+Decrease annotation in loops
+----------------------------
+
+One can also specify that the value of a given expression of numerical type decreases
+at each loop iteration by adding a ``decreases`` measure within the loop body:
+
+.. code-block:: scala
+
+ while(cond) {
+ decreases(expr)
+ body
+ }
+
+Stainless will then emit a verification condition that checks whether the expression
+is strictly positive and decreases at each iteration.
+
+Array access safety
+-------------------
+
+Stainless generates verification conditions for the safety of array accesses. For
+each array variable, Stainless carries along a symbolic information on its length.
+This information is used to prove that each expression used as an index in the
+array is strictly smaller than that length. The expression is also checked to
+be positive.
+
+ADT invariants
+--------------
+
+Stainless lets the user write ADT invariants with the ``require`` keyword.
+Internally, such invariants are extracted as methods (named ``inv``). Whenever,
+an ADT is constructed, and to make sure that the invariant is true, a
+verification condition is generated with a call to the corresponding ``inv``
+method.
+
+The Stainless annotation ``@inlineInvariant`` used on an ADT or one of its
+ancestors can be used to inline the call to ``inv`` in the verification
+condition, as shown in the following example. This annotation is only
+supported when ``--type-checker=true`` (which is the case by default).
+
+.. code-block:: scala
+
+ import stainless.annotation._
+
+ object InlineInvariant {
+ sealed abstract class A
+
+ case class B(x: BigInt) extends A {
+ require(x >= 50)
+ }
+
+ @inlineInvariant
+ case class C(x: BigInt) extends A {
+ require(x >= 50)
+ }
+
+ def f(): A = {
+ B(100) // VC: inv(B(100))
+ c(100) // VC: 100 >= 50 (call to `inv` was inlined)
+ }
+ }
+
+
+
+Pattern matching exhaustiveness
+-------------------------------
+
+Stainless verifies that pattern matching is exhaustive. The regular Scala compiler
+only considers the types of expression involved in pattern matching, but Stainless
+will consider information such as precondition to formally prove the
+exhaustiveness of pattern matching.
+
+As an example, the following code should issue a warning with Scala:
+
+.. code-block:: scala
+
+ abstract class List
+ case class Cons(head: Int, tail: List) extends List
+ case object Nil extends List
+
+ def getHead(l: List): Int = {
+ require(!l.isInstanceOf[Nil])
+ l match {
+ case Cons(x, _) => x
+ }
+ }
+
+But Stainless will prove that the pattern matching is actually exhaustive,
+relying on the given precondition.
diff --git a/_sources/wrap.rst.txt b/_sources/wrap.rst.txt
new file mode 100644
index 0000000000..7094bda356
--- /dev/null
+++ b/_sources/wrap.rst.txt
@@ -0,0 +1,239 @@
+.. _wrap:
+
+Working With Existing Code
+==========================
+
+While the subset of Scala (namely, PureScala) that is currently supported by Stainless
+is already expressive enough to implement a lot of different data structures and algorithms,
+it is often the case that one would like to avoid re-implementing a piece of code from scratch
+in this fragment, but rather re-use some existing code, whether it is part of the codebase or
+pulled in from a Java or Scala library.
+
+A wrapper for TrieMap
+---------------------
+
+As a running example, let's write a wrapper for the ``scala.collection.concurrent.TrieMap`` class.
+A first attempt to wrap it in a regular Stainless datatype could look like the following:
+
+.. code-block:: scala
+
+ import stainless.lang._
+ import stainless.annotation._
+
+ import scala.collection.concurrent.TrieMap
+
+ case class TrieMapWrapper[K, V](theMap: TrieMap[K, V])
+
+Unfortunately, this will not work as Stainless will complain that it does not
+know about the ``TrieMap`` type. In order to work around this, one can annotate
+the field with the ``@extern`` annotation, which tells Stainless that the type
+should be treated as opaque.
+
+.. code-block:: scala
+
+ import stainless.lang._
+ import stainless.annotation._
+
+ import scala.collection.concurrent.TrieMap
+ import scala.collection.concurrent.TrieMap
+
+ case class TrieMapWrapper[K, V](@extern theMap: TrieMap[K, V])
+
+Extern methods
+--------------
+
+Let's now define a forwarding method for the ``contains`` method of ``TrieMap``:
+
+.. code-block:: scala
+
+ import stainless.lang._
+ import stainless.annotation._
+
+ import scala.collection.concurrent.TrieMap
+ import scala.collection.concurrent.TrieMap
+
+ case class TrieMapWrapper[K, V](@extern theMap: TrieMap[K, V]) {
+
+ def contains(k: K): Boolean = {
+ theMap contains k
+ }
+ }
+
+Once again, this will fail because, from Stainless' point of view, ``theMap`` has an opaque type
+and thus has no ``contains`` method. By annotating the method itself with ``@extern``, Stainless will
+not attempt to extract the method's body, and we can thus freely refer to any of ``TrieMap``'s methods:
+
+.. code-block:: scala
+
+ import stainless.lang._
+ import stainless.annotation._
+
+ import scala.collection.concurrent.TrieMap
+
+ case class TrieMapWrapper[K, V](@extern theMap: TrieMap[K, V]) {
+
+ @extern
+ def contains(k: K): Boolean = {
+ theMap contains k
+ }
+ }
+
+.. note::
+ Methods marked ``@extern`` are allowed to mention types which Stainless is not able to extract.
+ Such types will be replaced by the *unknown type* ``?`` during the recovery phase.
+ One can inspect which types are replaced during recovery, by supplying the ``--debug=recovery`` flag.
+
+Contracts
+---------
+
+Let's also define another extern function, which creates a new empty map:
+
+.. code-block:: scala
+
+ object TrieMapWrapper {
+ @extern
+ def empty[K, V]: TrieMapWrapper[K, V] = {
+ TrieMapWrapper(TrieMap.empty[K, V])
+ }
+ }
+
+ def prop1 = {
+ val wrapper = TrieMapWrapper.empty[Int, String]
+ assert(!wrapper.contains(42)) // invalid
+ }
+
+Indeed, because Stainless does not know about ``TrieMap.empty``, it cannot assume
+by itself that the result of ``TrieMapWrapper.empty`` does not contain any entries.
+
+We can remedy to that by adding a postcondition to the ``empty`` function which says that,
+for any key ``k`` of type ``K``, the result of ``TrieMapWrapper.empty`` does not contain the key ``k``.
+
+.. code-block:: scala
+
+ object TrieMapWrapper {
+ @extern
+ def empty[K, V]: TrieMapWrapper[K, V] = {
+ TrieMapWrapper(TrieMap.empty[K, V])
+ } ensuring { res =>
+ forall((k: K) => !res.contains(k))
+ }
+ }
+
+The assertion above now verifies successfully.
+
+Purity annotations
+------------------
+
+Let's now see what happens when we call ``contains`` twice:
+
+.. code-block:: scala
+
+ def prop1 = {
+ val wrapper = TrieMapWrapper.empty[Int, String]
+ assert(!wrapper.contains(42))
+ assert(!wrapper.contains(42))
+ }
+
+.. code-block:: text
+
+ ┌───────────────────┐
+ ╔═╡ stainless summary ╞═══════════════════════════════════════════════════╗
+ ║ └───────────────────┘ ║
+ ║ prop1 body assertion valid U:smt-z3 ExternField.scala:46:5 0.018 ║
+ ║ prop1 body assertion invalid U:smt-z3 ExternField.scala:47:5 0.110 ║
+ ╚═════════════════════════════════════════════════════════════════════════╝
+
+The second assertion (perhaps surprisingly) fails to verify. This stems from the fact that Stainless assumes
+by default that extern functions and methods mutate their arguments. Indeed, because Stainless
+does not know about the body of such methods, it cannot know whether such a function is pure or not.
+It is thus up to the user to instruct Stainless otherwise, by annotating the function with ``@pure``:
+
+.. code-block:: scala
+
+ case class TrieMapWrapper[K, V](@extern theMap: TrieMap[K, V]) {
+
+ @extern @pure
+ def contains(k: K): Boolean = {
+ theMap contains k
+ }
+ }
+
+With the annotation, the two assertions above now verify:
+
+.. code-block:: text
+
+ ┌───────────────────┐
+ ╔═╡ stainless summary ╞═════════════════════════════════════════════════╗
+ ║ └───────────────────┘ ║
+ ║ prop1 body assertion valid U:smt-z3 ExternField.scala:46:5 0.018 ║
+ ║ prop1 body assertion valid U:smt-z3 ExternField.scala:48:5 0.110 ║
+ ╚═══════════════════════════════════════════════════════════════════════╝
+
+We can now define the other methods of interest, with their appropriate contract:
+
+.. code-block:: scala
+
+ import stainless.lang._
+ import stainless.annotation._
+ import scala.annotation.meta.field
+
+ import scala.collection.concurrent.TrieMap
+
+ case class TrieMapWrapper[K, V](
+ @extern
+ theMap: TrieMap[K, V]
+ ) {
+
+ @extern @pure
+ def contains(k: K): Boolean = {
+ theMap contains k
+ }
+
+ @extern
+ def insert(k: K, v: V): Unit = {
+ theMap.update(k, v)
+ } ensuring {
+ this.contains(k) &&
+ this.apply(k) == v
+ }
+
+ @extern @pure
+ def apply(k: K): V = {
+ require(contains(k))
+ theMap(k)
+ }
+ }
+
+ object TrieMapWrapper {
+ @extern @pure
+ def empty[K, V]: TrieMapWrapper[K, V] = {
+ TrieMapWrapper(TrieMap.empty[K, V])
+ } ensuring { res =>
+ forall((k: K) => !res.contains(k))
+ }
+ }
+
+And we can now reason about our wrapper for ``TrieMap``:
+
+.. code-block:: scala
+
+ def prop2 = {
+ val wrapper = TrieMapWrapper.empty[BigInt, String]
+ assert(!wrapper.contains(42))
+ wrapper.insert(42, "Hello")
+ assert(wrapper.contains(42))
+ assert(wrapper(42) == "Hello")
+ }
+
+.. code-block:: text
+
+ ┌───────────────────┐
+ ╔═╡ stainless summary ╞═════════════════════════════════════════════════════════════════════════════════╗
+ ║ └───────────────────┘ ║
+ ║ prop2 body assertion valid U:smt-z3 ExternField.scala:56:5 0.023 ║
+ ║ prop2 body assertion valid U:smt-z3 ExternField.scala:58:5 0.095 ║
+ ║ prop2 body assertion valid U:smt-z3 ExternField.scala:59:5 0.080 ║
+ ║ prop2 precond. (apply[BigInt, String](wrapper, 42)) valid U:smt-z3 ExternField.scala:59:12 0.200 ║
+ ╟-------------------------------------------------------------------------------------------------------╢
+ ║ total: 4 valid: 4 (0 from cache) invalid: 0 unknown: 0 time: 0.398 ║
+ ╚═══════════════════════════════════════════════════════════════════════════════════════════════════════╝
diff --git a/_static/basic.css b/_static/basic.css
new file mode 100644
index 0000000000..603f6a8798
--- /dev/null
+++ b/_static/basic.css
@@ -0,0 +1,905 @@
+/*
+ * basic.css
+ * ~~~~~~~~~
+ *
+ * Sphinx stylesheet -- basic theme.
+ *
+ * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/* -- main layout ----------------------------------------------------------- */
+
+div.clearer {
+ clear: both;
+}
+
+div.section::after {
+ display: block;
+ content: '';
+ clear: left;
+}
+
+/* -- relbar ---------------------------------------------------------------- */
+
+div.related {
+ width: 100%;
+ font-size: 90%;
+}
+
+div.related h3 {
+ display: none;
+}
+
+div.related ul {
+ margin: 0;
+ padding: 0 0 0 10px;
+ list-style: none;
+}
+
+div.related li {
+ display: inline;
+}
+
+div.related li.right {
+ float: right;
+ margin-right: 5px;
+}
+
+/* -- sidebar --------------------------------------------------------------- */
+
+div.sphinxsidebarwrapper {
+ padding: 10px 5px 0 10px;
+}
+
+div.sphinxsidebar {
+ float: left;
+ width: 230px;
+ margin-left: -100%;
+ font-size: 90%;
+ word-wrap: break-word;
+ overflow-wrap : break-word;
+}
+
+div.sphinxsidebar ul {
+ list-style: none;
+}
+
+div.sphinxsidebar ul ul,
+div.sphinxsidebar ul.want-points {
+ margin-left: 20px;
+ list-style: square;
+}
+
+div.sphinxsidebar ul ul {
+ margin-top: 0;
+ margin-bottom: 0;
+}
+
+div.sphinxsidebar form {
+ margin-top: 10px;
+}
+
+div.sphinxsidebar input {
+ border: 1px solid #98dbcc;
+ font-family: sans-serif;
+ font-size: 1em;
+}
+
+div.sphinxsidebar #searchbox form.search {
+ overflow: hidden;
+}
+
+div.sphinxsidebar #searchbox input[type="text"] {
+ float: left;
+ width: 80%;
+ padding: 0.25em;
+ box-sizing: border-box;
+}
+
+div.sphinxsidebar #searchbox input[type="submit"] {
+ float: left;
+ width: 20%;
+ border-left: none;
+ padding: 0.25em;
+ box-sizing: border-box;
+}
+
+
+img {
+ border: 0;
+ max-width: 100%;
+}
+
+/* -- search page ----------------------------------------------------------- */
+
+ul.search {
+ margin: 10px 0 0 20px;
+ padding: 0;
+}
+
+ul.search li {
+ padding: 5px 0 5px 20px;
+ background-image: url(file.png);
+ background-repeat: no-repeat;
+ background-position: 0 7px;
+}
+
+ul.search li a {
+ font-weight: bold;
+}
+
+ul.search li p.context {
+ color: #888;
+ margin: 2px 0 0 30px;
+ text-align: left;
+}
+
+ul.keywordmatches li.goodmatch a {
+ font-weight: bold;
+}
+
+/* -- index page ------------------------------------------------------------ */
+
+table.contentstable {
+ width: 90%;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+table.contentstable p.biglink {
+ line-height: 150%;
+}
+
+a.biglink {
+ font-size: 1.3em;
+}
+
+span.linkdescr {
+ font-style: italic;
+ padding-top: 5px;
+ font-size: 90%;
+}
+
+/* -- general index --------------------------------------------------------- */
+
+table.indextable {
+ width: 100%;
+}
+
+table.indextable td {
+ text-align: left;
+ vertical-align: top;
+}
+
+table.indextable ul {
+ margin-top: 0;
+ margin-bottom: 0;
+ list-style-type: none;
+}
+
+table.indextable > tbody > tr > td > ul {
+ padding-left: 0em;
+}
+
+table.indextable tr.pcap {
+ height: 10px;
+}
+
+table.indextable tr.cap {
+ margin-top: 10px;
+ background-color: #f2f2f2;
+}
+
+img.toggler {
+ margin-right: 3px;
+ margin-top: 3px;
+ cursor: pointer;
+}
+
+div.modindex-jumpbox {
+ border-top: 1px solid #ddd;
+ border-bottom: 1px solid #ddd;
+ margin: 1em 0 1em 0;
+ padding: 0.4em;
+}
+
+div.genindex-jumpbox {
+ border-top: 1px solid #ddd;
+ border-bottom: 1px solid #ddd;
+ margin: 1em 0 1em 0;
+ padding: 0.4em;
+}
+
+/* -- domain module index --------------------------------------------------- */
+
+table.modindextable td {
+ padding: 2px;
+ border-collapse: collapse;
+}
+
+/* -- general body styles --------------------------------------------------- */
+
+div.body {
+ min-width: 450px;
+ max-width: 800px;
+}
+
+div.body p, div.body dd, div.body li, div.body blockquote {
+ -moz-hyphens: auto;
+ -ms-hyphens: auto;
+ -webkit-hyphens: auto;
+ hyphens: auto;
+}
+
+a.headerlink {
+ visibility: hidden;
+}
+
+a.brackets:before,
+span.brackets > a:before{
+ content: "[";
+}
+
+a.brackets:after,
+span.brackets > a:after {
+ content: "]";
+}
+
+h1:hover > a.headerlink,
+h2:hover > a.headerlink,
+h3:hover > a.headerlink,
+h4:hover > a.headerlink,
+h5:hover > a.headerlink,
+h6:hover > a.headerlink,
+dt:hover > a.headerlink,
+caption:hover > a.headerlink,
+p.caption:hover > a.headerlink,
+div.code-block-caption:hover > a.headerlink {
+ visibility: visible;
+}
+
+div.body p.caption {
+ text-align: inherit;
+}
+
+div.body td {
+ text-align: left;
+}
+
+.first {
+ margin-top: 0 !important;
+}
+
+p.rubric {
+ margin-top: 30px;
+ font-weight: bold;
+}
+
+img.align-left, figure.align-left, .figure.align-left, object.align-left {
+ clear: left;
+ float: left;
+ margin-right: 1em;
+}
+
+img.align-right, figure.align-right, .figure.align-right, object.align-right {
+ clear: right;
+ float: right;
+ margin-left: 1em;
+}
+
+img.align-center, figure.align-center, .figure.align-center, object.align-center {
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+img.align-default, figure.align-default, .figure.align-default {
+ display: block;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+.align-left {
+ text-align: left;
+}
+
+.align-center {
+ text-align: center;
+}
+
+.align-default {
+ text-align: center;
+}
+
+.align-right {
+ text-align: right;
+}
+
+/* -- sidebars -------------------------------------------------------------- */
+
+div.sidebar,
+aside.sidebar {
+ margin: 0 0 0.5em 1em;
+ border: 1px solid #ddb;
+ padding: 7px;
+ background-color: #ffe;
+ width: 40%;
+ float: right;
+ clear: right;
+ overflow-x: auto;
+}
+
+p.sidebar-title {
+ font-weight: bold;
+}
+
+div.admonition, div.topic, blockquote {
+ clear: left;
+}
+
+/* -- topics ---------------------------------------------------------------- */
+
+div.topic {
+ border: 1px solid #ccc;
+ padding: 7px;
+ margin: 10px 0 10px 0;
+}
+
+p.topic-title {
+ font-size: 1.1em;
+ font-weight: bold;
+ margin-top: 10px;
+}
+
+/* -- admonitions ----------------------------------------------------------- */
+
+div.admonition {
+ margin-top: 10px;
+ margin-bottom: 10px;
+ padding: 7px;
+}
+
+div.admonition dt {
+ font-weight: bold;
+}
+
+p.admonition-title {
+ margin: 0px 10px 5px 0px;
+ font-weight: bold;
+}
+
+div.body p.centered {
+ text-align: center;
+ margin-top: 25px;
+}
+
+/* -- content of sidebars/topics/admonitions -------------------------------- */
+
+div.sidebar > :last-child,
+aside.sidebar > :last-child,
+div.topic > :last-child,
+div.admonition > :last-child {
+ margin-bottom: 0;
+}
+
+div.sidebar::after,
+aside.sidebar::after,
+div.topic::after,
+div.admonition::after,
+blockquote::after {
+ display: block;
+ content: '';
+ clear: both;
+}
+
+/* -- tables ---------------------------------------------------------------- */
+
+table.docutils {
+ margin-top: 10px;
+ margin-bottom: 10px;
+ border: 0;
+ border-collapse: collapse;
+}
+
+table.align-center {
+ margin-left: auto;
+ margin-right: auto;
+}
+
+table.align-default {
+ margin-left: auto;
+ margin-right: auto;
+}
+
+table caption span.caption-number {
+ font-style: italic;
+}
+
+table caption span.caption-text {
+}
+
+table.docutils td, table.docutils th {
+ padding: 1px 8px 1px 5px;
+ border-top: 0;
+ border-left: 0;
+ border-right: 0;
+ border-bottom: 1px solid #aaa;
+}
+
+table.footnote td, table.footnote th {
+ border: 0 !important;
+}
+
+th {
+ text-align: left;
+ padding-right: 5px;
+}
+
+table.citation {
+ border-left: solid 1px gray;
+ margin-left: 1px;
+}
+
+table.citation td {
+ border-bottom: none;
+}
+
+th > :first-child,
+td > :first-child {
+ margin-top: 0px;
+}
+
+th > :last-child,
+td > :last-child {
+ margin-bottom: 0px;
+}
+
+/* -- figures --------------------------------------------------------------- */
+
+div.figure, figure {
+ margin: 0.5em;
+ padding: 0.5em;
+}
+
+div.figure p.caption, figcaption {
+ padding: 0.3em;
+}
+
+div.figure p.caption span.caption-number,
+figcaption span.caption-number {
+ font-style: italic;
+}
+
+div.figure p.caption span.caption-text,
+figcaption span.caption-text {
+}
+
+/* -- field list styles ----------------------------------------------------- */
+
+table.field-list td, table.field-list th {
+ border: 0 !important;
+}
+
+.field-list ul {
+ margin: 0;
+ padding-left: 1em;
+}
+
+.field-list p {
+ margin: 0;
+}
+
+.field-name {
+ -moz-hyphens: manual;
+ -ms-hyphens: manual;
+ -webkit-hyphens: manual;
+ hyphens: manual;
+}
+
+/* -- hlist styles ---------------------------------------------------------- */
+
+table.hlist {
+ margin: 1em 0;
+}
+
+table.hlist td {
+ vertical-align: top;
+}
+
+/* -- object description styles --------------------------------------------- */
+
+.sig {
+ font-family: 'Consolas', 'Menlo', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', monospace;
+}
+
+.sig-name, code.descname {
+ background-color: transparent;
+ font-weight: bold;
+}
+
+.sig-name {
+ font-size: 1.1em;
+}
+
+code.descname {
+ font-size: 1.2em;
+}
+
+.sig-prename, code.descclassname {
+ background-color: transparent;
+}
+
+.optional {
+ font-size: 1.3em;
+}
+
+.sig-paren {
+ font-size: larger;
+}
+
+.sig-param.n {
+ font-style: italic;
+}
+
+/* C++ specific styling */
+
+.sig-inline.c-texpr,
+.sig-inline.cpp-texpr {
+ font-family: unset;
+}
+
+.sig.c .k, .sig.c .kt,
+.sig.cpp .k, .sig.cpp .kt {
+ color: #0033B3;
+}
+
+.sig.c .m,
+.sig.cpp .m {
+ color: #1750EB;
+}
+
+.sig.c .s, .sig.c .sc,
+.sig.cpp .s, .sig.cpp .sc {
+ color: #067D17;
+}
+
+
+/* -- other body styles ----------------------------------------------------- */
+
+ol.arabic {
+ list-style: decimal;
+}
+
+ol.loweralpha {
+ list-style: lower-alpha;
+}
+
+ol.upperalpha {
+ list-style: upper-alpha;
+}
+
+ol.lowerroman {
+ list-style: lower-roman;
+}
+
+ol.upperroman {
+ list-style: upper-roman;
+}
+
+:not(li) > ol > li:first-child > :first-child,
+:not(li) > ul > li:first-child > :first-child {
+ margin-top: 0px;
+}
+
+:not(li) > ol > li:last-child > :last-child,
+:not(li) > ul > li:last-child > :last-child {
+ margin-bottom: 0px;
+}
+
+ol.simple ol p,
+ol.simple ul p,
+ul.simple ol p,
+ul.simple ul p {
+ margin-top: 0;
+}
+
+ol.simple > li:not(:first-child) > p,
+ul.simple > li:not(:first-child) > p {
+ margin-top: 0;
+}
+
+ol.simple p,
+ul.simple p {
+ margin-bottom: 0;
+}
+
+dl.footnote > dt,
+dl.citation > dt {
+ float: left;
+ margin-right: 0.5em;
+}
+
+dl.footnote > dd,
+dl.citation > dd {
+ margin-bottom: 0em;
+}
+
+dl.footnote > dd:after,
+dl.citation > dd:after {
+ content: "";
+ clear: both;
+}
+
+dl.field-list {
+ display: grid;
+ grid-template-columns: fit-content(30%) auto;
+}
+
+dl.field-list > dt {
+ font-weight: bold;
+ word-break: break-word;
+ padding-left: 0.5em;
+ padding-right: 5px;
+}
+
+dl.field-list > dt:after {
+ content: ":";
+}
+
+dl.field-list > dd {
+ padding-left: 0.5em;
+ margin-top: 0em;
+ margin-left: 0em;
+ margin-bottom: 0em;
+}
+
+dl {
+ margin-bottom: 15px;
+}
+
+dd > :first-child {
+ margin-top: 0px;
+}
+
+dd ul, dd table {
+ margin-bottom: 10px;
+}
+
+dd {
+ margin-top: 3px;
+ margin-bottom: 10px;
+ margin-left: 30px;
+}
+
+dl > dd:last-child,
+dl > dd:last-child > :last-child {
+ margin-bottom: 0;
+}
+
+dt:target, span.highlighted {
+ background-color: #fbe54e;
+}
+
+rect.highlighted {
+ fill: #fbe54e;
+}
+
+dl.glossary dt {
+ font-weight: bold;
+ font-size: 1.1em;
+}
+
+.versionmodified {
+ font-style: italic;
+}
+
+.system-message {
+ background-color: #fda;
+ padding: 5px;
+ border: 3px solid red;
+}
+
+.footnote:target {
+ background-color: #ffa;
+}
+
+.line-block {
+ display: block;
+ margin-top: 1em;
+ margin-bottom: 1em;
+}
+
+.line-block .line-block {
+ margin-top: 0;
+ margin-bottom: 0;
+ margin-left: 1.5em;
+}
+
+.guilabel, .menuselection {
+ font-family: sans-serif;
+}
+
+.accelerator {
+ text-decoration: underline;
+}
+
+.classifier {
+ font-style: oblique;
+}
+
+.classifier:before {
+ font-style: normal;
+ margin: 0 0.5em;
+ content: ":";
+ display: inline-block;
+}
+
+abbr, acronym {
+ border-bottom: dotted 1px;
+ cursor: help;
+}
+
+/* -- code displays --------------------------------------------------------- */
+
+pre {
+ overflow: auto;
+ overflow-y: hidden; /* fixes display issues on Chrome browsers */
+}
+
+pre, div[class*="highlight-"] {
+ clear: both;
+}
+
+span.pre {
+ -moz-hyphens: none;
+ -ms-hyphens: none;
+ -webkit-hyphens: none;
+ hyphens: none;
+}
+
+div[class*="highlight-"] {
+ margin: 1em 0;
+}
+
+td.linenos pre {
+ border: 0;
+ background-color: transparent;
+ color: #aaa;
+}
+
+table.highlighttable {
+ display: block;
+}
+
+table.highlighttable tbody {
+ display: block;
+}
+
+table.highlighttable tr {
+ display: flex;
+}
+
+table.highlighttable td {
+ margin: 0;
+ padding: 0;
+}
+
+table.highlighttable td.linenos {
+ padding-right: 0.5em;
+}
+
+table.highlighttable td.code {
+ flex: 1;
+ overflow: hidden;
+}
+
+.highlight .hll {
+ display: block;
+}
+
+div.highlight pre,
+table.highlighttable pre {
+ margin: 0;
+}
+
+div.code-block-caption + div {
+ margin-top: 0;
+}
+
+div.code-block-caption {
+ margin-top: 1em;
+ padding: 2px 5px;
+ font-size: small;
+}
+
+div.code-block-caption code {
+ background-color: transparent;
+}
+
+table.highlighttable td.linenos,
+span.linenos,
+div.highlight span.gp { /* gp: Generic.Prompt */
+ user-select: none;
+ -webkit-user-select: text; /* Safari fallback only */
+ -webkit-user-select: none; /* Chrome/Safari */
+ -moz-user-select: none; /* Firefox */
+ -ms-user-select: none; /* IE10+ */
+}
+
+div.code-block-caption span.caption-number {
+ padding: 0.1em 0.3em;
+ font-style: italic;
+}
+
+div.code-block-caption span.caption-text {
+}
+
+div.literal-block-wrapper {
+ margin: 1em 0;
+}
+
+code.xref, a code {
+ background-color: transparent;
+ font-weight: bold;
+}
+
+h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
+ background-color: transparent;
+}
+
+.viewcode-link {
+ float: right;
+}
+
+.viewcode-back {
+ float: right;
+ font-family: sans-serif;
+}
+
+div.viewcode-block:target {
+ margin: -1px -10px;
+ padding: 0 10px;
+}
+
+/* -- math display ---------------------------------------------------------- */
+
+img.math {
+ vertical-align: middle;
+}
+
+div.body div.math p {
+ text-align: center;
+}
+
+span.eqno {
+ float: right;
+}
+
+span.eqno a.headerlink {
+ position: absolute;
+ z-index: 1;
+}
+
+div.math:hover a.headerlink {
+ visibility: visible;
+}
+
+/* -- printout stylesheet --------------------------------------------------- */
+
+@media print {
+ div.document,
+ div.documentwrapper,
+ div.bodywrapper {
+ margin: 0 !important;
+ width: 100%;
+ }
+
+ div.sphinxsidebar,
+ div.related,
+ div.footer,
+ #top-link {
+ display: none;
+ }
+}
\ No newline at end of file
diff --git a/_static/css/badge_only.css b/_static/css/badge_only.css
new file mode 100644
index 0000000000..e380325bc6
--- /dev/null
+++ b/_static/css/badge_only.css
@@ -0,0 +1 @@
+.fa:before{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}@font-face{font-family:FontAwesome;font-style:normal;font-weight:400;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#FontAwesome) format("svg")}.fa:before{font-family:FontAwesome;font-style:normal;font-weight:400;line-height:1}.fa:before,a .fa{text-decoration:inherit}.fa:before,a .fa,li .fa{display:inline-block}li .fa-large:before{width:1.875em}ul.fas{list-style-type:none;margin-left:2em;text-indent:-.8em}ul.fas li .fa{width:.8em}ul.fas li .fa-large:before{vertical-align:baseline}.fa-book:before,.icon-book:before{content:"\f02d"}.fa-caret-down:before,.icon-caret-down:before{content:"\f0d7"}.fa-caret-up:before,.icon-caret-up:before{content:"\f0d8"}.fa-caret-left:before,.icon-caret-left:before{content:"\f0d9"}.fa-caret-right:before,.icon-caret-right:before{content:"\f0da"}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60}.rst-versions .rst-current-version:after{clear:both;content:"";display:block}.rst-versions .rst-current-version .fa{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}
\ No newline at end of file
diff --git a/_static/css/fonts/IBM Plex Sans Var-Italic.woff2 b/_static/css/fonts/IBM Plex Sans Var-Italic.woff2
new file mode 100644
index 0000000000..74acd8daff
Binary files /dev/null and b/_static/css/fonts/IBM Plex Sans Var-Italic.woff2 differ
diff --git a/_static/css/fonts/IBM Plex Sans Var-Roman.woff2 b/_static/css/fonts/IBM Plex Sans Var-Roman.woff2
new file mode 100644
index 0000000000..209e600fe2
Binary files /dev/null and b/_static/css/fonts/IBM Plex Sans Var-Roman.woff2 differ
diff --git a/_static/css/fonts/IBMPlexMono-Regular.woff2 b/_static/css/fonts/IBMPlexMono-Regular.woff2
new file mode 100644
index 0000000000..84c87e05a7
Binary files /dev/null and b/_static/css/fonts/IBMPlexMono-Regular.woff2 differ
diff --git a/_static/css/fonts/Roboto-Slab-Bold.woff b/_static/css/fonts/Roboto-Slab-Bold.woff
new file mode 100644
index 0000000000..6cb6000018
Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Bold.woff differ
diff --git a/_static/css/fonts/Roboto-Slab-Bold.woff2 b/_static/css/fonts/Roboto-Slab-Bold.woff2
new file mode 100644
index 0000000000..7059e23142
Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Bold.woff2 differ
diff --git a/_static/css/fonts/Roboto-Slab-Regular.woff b/_static/css/fonts/Roboto-Slab-Regular.woff
new file mode 100644
index 0000000000..f815f63f99
Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Regular.woff differ
diff --git a/_static/css/fonts/Roboto-Slab-Regular.woff2 b/_static/css/fonts/Roboto-Slab-Regular.woff2
new file mode 100644
index 0000000000..f2c76e5bda
Binary files /dev/null and b/_static/css/fonts/Roboto-Slab-Regular.woff2 differ
diff --git a/_static/css/fonts/fontawesome-webfont.eot b/_static/css/fonts/fontawesome-webfont.eot
new file mode 100644
index 0000000000..e9f60ca953
Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.eot differ
diff --git a/_static/css/fonts/fontawesome-webfont.svg b/_static/css/fonts/fontawesome-webfont.svg
new file mode 100644
index 0000000000..855c845e53
--- /dev/null
+++ b/_static/css/fonts/fontawesome-webfont.svg
@@ -0,0 +1,2671 @@
+
+
+
diff --git a/_static/css/fonts/fontawesome-webfont.ttf b/_static/css/fonts/fontawesome-webfont.ttf
new file mode 100644
index 0000000000..35acda2fa1
Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.ttf differ
diff --git a/_static/css/fonts/fontawesome-webfont.woff b/_static/css/fonts/fontawesome-webfont.woff
new file mode 100644
index 0000000000..400014a4b0
Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.woff differ
diff --git a/_static/css/fonts/fontawesome-webfont.woff2 b/_static/css/fonts/fontawesome-webfont.woff2
new file mode 100644
index 0000000000..4d13fc6040
Binary files /dev/null and b/_static/css/fonts/fontawesome-webfont.woff2 differ
diff --git a/_static/css/fonts/lato-bold-italic.woff b/_static/css/fonts/lato-bold-italic.woff
new file mode 100644
index 0000000000..88ad05b9ff
Binary files /dev/null and b/_static/css/fonts/lato-bold-italic.woff differ
diff --git a/_static/css/fonts/lato-bold-italic.woff2 b/_static/css/fonts/lato-bold-italic.woff2
new file mode 100644
index 0000000000..c4e3d804b5
Binary files /dev/null and b/_static/css/fonts/lato-bold-italic.woff2 differ
diff --git a/_static/css/fonts/lato-bold.woff b/_static/css/fonts/lato-bold.woff
new file mode 100644
index 0000000000..c6dff51f06
Binary files /dev/null and b/_static/css/fonts/lato-bold.woff differ
diff --git a/_static/css/fonts/lato-bold.woff2 b/_static/css/fonts/lato-bold.woff2
new file mode 100644
index 0000000000..bb195043cf
Binary files /dev/null and b/_static/css/fonts/lato-bold.woff2 differ
diff --git a/_static/css/fonts/lato-normal-italic.woff b/_static/css/fonts/lato-normal-italic.woff
new file mode 100644
index 0000000000..76114bc033
Binary files /dev/null and b/_static/css/fonts/lato-normal-italic.woff differ
diff --git a/_static/css/fonts/lato-normal-italic.woff2 b/_static/css/fonts/lato-normal-italic.woff2
new file mode 100644
index 0000000000..3404f37e2e
Binary files /dev/null and b/_static/css/fonts/lato-normal-italic.woff2 differ
diff --git a/_static/css/fonts/lato-normal.woff b/_static/css/fonts/lato-normal.woff
new file mode 100644
index 0000000000..ae1307ff5f
Binary files /dev/null and b/_static/css/fonts/lato-normal.woff differ
diff --git a/_static/css/fonts/lato-normal.woff2 b/_static/css/fonts/lato-normal.woff2
new file mode 100644
index 0000000000..3bf9843328
Binary files /dev/null and b/_static/css/fonts/lato-normal.woff2 differ
diff --git a/_static/css/theme.css b/_static/css/theme.css
new file mode 100644
index 0000000000..42c1cfee6e
--- /dev/null
+++ b/_static/css/theme.css
@@ -0,0 +1,4 @@
+html{box-sizing:border-box}*,:after,:before{box-sizing:inherit}article,aside,details,figcaption,figure,footer,header,hgroup,nav,section{display:block}audio,canvas,video{display:inline-block;*display:inline;*zoom:1}[hidden],audio:not([controls]){display:none}*{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}html{font-size:100%;-webkit-text-size-adjust:100%;-ms-text-size-adjust:100%}body{margin:0}a:active,a:hover{outline:0}abbr[title]{border-bottom:1px dotted}b,strong{font-weight:700}blockquote{margin:0}dfn{font-style:italic}ins{background:#ff9;text-decoration:none}ins,mark{color:#000}mark{background:#ff0;font-style:italic;font-weight:700}.rst-content code,.rst-content tt,code,kbd,pre,samp{font-family:monospace,serif;_font-family:courier new,monospace;font-size:1em}pre{white-space:pre}q{quotes:none}q:after,q:before{content:"";content:none}small{font-size:85%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sup{top:-.5em}sub{bottom:-.25em}dl,ol,ul{margin:0;padding:0;list-style:none;list-style-image:none}li{list-style:none}dd{margin:0}img{border:0;-ms-interpolation-mode:bicubic;vertical-align:middle;max-width:100%}svg:not(:root){overflow:hidden}figure,form{margin:0}label{cursor:pointer}button,input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}button,input{line-height:normal}button,input[type=button],input[type=reset],input[type=submit]{cursor:pointer;-webkit-appearance:button;*overflow:visible}button[disabled],input[disabled]{cursor:default}input[type=search]{-webkit-appearance:textfield;-moz-box-sizing:content-box;-webkit-box-sizing:content-box;box-sizing:content-box}textarea{resize:vertical}table{border-collapse:collapse;border-spacing:0}td{vertical-align:top}.chromeframe{margin:.2em 0;background:#ccc;color:#000;padding:.2em 0}.ir{display:block;border:0;text-indent:-999em;overflow:hidden;background-color:transparent;background-repeat:no-repeat;text-align:left;direction:ltr;*line-height:0}.ir br{display:none}.hidden{display:none!important;visibility:hidden}.visuallyhidden{border:0;clip:rect(0 0 0 0);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute;width:1px}.visuallyhidden.focusable:active,.visuallyhidden.focusable:focus{clip:auto;height:auto;margin:0;overflow:visible;position:static;width:auto}.invisible{visibility:hidden}.relative{position:relative}big,small{font-size:100%}@media print{body,html,section{background:none!important}*{box-shadow:none!important;text-shadow:none!important;filter:none!important;-ms-filter:none!important}a,a:visited{text-decoration:underline}.ir a:after,a[href^="#"]:after,a[href^="javascript:"]:after{content:""}blockquote,pre{page-break-inside:avoid}thead{display:table-header-group}img,tr{page-break-inside:avoid}img{max-width:100%!important}@page{margin:.5cm}.rst-content .toctree-wrapper>p.caption,h2,h3,p{orphans:3;widows:3}.rst-content .toctree-wrapper>p.caption,h2,h3{page-break-after:avoid}}.btn,.fa:before,.icon:before,.rst-content .admonition,.rst-content .admonition-title:before,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .code-block-caption .headerlink:before,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-alert,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a,.wy-menu-vertical li.current>a span.toctree-expand:before,.wy-menu-vertical li.on a,.wy-menu-vertical li.on a span.toctree-expand:before,.wy-menu-vertical li span.toctree-expand:before,.wy-nav-top a,.wy-side-nav-search .wy-dropdown>a,.wy-side-nav-search>a,input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week],select,textarea{-webkit-font-smoothing:antialiased}.clearfix{*zoom:1}.clearfix:after,.clearfix:before{display:table;content:""}.clearfix:after{clear:both}/*!
+ * Font Awesome 4.7.0 by @davegandy - http://fontawesome.io - @fontawesome
+ * License - http://fontawesome.io/license (Font: SIL OFL 1.1, CSS: MIT License)
+ */@font-face{font-family:FontAwesome;src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713);src:url(fonts/fontawesome-webfont.eot?674f50d287a8c48dc19ba404d20fe713?#iefix&v=4.7.0) format("embedded-opentype"),url(fonts/fontawesome-webfont.woff2?af7ae505a9eed503f8b8e6982036873e) format("woff2"),url(fonts/fontawesome-webfont.woff?fee66e712a8a08eef5805a46892932ad) format("woff"),url(fonts/fontawesome-webfont.ttf?b06871f281fee6b241d60582ae9369b9) format("truetype"),url(fonts/fontawesome-webfont.svg?912ec66d7572ff821749319396470bde#fontawesomeregular) format("svg");font-weight:400;font-style:normal}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-menu-vertical li.current>a span.toctree-expand,.wy-menu-vertical li.on a span.toctree-expand,.wy-menu-vertical li span.toctree-expand{display:inline-block;font:normal normal normal 14px/1 FontAwesome;font-size:inherit;text-rendering:auto;-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}.fa-lg{font-size:1.33333em;line-height:.75em;vertical-align:-15%}.fa-2x{font-size:2em}.fa-3x{font-size:3em}.fa-4x{font-size:4em}.fa-5x{font-size:5em}.fa-fw{width:1.28571em;text-align:center}.fa-ul{padding-left:0;margin-left:2.14286em;list-style-type:none}.fa-ul>li{position:relative}.fa-li{position:absolute;left:-2.14286em;width:2.14286em;top:.14286em;text-align:center}.fa-li.fa-lg{left:-1.85714em}.fa-border{padding:.2em .25em .15em;border:.08em solid #eee;border-radius:.1em}.fa-pull-left{float:left}.fa-pull-right{float:right}.fa-pull-left.icon,.fa.fa-pull-left,.rst-content .code-block-caption .fa-pull-left.headerlink,.rst-content .fa-pull-left.admonition-title,.rst-content code.download span.fa-pull-left:first-child,.rst-content dl dt .fa-pull-left.headerlink,.rst-content h1 .fa-pull-left.headerlink,.rst-content h2 .fa-pull-left.headerlink,.rst-content h3 .fa-pull-left.headerlink,.rst-content h4 .fa-pull-left.headerlink,.rst-content h5 .fa-pull-left.headerlink,.rst-content h6 .fa-pull-left.headerlink,.rst-content p.caption .fa-pull-left.headerlink,.rst-content table>caption .fa-pull-left.headerlink,.rst-content tt.download span.fa-pull-left:first-child,.wy-menu-vertical li.current>a span.fa-pull-left.toctree-expand,.wy-menu-vertical li.on a span.fa-pull-left.toctree-expand,.wy-menu-vertical li span.fa-pull-left.toctree-expand{margin-right:.3em}.fa-pull-right.icon,.fa.fa-pull-right,.rst-content .code-block-caption .fa-pull-right.headerlink,.rst-content .fa-pull-right.admonition-title,.rst-content code.download span.fa-pull-right:first-child,.rst-content dl dt .fa-pull-right.headerlink,.rst-content h1 .fa-pull-right.headerlink,.rst-content h2 .fa-pull-right.headerlink,.rst-content h3 .fa-pull-right.headerlink,.rst-content h4 .fa-pull-right.headerlink,.rst-content h5 .fa-pull-right.headerlink,.rst-content h6 .fa-pull-right.headerlink,.rst-content p.caption .fa-pull-right.headerlink,.rst-content table>caption .fa-pull-right.headerlink,.rst-content tt.download span.fa-pull-right:first-child,.wy-menu-vertical li.current>a span.fa-pull-right.toctree-expand,.wy-menu-vertical li.on a span.fa-pull-right.toctree-expand,.wy-menu-vertical li span.fa-pull-right.toctree-expand{margin-left:.3em}.pull-right{float:right}.pull-left{float:left}.fa.pull-left,.pull-left.icon,.rst-content .code-block-caption .pull-left.headerlink,.rst-content .pull-left.admonition-title,.rst-content code.download span.pull-left:first-child,.rst-content dl dt .pull-left.headerlink,.rst-content h1 .pull-left.headerlink,.rst-content h2 .pull-left.headerlink,.rst-content h3 .pull-left.headerlink,.rst-content h4 .pull-left.headerlink,.rst-content h5 .pull-left.headerlink,.rst-content h6 .pull-left.headerlink,.rst-content p.caption .pull-left.headerlink,.rst-content table>caption .pull-left.headerlink,.rst-content tt.download span.pull-left:first-child,.wy-menu-vertical li.current>a span.pull-left.toctree-expand,.wy-menu-vertical li.on a span.pull-left.toctree-expand,.wy-menu-vertical li span.pull-left.toctree-expand{margin-right:.3em}.fa.pull-right,.pull-right.icon,.rst-content .code-block-caption .pull-right.headerlink,.rst-content .pull-right.admonition-title,.rst-content code.download span.pull-right:first-child,.rst-content dl dt .pull-right.headerlink,.rst-content h1 .pull-right.headerlink,.rst-content h2 .pull-right.headerlink,.rst-content h3 .pull-right.headerlink,.rst-content h4 .pull-right.headerlink,.rst-content h5 .pull-right.headerlink,.rst-content h6 .pull-right.headerlink,.rst-content p.caption .pull-right.headerlink,.rst-content table>caption .pull-right.headerlink,.rst-content tt.download span.pull-right:first-child,.wy-menu-vertical li.current>a span.pull-right.toctree-expand,.wy-menu-vertical li.on a span.pull-right.toctree-expand,.wy-menu-vertical li span.pull-right.toctree-expand{margin-left:.3em}.fa-spin{-webkit-animation:fa-spin 2s linear infinite;animation:fa-spin 2s linear infinite}.fa-pulse{-webkit-animation:fa-spin 1s steps(8) infinite;animation:fa-spin 1s steps(8) infinite}@-webkit-keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}@keyframes fa-spin{0%{-webkit-transform:rotate(0deg);transform:rotate(0deg)}to{-webkit-transform:rotate(359deg);transform:rotate(359deg)}}.fa-rotate-90{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=1)";-webkit-transform:rotate(90deg);-ms-transform:rotate(90deg);transform:rotate(90deg)}.fa-rotate-180{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2)";-webkit-transform:rotate(180deg);-ms-transform:rotate(180deg);transform:rotate(180deg)}.fa-rotate-270{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=3)";-webkit-transform:rotate(270deg);-ms-transform:rotate(270deg);transform:rotate(270deg)}.fa-flip-horizontal{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=0, mirror=1)";-webkit-transform:scaleX(-1);-ms-transform:scaleX(-1);transform:scaleX(-1)}.fa-flip-vertical{-ms-filter:"progid:DXImageTransform.Microsoft.BasicImage(rotation=2, mirror=1)";-webkit-transform:scaleY(-1);-ms-transform:scaleY(-1);transform:scaleY(-1)}:root .fa-flip-horizontal,:root .fa-flip-vertical,:root .fa-rotate-90,:root .fa-rotate-180,:root .fa-rotate-270{filter:none}.fa-stack{position:relative;display:inline-block;width:2em;height:2em;line-height:2em;vertical-align:middle}.fa-stack-1x,.fa-stack-2x{position:absolute;left:0;width:100%;text-align:center}.fa-stack-1x{line-height:inherit}.fa-stack-2x{font-size:2em}.fa-inverse{color:#fff}.fa-glass:before{content:""}.fa-music:before{content:""}.fa-search:before,.icon-search:before{content:""}.fa-envelope-o:before{content:""}.fa-heart:before{content:""}.fa-star:before{content:""}.fa-star-o:before{content:""}.fa-user:before{content:""}.fa-film:before{content:""}.fa-th-large:before{content:""}.fa-th:before{content:""}.fa-th-list:before{content:""}.fa-check:before{content:""}.fa-close:before,.fa-remove:before,.fa-times:before{content:""}.fa-search-plus:before{content:""}.fa-search-minus:before{content:""}.fa-power-off:before{content:""}.fa-signal:before{content:""}.fa-cog:before,.fa-gear:before{content:""}.fa-trash-o:before{content:""}.fa-home:before,.icon-home:before{content:""}.fa-file-o:before{content:""}.fa-clock-o:before{content:""}.fa-road:before{content:""}.fa-download:before,.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{content:""}.fa-arrow-circle-o-down:before{content:""}.fa-arrow-circle-o-up:before{content:""}.fa-inbox:before{content:""}.fa-play-circle-o:before{content:""}.fa-repeat:before,.fa-rotate-right:before{content:""}.fa-refresh:before{content:""}.fa-list-alt:before{content:""}.fa-lock:before{content:""}.fa-flag:before{content:""}.fa-headphones:before{content:""}.fa-volume-off:before{content:""}.fa-volume-down:before{content:""}.fa-volume-up:before{content:""}.fa-qrcode:before{content:""}.fa-barcode:before{content:""}.fa-tag:before{content:""}.fa-tags:before{content:""}.fa-book:before,.icon-book:before{content:""}.fa-bookmark:before{content:""}.fa-print:before{content:""}.fa-camera:before{content:""}.fa-font:before{content:""}.fa-bold:before{content:""}.fa-italic:before{content:""}.fa-text-height:before{content:""}.fa-text-width:before{content:""}.fa-align-left:before{content:""}.fa-align-center:before{content:""}.fa-align-right:before{content:""}.fa-align-justify:before{content:""}.fa-list:before{content:""}.fa-dedent:before,.fa-outdent:before{content:""}.fa-indent:before{content:""}.fa-video-camera:before{content:""}.fa-image:before,.fa-photo:before,.fa-picture-o:before{content:""}.fa-pencil:before{content:""}.fa-map-marker:before{content:""}.fa-adjust:before{content:""}.fa-tint:before{content:""}.fa-edit:before,.fa-pencil-square-o:before{content:""}.fa-share-square-o:before{content:""}.fa-check-square-o:before{content:""}.fa-arrows:before{content:""}.fa-step-backward:before{content:""}.fa-fast-backward:before{content:""}.fa-backward:before{content:""}.fa-play:before{content:""}.fa-pause:before{content:""}.fa-stop:before{content:""}.fa-forward:before{content:""}.fa-fast-forward:before{content:""}.fa-step-forward:before{content:""}.fa-eject:before{content:""}.fa-chevron-left:before{content:""}.fa-chevron-right:before{content:""}.fa-plus-circle:before{content:""}.fa-minus-circle:before{content:""}.fa-times-circle:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before{content:""}.fa-check-circle:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before{content:""}.fa-question-circle:before{content:""}.fa-info-circle:before{content:""}.fa-crosshairs:before{content:""}.fa-times-circle-o:before{content:""}.fa-check-circle-o:before{content:""}.fa-ban:before{content:""}.fa-arrow-left:before{content:""}.fa-arrow-right:before{content:""}.fa-arrow-up:before{content:""}.fa-arrow-down:before{content:""}.fa-mail-forward:before,.fa-share:before{content:""}.fa-expand:before{content:""}.fa-compress:before{content:""}.fa-plus:before{content:""}.fa-minus:before{content:""}.fa-asterisk:before{content:""}.fa-exclamation-circle:before,.rst-content .admonition-title:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before{content:""}.fa-gift:before{content:""}.fa-leaf:before{content:""}.fa-fire:before,.icon-fire:before{content:""}.fa-eye:before{content:""}.fa-eye-slash:before{content:""}.fa-exclamation-triangle:before,.fa-warning:before{content:""}.fa-plane:before{content:""}.fa-calendar:before{content:""}.fa-random:before{content:""}.fa-comment:before{content:""}.fa-magnet:before{content:""}.fa-chevron-up:before{content:""}.fa-chevron-down:before{content:""}.fa-retweet:before{content:""}.fa-shopping-cart:before{content:""}.fa-folder:before{content:""}.fa-folder-open:before{content:""}.fa-arrows-v:before{content:""}.fa-arrows-h:before{content:""}.fa-bar-chart-o:before,.fa-bar-chart:before{content:""}.fa-twitter-square:before{content:""}.fa-facebook-square:before{content:""}.fa-camera-retro:before{content:""}.fa-key:before{content:""}.fa-cogs:before,.fa-gears:before{content:""}.fa-comments:before{content:""}.fa-thumbs-o-up:before{content:""}.fa-thumbs-o-down:before{content:""}.fa-star-half:before{content:""}.fa-heart-o:before{content:""}.fa-sign-out:before{content:""}.fa-linkedin-square:before{content:""}.fa-thumb-tack:before{content:""}.fa-external-link:before{content:""}.fa-sign-in:before{content:""}.fa-trophy:before{content:""}.fa-github-square:before{content:""}.fa-upload:before{content:""}.fa-lemon-o:before{content:""}.fa-phone:before{content:""}.fa-square-o:before{content:""}.fa-bookmark-o:before{content:""}.fa-phone-square:before{content:""}.fa-twitter:before{content:""}.fa-facebook-f:before,.fa-facebook:before{content:""}.fa-github:before,.icon-github:before{content:""}.fa-unlock:before{content:""}.fa-credit-card:before{content:""}.fa-feed:before,.fa-rss:before{content:""}.fa-hdd-o:before{content:""}.fa-bullhorn:before{content:""}.fa-bell:before{content:""}.fa-certificate:before{content:""}.fa-hand-o-right:before{content:""}.fa-hand-o-left:before{content:""}.fa-hand-o-up:before{content:""}.fa-hand-o-down:before{content:""}.fa-arrow-circle-left:before,.icon-circle-arrow-left:before{content:""}.fa-arrow-circle-right:before,.icon-circle-arrow-right:before{content:""}.fa-arrow-circle-up:before{content:""}.fa-arrow-circle-down:before{content:""}.fa-globe:before{content:""}.fa-wrench:before{content:""}.fa-tasks:before{content:""}.fa-filter:before{content:""}.fa-briefcase:before{content:""}.fa-arrows-alt:before{content:""}.fa-group:before,.fa-users:before{content:""}.fa-chain:before,.fa-link:before,.icon-link:before{content:""}.fa-cloud:before{content:""}.fa-flask:before{content:""}.fa-cut:before,.fa-scissors:before{content:""}.fa-copy:before,.fa-files-o:before{content:""}.fa-paperclip:before{content:""}.fa-floppy-o:before,.fa-save:before{content:""}.fa-square:before{content:""}.fa-bars:before,.fa-navicon:before,.fa-reorder:before{content:""}.fa-list-ul:before{content:""}.fa-list-ol:before{content:""}.fa-strikethrough:before{content:""}.fa-underline:before{content:""}.fa-table:before{content:""}.fa-magic:before{content:""}.fa-truck:before{content:""}.fa-pinterest:before{content:""}.fa-pinterest-square:before{content:""}.fa-google-plus-square:before{content:""}.fa-google-plus:before{content:""}.fa-money:before{content:""}.fa-caret-down:before,.icon-caret-down:before,.wy-dropdown .caret:before{content:""}.fa-caret-up:before{content:""}.fa-caret-left:before{content:""}.fa-caret-right:before{content:""}.fa-columns:before{content:""}.fa-sort:before,.fa-unsorted:before{content:""}.fa-sort-desc:before,.fa-sort-down:before{content:""}.fa-sort-asc:before,.fa-sort-up:before{content:""}.fa-envelope:before{content:""}.fa-linkedin:before{content:""}.fa-rotate-left:before,.fa-undo:before{content:""}.fa-gavel:before,.fa-legal:before{content:""}.fa-dashboard:before,.fa-tachometer:before{content:""}.fa-comment-o:before{content:""}.fa-comments-o:before{content:""}.fa-bolt:before,.fa-flash:before{content:""}.fa-sitemap:before{content:""}.fa-umbrella:before{content:""}.fa-clipboard:before,.fa-paste:before{content:""}.fa-lightbulb-o:before{content:""}.fa-exchange:before{content:""}.fa-cloud-download:before{content:""}.fa-cloud-upload:before{content:""}.fa-user-md:before{content:""}.fa-stethoscope:before{content:""}.fa-suitcase:before{content:""}.fa-bell-o:before{content:""}.fa-coffee:before{content:""}.fa-cutlery:before{content:""}.fa-file-text-o:before{content:""}.fa-building-o:before{content:""}.fa-hospital-o:before{content:""}.fa-ambulance:before{content:""}.fa-medkit:before{content:""}.fa-fighter-jet:before{content:""}.fa-beer:before{content:""}.fa-h-square:before{content:""}.fa-plus-square:before{content:""}.fa-angle-double-left:before{content:""}.fa-angle-double-right:before{content:""}.fa-angle-double-up:before{content:""}.fa-angle-double-down:before{content:""}.fa-angle-left:before{content:""}.fa-angle-right:before{content:""}.fa-angle-up:before{content:""}.fa-angle-down:before{content:""}.fa-desktop:before{content:""}.fa-laptop:before{content:""}.fa-tablet:before{content:""}.fa-mobile-phone:before,.fa-mobile:before{content:""}.fa-circle-o:before{content:""}.fa-quote-left:before{content:""}.fa-quote-right:before{content:""}.fa-spinner:before{content:""}.fa-circle:before{content:""}.fa-mail-reply:before,.fa-reply:before{content:""}.fa-github-alt:before{content:""}.fa-folder-o:before{content:""}.fa-folder-open-o:before{content:""}.fa-smile-o:before{content:""}.fa-frown-o:before{content:""}.fa-meh-o:before{content:""}.fa-gamepad:before{content:""}.fa-keyboard-o:before{content:""}.fa-flag-o:before{content:""}.fa-flag-checkered:before{content:""}.fa-terminal:before{content:""}.fa-code:before{content:""}.fa-mail-reply-all:before,.fa-reply-all:before{content:""}.fa-star-half-empty:before,.fa-star-half-full:before,.fa-star-half-o:before{content:""}.fa-location-arrow:before{content:""}.fa-crop:before{content:""}.fa-code-fork:before{content:""}.fa-chain-broken:before,.fa-unlink:before{content:""}.fa-question:before{content:""}.fa-info:before{content:""}.fa-exclamation:before{content:""}.fa-superscript:before{content:""}.fa-subscript:before{content:""}.fa-eraser:before{content:""}.fa-puzzle-piece:before{content:""}.fa-microphone:before{content:""}.fa-microphone-slash:before{content:""}.fa-shield:before{content:""}.fa-calendar-o:before{content:""}.fa-fire-extinguisher:before{content:""}.fa-rocket:before{content:""}.fa-maxcdn:before{content:""}.fa-chevron-circle-left:before{content:""}.fa-chevron-circle-right:before{content:""}.fa-chevron-circle-up:before{content:""}.fa-chevron-circle-down:before{content:""}.fa-html5:before{content:""}.fa-css3:before{content:""}.fa-anchor:before{content:""}.fa-unlock-alt:before{content:""}.fa-bullseye:before{content:""}.fa-ellipsis-h:before{content:""}.fa-ellipsis-v:before{content:""}.fa-rss-square:before{content:""}.fa-play-circle:before{content:""}.fa-ticket:before{content:""}.fa-minus-square:before{content:""}.fa-minus-square-o:before,.wy-menu-vertical li.current>a span.toctree-expand:before,.wy-menu-vertical li.on a span.toctree-expand:before{content:""}.fa-level-up:before{content:""}.fa-level-down:before{content:""}.fa-check-square:before{content:""}.fa-pencil-square:before{content:""}.fa-external-link-square:before{content:""}.fa-share-square:before{content:""}.fa-compass:before{content:""}.fa-caret-square-o-down:before,.fa-toggle-down:before{content:""}.fa-caret-square-o-up:before,.fa-toggle-up:before{content:""}.fa-caret-square-o-right:before,.fa-toggle-right:before{content:""}.fa-eur:before,.fa-euro:before{content:""}.fa-gbp:before{content:""}.fa-dollar:before,.fa-usd:before{content:""}.fa-inr:before,.fa-rupee:before{content:""}.fa-cny:before,.fa-jpy:before,.fa-rmb:before,.fa-yen:before{content:""}.fa-rouble:before,.fa-rub:before,.fa-ruble:before{content:""}.fa-krw:before,.fa-won:before{content:""}.fa-bitcoin:before,.fa-btc:before{content:""}.fa-file:before{content:""}.fa-file-text:before{content:""}.fa-sort-alpha-asc:before{content:""}.fa-sort-alpha-desc:before{content:""}.fa-sort-amount-asc:before{content:""}.fa-sort-amount-desc:before{content:""}.fa-sort-numeric-asc:before{content:""}.fa-sort-numeric-desc:before{content:""}.fa-thumbs-up:before{content:""}.fa-thumbs-down:before{content:""}.fa-youtube-square:before{content:""}.fa-youtube:before{content:""}.fa-xing:before{content:""}.fa-xing-square:before{content:""}.fa-youtube-play:before{content:""}.fa-dropbox:before{content:""}.fa-stack-overflow:before{content:""}.fa-instagram:before{content:""}.fa-flickr:before{content:""}.fa-adn:before{content:""}.fa-bitbucket:before,.icon-bitbucket:before{content:""}.fa-bitbucket-square:before{content:""}.fa-tumblr:before{content:""}.fa-tumblr-square:before{content:""}.fa-long-arrow-down:before{content:""}.fa-long-arrow-up:before{content:""}.fa-long-arrow-left:before{content:""}.fa-long-arrow-right:before{content:""}.fa-apple:before{content:""}.fa-windows:before{content:""}.fa-android:before{content:""}.fa-linux:before{content:""}.fa-dribbble:before{content:""}.fa-skype:before{content:""}.fa-foursquare:before{content:""}.fa-trello:before{content:""}.fa-female:before{content:""}.fa-male:before{content:""}.fa-gittip:before,.fa-gratipay:before{content:""}.fa-sun-o:before{content:""}.fa-moon-o:before{content:""}.fa-archive:before{content:""}.fa-bug:before{content:""}.fa-vk:before{content:""}.fa-weibo:before{content:""}.fa-renren:before{content:""}.fa-pagelines:before{content:""}.fa-stack-exchange:before{content:""}.fa-arrow-circle-o-right:before{content:""}.fa-arrow-circle-o-left:before{content:""}.fa-caret-square-o-left:before,.fa-toggle-left:before{content:""}.fa-dot-circle-o:before{content:""}.fa-wheelchair:before{content:""}.fa-vimeo-square:before{content:""}.fa-try:before,.fa-turkish-lira:before{content:""}.fa-plus-square-o:before,.wy-menu-vertical li span.toctree-expand:before{content:""}.fa-space-shuttle:before{content:""}.fa-slack:before{content:""}.fa-envelope-square:before{content:""}.fa-wordpress:before{content:""}.fa-openid:before{content:""}.fa-bank:before,.fa-institution:before,.fa-university:before{content:""}.fa-graduation-cap:before,.fa-mortar-board:before{content:""}.fa-yahoo:before{content:""}.fa-google:before{content:""}.fa-reddit:before{content:""}.fa-reddit-square:before{content:""}.fa-stumbleupon-circle:before{content:""}.fa-stumbleupon:before{content:""}.fa-delicious:before{content:""}.fa-digg:before{content:""}.fa-pied-piper-pp:before{content:""}.fa-pied-piper-alt:before{content:""}.fa-drupal:before{content:""}.fa-joomla:before{content:""}.fa-language:before{content:""}.fa-fax:before{content:""}.fa-building:before{content:""}.fa-child:before{content:""}.fa-paw:before{content:""}.fa-spoon:before{content:""}.fa-cube:before{content:""}.fa-cubes:before{content:""}.fa-behance:before{content:""}.fa-behance-square:before{content:""}.fa-steam:before{content:""}.fa-steam-square:before{content:""}.fa-recycle:before{content:""}.fa-automobile:before,.fa-car:before{content:""}.fa-cab:before,.fa-taxi:before{content:""}.fa-tree:before{content:""}.fa-spotify:before{content:""}.fa-deviantart:before{content:""}.fa-soundcloud:before{content:""}.fa-database:before{content:""}.fa-file-pdf-o:before{content:""}.fa-file-word-o:before{content:""}.fa-file-excel-o:before{content:""}.fa-file-powerpoint-o:before{content:""}.fa-file-image-o:before,.fa-file-photo-o:before,.fa-file-picture-o:before{content:""}.fa-file-archive-o:before,.fa-file-zip-o:before{content:""}.fa-file-audio-o:before,.fa-file-sound-o:before{content:""}.fa-file-movie-o:before,.fa-file-video-o:before{content:""}.fa-file-code-o:before{content:""}.fa-vine:before{content:""}.fa-codepen:before{content:""}.fa-jsfiddle:before{content:""}.fa-life-bouy:before,.fa-life-buoy:before,.fa-life-ring:before,.fa-life-saver:before,.fa-support:before{content:""}.fa-circle-o-notch:before{content:""}.fa-ra:before,.fa-rebel:before,.fa-resistance:before{content:""}.fa-empire:before,.fa-ge:before{content:""}.fa-git-square:before{content:""}.fa-git:before{content:""}.fa-hacker-news:before,.fa-y-combinator-square:before,.fa-yc-square:before{content:""}.fa-tencent-weibo:before{content:""}.fa-qq:before{content:""}.fa-wechat:before,.fa-weixin:before{content:""}.fa-paper-plane:before,.fa-send:before{content:""}.fa-paper-plane-o:before,.fa-send-o:before{content:""}.fa-history:before{content:""}.fa-circle-thin:before{content:""}.fa-header:before{content:""}.fa-paragraph:before{content:""}.fa-sliders:before{content:""}.fa-share-alt:before{content:""}.fa-share-alt-square:before{content:""}.fa-bomb:before{content:""}.fa-futbol-o:before,.fa-soccer-ball-o:before{content:""}.fa-tty:before{content:""}.fa-binoculars:before{content:""}.fa-plug:before{content:""}.fa-slideshare:before{content:""}.fa-twitch:before{content:""}.fa-yelp:before{content:""}.fa-newspaper-o:before{content:""}.fa-wifi:before{content:""}.fa-calculator:before{content:""}.fa-paypal:before{content:""}.fa-google-wallet:before{content:""}.fa-cc-visa:before{content:""}.fa-cc-mastercard:before{content:""}.fa-cc-discover:before{content:""}.fa-cc-amex:before{content:""}.fa-cc-paypal:before{content:""}.fa-cc-stripe:before{content:""}.fa-bell-slash:before{content:""}.fa-bell-slash-o:before{content:""}.fa-trash:before{content:""}.fa-copyright:before{content:""}.fa-at:before{content:""}.fa-eyedropper:before{content:""}.fa-paint-brush:before{content:""}.fa-birthday-cake:before{content:""}.fa-area-chart:before{content:""}.fa-pie-chart:before{content:""}.fa-line-chart:before{content:""}.fa-lastfm:before{content:""}.fa-lastfm-square:before{content:""}.fa-toggle-off:before{content:""}.fa-toggle-on:before{content:""}.fa-bicycle:before{content:""}.fa-bus:before{content:""}.fa-ioxhost:before{content:""}.fa-angellist:before{content:""}.fa-cc:before{content:""}.fa-ils:before,.fa-shekel:before,.fa-sheqel:before{content:""}.fa-meanpath:before{content:""}.fa-buysellads:before{content:""}.fa-connectdevelop:before{content:""}.fa-dashcube:before{content:""}.fa-forumbee:before{content:""}.fa-leanpub:before{content:""}.fa-sellsy:before{content:""}.fa-shirtsinbulk:before{content:""}.fa-simplybuilt:before{content:""}.fa-skyatlas:before{content:""}.fa-cart-plus:before{content:""}.fa-cart-arrow-down:before{content:""}.fa-diamond:before{content:""}.fa-ship:before{content:""}.fa-user-secret:before{content:""}.fa-motorcycle:before{content:""}.fa-street-view:before{content:""}.fa-heartbeat:before{content:""}.fa-venus:before{content:""}.fa-mars:before{content:""}.fa-mercury:before{content:""}.fa-intersex:before,.fa-transgender:before{content:""}.fa-transgender-alt:before{content:""}.fa-venus-double:before{content:""}.fa-mars-double:before{content:""}.fa-venus-mars:before{content:""}.fa-mars-stroke:before{content:""}.fa-mars-stroke-v:before{content:""}.fa-mars-stroke-h:before{content:""}.fa-neuter:before{content:""}.fa-genderless:before{content:""}.fa-facebook-official:before{content:""}.fa-pinterest-p:before{content:""}.fa-whatsapp:before{content:""}.fa-server:before{content:""}.fa-user-plus:before{content:""}.fa-user-times:before{content:""}.fa-bed:before,.fa-hotel:before{content:""}.fa-viacoin:before{content:""}.fa-train:before{content:""}.fa-subway:before{content:""}.fa-medium:before{content:""}.fa-y-combinator:before,.fa-yc:before{content:""}.fa-optin-monster:before{content:""}.fa-opencart:before{content:""}.fa-expeditedssl:before{content:""}.fa-battery-4:before,.fa-battery-full:before,.fa-battery:before{content:""}.fa-battery-3:before,.fa-battery-three-quarters:before{content:""}.fa-battery-2:before,.fa-battery-half:before{content:""}.fa-battery-1:before,.fa-battery-quarter:before{content:""}.fa-battery-0:before,.fa-battery-empty:before{content:""}.fa-mouse-pointer:before{content:""}.fa-i-cursor:before{content:""}.fa-object-group:before{content:""}.fa-object-ungroup:before{content:""}.fa-sticky-note:before{content:""}.fa-sticky-note-o:before{content:""}.fa-cc-jcb:before{content:""}.fa-cc-diners-club:before{content:""}.fa-clone:before{content:""}.fa-balance-scale:before{content:""}.fa-hourglass-o:before{content:""}.fa-hourglass-1:before,.fa-hourglass-start:before{content:""}.fa-hourglass-2:before,.fa-hourglass-half:before{content:""}.fa-hourglass-3:before,.fa-hourglass-end:before{content:""}.fa-hourglass:before{content:""}.fa-hand-grab-o:before,.fa-hand-rock-o:before{content:""}.fa-hand-paper-o:before,.fa-hand-stop-o:before{content:""}.fa-hand-scissors-o:before{content:""}.fa-hand-lizard-o:before{content:""}.fa-hand-spock-o:before{content:""}.fa-hand-pointer-o:before{content:""}.fa-hand-peace-o:before{content:""}.fa-trademark:before{content:""}.fa-registered:before{content:""}.fa-creative-commons:before{content:""}.fa-gg:before{content:""}.fa-gg-circle:before{content:""}.fa-tripadvisor:before{content:""}.fa-odnoklassniki:before{content:""}.fa-odnoklassniki-square:before{content:""}.fa-get-pocket:before{content:""}.fa-wikipedia-w:before{content:""}.fa-safari:before{content:""}.fa-chrome:before{content:""}.fa-firefox:before{content:""}.fa-opera:before{content:""}.fa-internet-explorer:before{content:""}.fa-television:before,.fa-tv:before{content:""}.fa-contao:before{content:""}.fa-500px:before{content:""}.fa-amazon:before{content:""}.fa-calendar-plus-o:before{content:""}.fa-calendar-minus-o:before{content:""}.fa-calendar-times-o:before{content:""}.fa-calendar-check-o:before{content:""}.fa-industry:before{content:""}.fa-map-pin:before{content:""}.fa-map-signs:before{content:""}.fa-map-o:before{content:""}.fa-map:before{content:""}.fa-commenting:before{content:""}.fa-commenting-o:before{content:""}.fa-houzz:before{content:""}.fa-vimeo:before{content:""}.fa-black-tie:before{content:""}.fa-fonticons:before{content:""}.fa-reddit-alien:before{content:""}.fa-edge:before{content:""}.fa-credit-card-alt:before{content:""}.fa-codiepie:before{content:""}.fa-modx:before{content:""}.fa-fort-awesome:before{content:""}.fa-usb:before{content:""}.fa-product-hunt:before{content:""}.fa-mixcloud:before{content:""}.fa-scribd:before{content:""}.fa-pause-circle:before{content:""}.fa-pause-circle-o:before{content:""}.fa-stop-circle:before{content:""}.fa-stop-circle-o:before{content:""}.fa-shopping-bag:before{content:""}.fa-shopping-basket:before{content:""}.fa-hashtag:before{content:""}.fa-bluetooth:before{content:""}.fa-bluetooth-b:before{content:""}.fa-percent:before{content:""}.fa-gitlab:before,.icon-gitlab:before{content:""}.fa-wpbeginner:before{content:""}.fa-wpforms:before{content:""}.fa-envira:before{content:""}.fa-universal-access:before{content:""}.fa-wheelchair-alt:before{content:""}.fa-question-circle-o:before{content:""}.fa-blind:before{content:""}.fa-audio-description:before{content:""}.fa-volume-control-phone:before{content:""}.fa-braille:before{content:""}.fa-assistive-listening-systems:before{content:""}.fa-american-sign-language-interpreting:before,.fa-asl-interpreting:before{content:""}.fa-deaf:before,.fa-deafness:before,.fa-hard-of-hearing:before{content:""}.fa-glide:before{content:""}.fa-glide-g:before{content:""}.fa-sign-language:before,.fa-signing:before{content:""}.fa-low-vision:before{content:""}.fa-viadeo:before{content:""}.fa-viadeo-square:before{content:""}.fa-snapchat:before{content:""}.fa-snapchat-ghost:before{content:""}.fa-snapchat-square:before{content:""}.fa-pied-piper:before{content:""}.fa-first-order:before{content:""}.fa-yoast:before{content:""}.fa-themeisle:before{content:""}.fa-google-plus-circle:before,.fa-google-plus-official:before{content:""}.fa-fa:before,.fa-font-awesome:before{content:""}.fa-handshake-o:before{content:""}.fa-envelope-open:before{content:""}.fa-envelope-open-o:before{content:""}.fa-linode:before{content:""}.fa-address-book:before{content:""}.fa-address-book-o:before{content:""}.fa-address-card:before,.fa-vcard:before{content:""}.fa-address-card-o:before,.fa-vcard-o:before{content:""}.fa-user-circle:before{content:""}.fa-user-circle-o:before{content:""}.fa-user-o:before{content:""}.fa-id-badge:before{content:""}.fa-drivers-license:before,.fa-id-card:before{content:""}.fa-drivers-license-o:before,.fa-id-card-o:before{content:""}.fa-quora:before{content:""}.fa-free-code-camp:before{content:""}.fa-telegram:before{content:""}.fa-thermometer-4:before,.fa-thermometer-full:before,.fa-thermometer:before{content:""}.fa-thermometer-3:before,.fa-thermometer-three-quarters:before{content:""}.fa-thermometer-2:before,.fa-thermometer-half:before{content:""}.fa-thermometer-1:before,.fa-thermometer-quarter:before{content:""}.fa-thermometer-0:before,.fa-thermometer-empty:before{content:""}.fa-shower:before{content:""}.fa-bath:before,.fa-bathtub:before,.fa-s15:before{content:""}.fa-podcast:before{content:""}.fa-window-maximize:before{content:""}.fa-window-minimize:before{content:""}.fa-window-restore:before{content:""}.fa-times-rectangle:before,.fa-window-close:before{content:""}.fa-times-rectangle-o:before,.fa-window-close-o:before{content:""}.fa-bandcamp:before{content:""}.fa-grav:before{content:""}.fa-etsy:before{content:""}.fa-imdb:before{content:""}.fa-ravelry:before{content:""}.fa-eercast:before{content:""}.fa-microchip:before{content:""}.fa-snowflake-o:before{content:""}.fa-superpowers:before{content:""}.fa-wpexplorer:before{content:""}.fa-meetup:before{content:""}.sr-only{position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);border:0}.sr-only-focusable:active,.sr-only-focusable:focus{position:static;width:auto;height:auto;margin:0;overflow:visible;clip:auto}.fa,.icon,.rst-content .admonition-title,.rst-content .code-block-caption .headerlink,.rst-content code.download span:first-child,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content table>caption .headerlink,.rst-content tt.download span:first-child,.wy-dropdown .caret,.wy-inline-validate.wy-inline-validate-danger .wy-input-context,.wy-inline-validate.wy-inline-validate-info .wy-input-context,.wy-inline-validate.wy-inline-validate-success .wy-input-context,.wy-inline-validate.wy-inline-validate-warning .wy-input-context,.wy-menu-vertical li.current>a span.toctree-expand,.wy-menu-vertical li.on a span.toctree-expand,.wy-menu-vertical li span.toctree-expand{font-family:inherit}.fa:before,.icon:before,.rst-content .admonition-title:before,.rst-content .code-block-caption .headerlink:before,.rst-content code.download span:first-child:before,.rst-content dl dt .headerlink:before,.rst-content h1 .headerlink:before,.rst-content h2 .headerlink:before,.rst-content h3 .headerlink:before,.rst-content h4 .headerlink:before,.rst-content h5 .headerlink:before,.rst-content h6 .headerlink:before,.rst-content p.caption .headerlink:before,.rst-content table>caption .headerlink:before,.rst-content tt.download span:first-child:before,.wy-dropdown .caret:before,.wy-inline-validate.wy-inline-validate-danger .wy-input-context:before,.wy-inline-validate.wy-inline-validate-info .wy-input-context:before,.wy-inline-validate.wy-inline-validate-success .wy-input-context:before,.wy-inline-validate.wy-inline-validate-warning .wy-input-context:before,.wy-menu-vertical li.current>a span.toctree-expand:before,.wy-menu-vertical li.on a span.toctree-expand:before,.wy-menu-vertical li span.toctree-expand:before{font-family:FontAwesome;display:inline-block;font-style:normal;font-weight:400;line-height:1;text-decoration:inherit}.rst-content .code-block-caption a .headerlink,.rst-content a .admonition-title,.rst-content code.download a span:first-child,.rst-content dl dt a .headerlink,.rst-content h1 a .headerlink,.rst-content h2 a .headerlink,.rst-content h3 a .headerlink,.rst-content h4 a .headerlink,.rst-content h5 a .headerlink,.rst-content h6 a .headerlink,.rst-content p.caption a .headerlink,.rst-content table>caption a .headerlink,.rst-content tt.download a span:first-child,.wy-menu-vertical li.current>a span.toctree-expand,.wy-menu-vertical li.on a span.toctree-expand,.wy-menu-vertical li a span.toctree-expand,a .fa,a .icon,a .rst-content .admonition-title,a .rst-content .code-block-caption .headerlink,a .rst-content code.download span:first-child,a .rst-content dl dt .headerlink,a .rst-content h1 .headerlink,a .rst-content h2 .headerlink,a .rst-content h3 .headerlink,a .rst-content h4 .headerlink,a .rst-content h5 .headerlink,a .rst-content h6 .headerlink,a .rst-content p.caption .headerlink,a .rst-content table>caption .headerlink,a .rst-content tt.download span:first-child,a .wy-menu-vertical li span.toctree-expand{display:inline-block;text-decoration:inherit}.btn .fa,.btn .icon,.btn .rst-content .admonition-title,.btn .rst-content .code-block-caption .headerlink,.btn .rst-content code.download span:first-child,.btn .rst-content dl dt .headerlink,.btn .rst-content h1 .headerlink,.btn .rst-content h2 .headerlink,.btn .rst-content h3 .headerlink,.btn .rst-content h4 .headerlink,.btn .rst-content h5 .headerlink,.btn .rst-content h6 .headerlink,.btn .rst-content p.caption .headerlink,.btn .rst-content table>caption .headerlink,.btn .rst-content tt.download span:first-child,.btn .wy-menu-vertical li.current>a span.toctree-expand,.btn .wy-menu-vertical li.on a span.toctree-expand,.btn .wy-menu-vertical li span.toctree-expand,.nav .fa,.nav .icon,.nav .rst-content .admonition-title,.nav .rst-content .code-block-caption .headerlink,.nav .rst-content code.download span:first-child,.nav .rst-content dl dt .headerlink,.nav .rst-content h1 .headerlink,.nav .rst-content h2 .headerlink,.nav .rst-content h3 .headerlink,.nav .rst-content h4 .headerlink,.nav .rst-content h5 .headerlink,.nav .rst-content h6 .headerlink,.nav .rst-content p.caption .headerlink,.nav .rst-content table>caption .headerlink,.nav .rst-content tt.download span:first-child,.nav .wy-menu-vertical li.current>a span.toctree-expand,.nav .wy-menu-vertical li.on a span.toctree-expand,.nav .wy-menu-vertical li span.toctree-expand,.rst-content .btn .admonition-title,.rst-content .code-block-caption .btn .headerlink,.rst-content .code-block-caption .nav .headerlink,.rst-content .nav .admonition-title,.rst-content code.download .btn span:first-child,.rst-content code.download .nav span:first-child,.rst-content dl dt .btn .headerlink,.rst-content dl dt .nav .headerlink,.rst-content h1 .btn .headerlink,.rst-content h1 .nav .headerlink,.rst-content h2 .btn .headerlink,.rst-content h2 .nav .headerlink,.rst-content h3 .btn .headerlink,.rst-content h3 .nav .headerlink,.rst-content h4 .btn .headerlink,.rst-content h4 .nav .headerlink,.rst-content h5 .btn .headerlink,.rst-content h5 .nav .headerlink,.rst-content h6 .btn .headerlink,.rst-content h6 .nav .headerlink,.rst-content p.caption .btn .headerlink,.rst-content p.caption .nav .headerlink,.rst-content table>caption .btn .headerlink,.rst-content table>caption .nav .headerlink,.rst-content tt.download .btn span:first-child,.rst-content tt.download .nav span:first-child,.wy-menu-vertical li .btn span.toctree-expand,.wy-menu-vertical li.current>a .btn span.toctree-expand,.wy-menu-vertical li.current>a .nav span.toctree-expand,.wy-menu-vertical li .nav span.toctree-expand,.wy-menu-vertical li.on a .btn span.toctree-expand,.wy-menu-vertical li.on a .nav span.toctree-expand{display:inline}.btn .fa-large.icon,.btn .fa.fa-large,.btn .rst-content .code-block-caption .fa-large.headerlink,.btn .rst-content .fa-large.admonition-title,.btn .rst-content code.download span.fa-large:first-child,.btn .rst-content dl dt .fa-large.headerlink,.btn .rst-content h1 .fa-large.headerlink,.btn .rst-content h2 .fa-large.headerlink,.btn .rst-content h3 .fa-large.headerlink,.btn .rst-content h4 .fa-large.headerlink,.btn .rst-content h5 .fa-large.headerlink,.btn .rst-content h6 .fa-large.headerlink,.btn .rst-content p.caption .fa-large.headerlink,.btn .rst-content table>caption .fa-large.headerlink,.btn .rst-content tt.download span.fa-large:first-child,.btn .wy-menu-vertical li span.fa-large.toctree-expand,.nav .fa-large.icon,.nav .fa.fa-large,.nav .rst-content .code-block-caption .fa-large.headerlink,.nav .rst-content .fa-large.admonition-title,.nav .rst-content code.download span.fa-large:first-child,.nav .rst-content dl dt .fa-large.headerlink,.nav .rst-content h1 .fa-large.headerlink,.nav .rst-content h2 .fa-large.headerlink,.nav .rst-content h3 .fa-large.headerlink,.nav .rst-content h4 .fa-large.headerlink,.nav .rst-content h5 .fa-large.headerlink,.nav .rst-content h6 .fa-large.headerlink,.nav .rst-content p.caption .fa-large.headerlink,.nav .rst-content table>caption .fa-large.headerlink,.nav .rst-content tt.download span.fa-large:first-child,.nav .wy-menu-vertical li span.fa-large.toctree-expand,.rst-content .btn .fa-large.admonition-title,.rst-content .code-block-caption .btn .fa-large.headerlink,.rst-content .code-block-caption .nav .fa-large.headerlink,.rst-content .nav .fa-large.admonition-title,.rst-content code.download .btn span.fa-large:first-child,.rst-content code.download .nav span.fa-large:first-child,.rst-content dl dt .btn .fa-large.headerlink,.rst-content dl dt .nav .fa-large.headerlink,.rst-content h1 .btn .fa-large.headerlink,.rst-content h1 .nav .fa-large.headerlink,.rst-content h2 .btn .fa-large.headerlink,.rst-content h2 .nav .fa-large.headerlink,.rst-content h3 .btn .fa-large.headerlink,.rst-content h3 .nav .fa-large.headerlink,.rst-content h4 .btn .fa-large.headerlink,.rst-content h4 .nav .fa-large.headerlink,.rst-content h5 .btn .fa-large.headerlink,.rst-content h5 .nav .fa-large.headerlink,.rst-content h6 .btn .fa-large.headerlink,.rst-content h6 .nav .fa-large.headerlink,.rst-content p.caption .btn .fa-large.headerlink,.rst-content p.caption .nav .fa-large.headerlink,.rst-content table>caption .btn .fa-large.headerlink,.rst-content table>caption .nav .fa-large.headerlink,.rst-content tt.download .btn span.fa-large:first-child,.rst-content tt.download .nav span.fa-large:first-child,.wy-menu-vertical li .btn span.fa-large.toctree-expand,.wy-menu-vertical li .nav span.fa-large.toctree-expand{line-height:.9em}.btn .fa-spin.icon,.btn .fa.fa-spin,.btn .rst-content .code-block-caption .fa-spin.headerlink,.btn .rst-content .fa-spin.admonition-title,.btn .rst-content code.download span.fa-spin:first-child,.btn .rst-content dl dt .fa-spin.headerlink,.btn .rst-content h1 .fa-spin.headerlink,.btn .rst-content h2 .fa-spin.headerlink,.btn .rst-content h3 .fa-spin.headerlink,.btn .rst-content h4 .fa-spin.headerlink,.btn .rst-content h5 .fa-spin.headerlink,.btn .rst-content h6 .fa-spin.headerlink,.btn .rst-content p.caption .fa-spin.headerlink,.btn .rst-content table>caption .fa-spin.headerlink,.btn .rst-content tt.download span.fa-spin:first-child,.btn .wy-menu-vertical li span.fa-spin.toctree-expand,.nav .fa-spin.icon,.nav .fa.fa-spin,.nav .rst-content .code-block-caption .fa-spin.headerlink,.nav .rst-content .fa-spin.admonition-title,.nav .rst-content code.download span.fa-spin:first-child,.nav .rst-content dl dt .fa-spin.headerlink,.nav .rst-content h1 .fa-spin.headerlink,.nav .rst-content h2 .fa-spin.headerlink,.nav .rst-content h3 .fa-spin.headerlink,.nav .rst-content h4 .fa-spin.headerlink,.nav .rst-content h5 .fa-spin.headerlink,.nav .rst-content h6 .fa-spin.headerlink,.nav .rst-content p.caption .fa-spin.headerlink,.nav .rst-content table>caption .fa-spin.headerlink,.nav .rst-content tt.download span.fa-spin:first-child,.nav .wy-menu-vertical li span.fa-spin.toctree-expand,.rst-content .btn .fa-spin.admonition-title,.rst-content .code-block-caption .btn .fa-spin.headerlink,.rst-content .code-block-caption .nav .fa-spin.headerlink,.rst-content .nav .fa-spin.admonition-title,.rst-content code.download .btn span.fa-spin:first-child,.rst-content code.download .nav span.fa-spin:first-child,.rst-content dl dt .btn .fa-spin.headerlink,.rst-content dl dt .nav .fa-spin.headerlink,.rst-content h1 .btn .fa-spin.headerlink,.rst-content h1 .nav .fa-spin.headerlink,.rst-content h2 .btn .fa-spin.headerlink,.rst-content h2 .nav .fa-spin.headerlink,.rst-content h3 .btn .fa-spin.headerlink,.rst-content h3 .nav .fa-spin.headerlink,.rst-content h4 .btn .fa-spin.headerlink,.rst-content h4 .nav .fa-spin.headerlink,.rst-content h5 .btn .fa-spin.headerlink,.rst-content h5 .nav .fa-spin.headerlink,.rst-content h6 .btn .fa-spin.headerlink,.rst-content h6 .nav .fa-spin.headerlink,.rst-content p.caption .btn .fa-spin.headerlink,.rst-content p.caption .nav .fa-spin.headerlink,.rst-content table>caption .btn .fa-spin.headerlink,.rst-content table>caption .nav .fa-spin.headerlink,.rst-content tt.download .btn span.fa-spin:first-child,.rst-content tt.download .nav span.fa-spin:first-child,.wy-menu-vertical li .btn span.fa-spin.toctree-expand,.wy-menu-vertical li .nav span.fa-spin.toctree-expand{display:inline-block}.btn.fa:before,.btn.icon:before,.rst-content .btn.admonition-title:before,.rst-content .code-block-caption .btn.headerlink:before,.rst-content code.download span.btn:first-child:before,.rst-content dl dt .btn.headerlink:before,.rst-content h1 .btn.headerlink:before,.rst-content h2 .btn.headerlink:before,.rst-content h3 .btn.headerlink:before,.rst-content h4 .btn.headerlink:before,.rst-content h5 .btn.headerlink:before,.rst-content h6 .btn.headerlink:before,.rst-content p.caption .btn.headerlink:before,.rst-content table>caption .btn.headerlink:before,.rst-content tt.download span.btn:first-child:before,.wy-menu-vertical li span.btn.toctree-expand:before{opacity:.5;-webkit-transition:opacity .05s ease-in;-moz-transition:opacity .05s ease-in;transition:opacity .05s ease-in}.btn.fa:hover:before,.btn.icon:hover:before,.rst-content .btn.admonition-title:hover:before,.rst-content .code-block-caption .btn.headerlink:hover:before,.rst-content code.download span.btn:first-child:hover:before,.rst-content dl dt .btn.headerlink:hover:before,.rst-content h1 .btn.headerlink:hover:before,.rst-content h2 .btn.headerlink:hover:before,.rst-content h3 .btn.headerlink:hover:before,.rst-content h4 .btn.headerlink:hover:before,.rst-content h5 .btn.headerlink:hover:before,.rst-content h6 .btn.headerlink:hover:before,.rst-content p.caption .btn.headerlink:hover:before,.rst-content table>caption .btn.headerlink:hover:before,.rst-content tt.download span.btn:first-child:hover:before,.wy-menu-vertical li span.btn.toctree-expand:hover:before{opacity:1}.btn-mini .fa:before,.btn-mini .icon:before,.btn-mini .rst-content .admonition-title:before,.btn-mini .rst-content .code-block-caption .headerlink:before,.btn-mini .rst-content code.download span:first-child:before,.btn-mini .rst-content dl dt .headerlink:before,.btn-mini .rst-content h1 .headerlink:before,.btn-mini .rst-content h2 .headerlink:before,.btn-mini .rst-content h3 .headerlink:before,.btn-mini .rst-content h4 .headerlink:before,.btn-mini .rst-content h5 .headerlink:before,.btn-mini .rst-content h6 .headerlink:before,.btn-mini .rst-content p.caption .headerlink:before,.btn-mini .rst-content table>caption .headerlink:before,.btn-mini .rst-content tt.download span:first-child:before,.btn-mini .wy-menu-vertical li span.toctree-expand:before,.rst-content .btn-mini .admonition-title:before,.rst-content .code-block-caption .btn-mini .headerlink:before,.rst-content code.download .btn-mini span:first-child:before,.rst-content dl dt .btn-mini .headerlink:before,.rst-content h1 .btn-mini .headerlink:before,.rst-content h2 .btn-mini .headerlink:before,.rst-content h3 .btn-mini .headerlink:before,.rst-content h4 .btn-mini .headerlink:before,.rst-content h5 .btn-mini .headerlink:before,.rst-content h6 .btn-mini .headerlink:before,.rst-content p.caption .btn-mini .headerlink:before,.rst-content table>caption .btn-mini .headerlink:before,.rst-content tt.download .btn-mini span:first-child:before,.wy-menu-vertical li .btn-mini span.toctree-expand:before{font-size:14px;vertical-align:-15%}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning,.wy-alert{padding:12px;line-height:24px;margin-bottom:24px;background:#e7f2fa}.rst-content .admonition-title,.wy-alert-title{font-weight:700;display:block;color:#fff;background:#6ab0de;padding:6px 12px;margin:-12px -12px 12px}.rst-content .danger,.rst-content .error,.rst-content .wy-alert-danger.admonition,.rst-content .wy-alert-danger.admonition-todo,.rst-content .wy-alert-danger.attention,.rst-content .wy-alert-danger.caution,.rst-content .wy-alert-danger.hint,.rst-content .wy-alert-danger.important,.rst-content .wy-alert-danger.note,.rst-content .wy-alert-danger.seealso,.rst-content .wy-alert-danger.tip,.rst-content .wy-alert-danger.warning,.wy-alert.wy-alert-danger{background:#fdf3f2}.rst-content .danger .admonition-title,.rst-content .danger .wy-alert-title,.rst-content .error .admonition-title,.rst-content .error .wy-alert-title,.rst-content .wy-alert-danger.admonition-todo .admonition-title,.rst-content .wy-alert-danger.admonition-todo .wy-alert-title,.rst-content .wy-alert-danger.admonition .admonition-title,.rst-content .wy-alert-danger.admonition .wy-alert-title,.rst-content .wy-alert-danger.attention .admonition-title,.rst-content .wy-alert-danger.attention .wy-alert-title,.rst-content .wy-alert-danger.caution .admonition-title,.rst-content .wy-alert-danger.caution .wy-alert-title,.rst-content .wy-alert-danger.hint .admonition-title,.rst-content .wy-alert-danger.hint .wy-alert-title,.rst-content .wy-alert-danger.important .admonition-title,.rst-content .wy-alert-danger.important .wy-alert-title,.rst-content .wy-alert-danger.note .admonition-title,.rst-content .wy-alert-danger.note .wy-alert-title,.rst-content .wy-alert-danger.seealso .admonition-title,.rst-content .wy-alert-danger.seealso .wy-alert-title,.rst-content .wy-alert-danger.tip .admonition-title,.rst-content .wy-alert-danger.tip .wy-alert-title,.rst-content .wy-alert-danger.warning .admonition-title,.rst-content .wy-alert-danger.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-danger .admonition-title,.wy-alert.wy-alert-danger .rst-content .admonition-title,.wy-alert.wy-alert-danger .wy-alert-title{background:#f29f97}.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .warning,.rst-content .wy-alert-warning.admonition,.rst-content .wy-alert-warning.danger,.rst-content .wy-alert-warning.error,.rst-content .wy-alert-warning.hint,.rst-content .wy-alert-warning.important,.rst-content .wy-alert-warning.note,.rst-content .wy-alert-warning.seealso,.rst-content .wy-alert-warning.tip,.wy-alert.wy-alert-warning{background:#ffedcc}.rst-content .admonition-todo .admonition-title,.rst-content .admonition-todo .wy-alert-title,.rst-content .attention .admonition-title,.rst-content .attention .wy-alert-title,.rst-content .caution .admonition-title,.rst-content .caution .wy-alert-title,.rst-content .warning .admonition-title,.rst-content .warning .wy-alert-title,.rst-content .wy-alert-warning.admonition .admonition-title,.rst-content .wy-alert-warning.admonition .wy-alert-title,.rst-content .wy-alert-warning.danger .admonition-title,.rst-content .wy-alert-warning.danger .wy-alert-title,.rst-content .wy-alert-warning.error .admonition-title,.rst-content .wy-alert-warning.error .wy-alert-title,.rst-content .wy-alert-warning.hint .admonition-title,.rst-content .wy-alert-warning.hint .wy-alert-title,.rst-content .wy-alert-warning.important .admonition-title,.rst-content .wy-alert-warning.important .wy-alert-title,.rst-content .wy-alert-warning.note .admonition-title,.rst-content .wy-alert-warning.note .wy-alert-title,.rst-content .wy-alert-warning.seealso .admonition-title,.rst-content .wy-alert-warning.seealso .wy-alert-title,.rst-content .wy-alert-warning.tip .admonition-title,.rst-content .wy-alert-warning.tip .wy-alert-title,.rst-content .wy-alert.wy-alert-warning .admonition-title,.wy-alert.wy-alert-warning .rst-content .admonition-title,.wy-alert.wy-alert-warning .wy-alert-title{background:#f0b37e}.rst-content .note,.rst-content .seealso,.rst-content .wy-alert-info.admonition,.rst-content .wy-alert-info.admonition-todo,.rst-content .wy-alert-info.attention,.rst-content .wy-alert-info.caution,.rst-content .wy-alert-info.danger,.rst-content .wy-alert-info.error,.rst-content .wy-alert-info.hint,.rst-content .wy-alert-info.important,.rst-content .wy-alert-info.tip,.rst-content .wy-alert-info.warning,.wy-alert.wy-alert-info{background:#e7f2fa}.rst-content .note .admonition-title,.rst-content .note .wy-alert-title,.rst-content .seealso .admonition-title,.rst-content .seealso .wy-alert-title,.rst-content .wy-alert-info.admonition-todo .admonition-title,.rst-content .wy-alert-info.admonition-todo .wy-alert-title,.rst-content .wy-alert-info.admonition .admonition-title,.rst-content .wy-alert-info.admonition .wy-alert-title,.rst-content .wy-alert-info.attention .admonition-title,.rst-content .wy-alert-info.attention .wy-alert-title,.rst-content .wy-alert-info.caution .admonition-title,.rst-content .wy-alert-info.caution .wy-alert-title,.rst-content .wy-alert-info.danger .admonition-title,.rst-content .wy-alert-info.danger .wy-alert-title,.rst-content .wy-alert-info.error .admonition-title,.rst-content .wy-alert-info.error .wy-alert-title,.rst-content .wy-alert-info.hint .admonition-title,.rst-content .wy-alert-info.hint .wy-alert-title,.rst-content .wy-alert-info.important .admonition-title,.rst-content .wy-alert-info.important .wy-alert-title,.rst-content .wy-alert-info.tip .admonition-title,.rst-content .wy-alert-info.tip .wy-alert-title,.rst-content .wy-alert-info.warning .admonition-title,.rst-content .wy-alert-info.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-info .admonition-title,.wy-alert.wy-alert-info .rst-content .admonition-title,.wy-alert.wy-alert-info .wy-alert-title{background:#6ab0de}.rst-content .hint,.rst-content .important,.rst-content .tip,.rst-content .wy-alert-success.admonition,.rst-content .wy-alert-success.admonition-todo,.rst-content .wy-alert-success.attention,.rst-content .wy-alert-success.caution,.rst-content .wy-alert-success.danger,.rst-content .wy-alert-success.error,.rst-content .wy-alert-success.note,.rst-content .wy-alert-success.seealso,.rst-content .wy-alert-success.warning,.wy-alert.wy-alert-success{background:#dbfaf4}.rst-content .hint .admonition-title,.rst-content .hint .wy-alert-title,.rst-content .important .admonition-title,.rst-content .important .wy-alert-title,.rst-content .tip .admonition-title,.rst-content .tip .wy-alert-title,.rst-content .wy-alert-success.admonition-todo .admonition-title,.rst-content .wy-alert-success.admonition-todo .wy-alert-title,.rst-content .wy-alert-success.admonition .admonition-title,.rst-content .wy-alert-success.admonition .wy-alert-title,.rst-content .wy-alert-success.attention .admonition-title,.rst-content .wy-alert-success.attention .wy-alert-title,.rst-content .wy-alert-success.caution .admonition-title,.rst-content .wy-alert-success.caution .wy-alert-title,.rst-content .wy-alert-success.danger .admonition-title,.rst-content .wy-alert-success.danger .wy-alert-title,.rst-content .wy-alert-success.error .admonition-title,.rst-content .wy-alert-success.error .wy-alert-title,.rst-content .wy-alert-success.note .admonition-title,.rst-content .wy-alert-success.note .wy-alert-title,.rst-content .wy-alert-success.seealso .admonition-title,.rst-content .wy-alert-success.seealso .wy-alert-title,.rst-content .wy-alert-success.warning .admonition-title,.rst-content .wy-alert-success.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-success .admonition-title,.wy-alert.wy-alert-success .rst-content .admonition-title,.wy-alert.wy-alert-success .wy-alert-title{background:#1abc9c}.rst-content .wy-alert-neutral.admonition,.rst-content .wy-alert-neutral.admonition-todo,.rst-content .wy-alert-neutral.attention,.rst-content .wy-alert-neutral.caution,.rst-content .wy-alert-neutral.danger,.rst-content .wy-alert-neutral.error,.rst-content .wy-alert-neutral.hint,.rst-content .wy-alert-neutral.important,.rst-content .wy-alert-neutral.note,.rst-content .wy-alert-neutral.seealso,.rst-content .wy-alert-neutral.tip,.rst-content .wy-alert-neutral.warning,.wy-alert.wy-alert-neutral{background:#f3f6f6}.rst-content .wy-alert-neutral.admonition-todo .admonition-title,.rst-content .wy-alert-neutral.admonition-todo .wy-alert-title,.rst-content .wy-alert-neutral.admonition .admonition-title,.rst-content .wy-alert-neutral.admonition .wy-alert-title,.rst-content .wy-alert-neutral.attention .admonition-title,.rst-content .wy-alert-neutral.attention .wy-alert-title,.rst-content .wy-alert-neutral.caution .admonition-title,.rst-content .wy-alert-neutral.caution .wy-alert-title,.rst-content .wy-alert-neutral.danger .admonition-title,.rst-content .wy-alert-neutral.danger .wy-alert-title,.rst-content .wy-alert-neutral.error .admonition-title,.rst-content .wy-alert-neutral.error .wy-alert-title,.rst-content .wy-alert-neutral.hint .admonition-title,.rst-content .wy-alert-neutral.hint .wy-alert-title,.rst-content .wy-alert-neutral.important .admonition-title,.rst-content .wy-alert-neutral.important .wy-alert-title,.rst-content .wy-alert-neutral.note .admonition-title,.rst-content .wy-alert-neutral.note .wy-alert-title,.rst-content .wy-alert-neutral.seealso .admonition-title,.rst-content .wy-alert-neutral.seealso .wy-alert-title,.rst-content .wy-alert-neutral.tip .admonition-title,.rst-content .wy-alert-neutral.tip .wy-alert-title,.rst-content .wy-alert-neutral.warning .admonition-title,.rst-content .wy-alert-neutral.warning .wy-alert-title,.rst-content .wy-alert.wy-alert-neutral .admonition-title,.wy-alert.wy-alert-neutral .rst-content .admonition-title,.wy-alert.wy-alert-neutral .wy-alert-title{color:#404040;background:#e1e4e5}.rst-content .wy-alert-neutral.admonition-todo a,.rst-content .wy-alert-neutral.admonition a,.rst-content .wy-alert-neutral.attention a,.rst-content .wy-alert-neutral.caution a,.rst-content .wy-alert-neutral.danger a,.rst-content .wy-alert-neutral.error a,.rst-content .wy-alert-neutral.hint a,.rst-content .wy-alert-neutral.important a,.rst-content .wy-alert-neutral.note a,.rst-content .wy-alert-neutral.seealso a,.rst-content .wy-alert-neutral.tip a,.rst-content .wy-alert-neutral.warning a,.wy-alert.wy-alert-neutral a{color:#2980b9}.rst-content .admonition-todo p:last-child,.rst-content .admonition p:last-child,.rst-content .attention p:last-child,.rst-content .caution p:last-child,.rst-content .danger p:last-child,.rst-content .error p:last-child,.rst-content .hint p:last-child,.rst-content .important p:last-child,.rst-content .note p:last-child,.rst-content .seealso p:last-child,.rst-content .tip p:last-child,.rst-content .warning p:last-child,.wy-alert p:last-child{margin-bottom:0}.wy-tray-container{position:fixed;bottom:0;left:0;z-index:600}.wy-tray-container li{display:block;width:300px;background:transparent;color:#fff;text-align:center;box-shadow:0 5px 5px 0 rgba(0,0,0,.1);padding:0 24px;min-width:20%;opacity:0;height:0;line-height:56px;overflow:hidden;-webkit-transition:all .3s ease-in;-moz-transition:all .3s ease-in;transition:all .3s ease-in}.wy-tray-container li.wy-tray-item-success{background:#27ae60}.wy-tray-container li.wy-tray-item-info{background:#2980b9}.wy-tray-container li.wy-tray-item-warning{background:#e67e22}.wy-tray-container li.wy-tray-item-danger{background:#e74c3c}.wy-tray-container li.on{opacity:1;height:56px}@media screen and (max-width:768px){.wy-tray-container{bottom:auto;top:0;width:100%}.wy-tray-container li{width:100%}}button{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle;cursor:pointer;line-height:normal;-webkit-appearance:button;*overflow:visible}button::-moz-focus-inner,input::-moz-focus-inner{border:0;padding:0}button[disabled]{cursor:default}.btn{display:inline-block;border-radius:2px;line-height:normal;white-space:nowrap;text-align:center;cursor:pointer;font-size:100%;padding:6px 12px 8px;color:#fff;border:1px solid rgba(0,0,0,.1);background-color:#27ae60;text-decoration:none;font-weight:400;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 2px -1px hsla(0,0%,100%,.5),inset 0 -2px 0 0 rgba(0,0,0,.1);outline-none:false;vertical-align:middle;*display:inline;zoom:1;-webkit-user-drag:none;-webkit-user-select:none;-moz-user-select:none;-ms-user-select:none;user-select:none;-webkit-transition:all .1s linear;-moz-transition:all .1s linear;transition:all .1s linear}.btn-hover{background:#2e8ece;color:#fff}.btn:hover{background:#2cc36b;color:#fff}.btn:focus{background:#2cc36b;outline:0}.btn:active{box-shadow:inset 0 -1px 0 0 rgba(0,0,0,.05),inset 0 2px 0 0 rgba(0,0,0,.1);padding:8px 12px 6px}.btn:visited{color:#fff}.btn-disabled,.btn-disabled:active,.btn-disabled:focus,.btn-disabled:hover,.btn:disabled{background-image:none;filter:progid:DXImageTransform.Microsoft.gradient(enabled = false);filter:alpha(opacity=40);opacity:.4;cursor:not-allowed;box-shadow:none}.btn::-moz-focus-inner{padding:0;border:0}.btn-small{font-size:80%}.btn-info{background-color:#2980b9!important}.btn-info:hover{background-color:#2e8ece!important}.btn-neutral{background-color:#f3f6f6!important;color:#404040!important}.btn-neutral:hover{background-color:#e5ebeb!important;color:#404040}.btn-neutral:visited{color:#404040!important}.btn-success{background-color:#27ae60!important}.btn-success:hover{background-color:#295!important}.btn-danger{background-color:#e74c3c!important}.btn-danger:hover{background-color:#ea6153!important}.btn-warning{background-color:#e67e22!important}.btn-warning:hover{background-color:#e98b39!important}.btn-invert{background-color:#222}.btn-invert:hover{background-color:#2f2f2f!important}.btn-link{background-color:transparent!important;color:#2980b9;box-shadow:none;border-color:transparent!important}.btn-link:active,.btn-link:hover{background-color:transparent!important;color:#409ad5!important;box-shadow:none}.btn-link:visited{color:#9b59b6}.wy-btn-group .btn,.wy-control .btn{vertical-align:middle}.wy-btn-group{margin-bottom:24px;*zoom:1}.wy-btn-group:after,.wy-btn-group:before{display:table;content:""}.wy-btn-group:after{clear:both}.wy-dropdown{position:relative;display:inline-block}.wy-dropdown-active .wy-dropdown-menu{display:block}.wy-dropdown-menu{position:absolute;left:0;display:none;float:left;top:100%;min-width:100%;background:#fcfcfc;z-index:100;border:1px solid #cfd7dd;box-shadow:0 2px 2px 0 rgba(0,0,0,.1);padding:12px}.wy-dropdown-menu>dd>a{display:block;clear:both;color:#404040;white-space:nowrap;font-size:90%;padding:0 12px;cursor:pointer}.wy-dropdown-menu>dd>a:hover{background:#2980b9;color:#fff}.wy-dropdown-menu>dd.divider{border-top:1px solid #cfd7dd;margin:6px 0}.wy-dropdown-menu>dd.search{padding-bottom:12px}.wy-dropdown-menu>dd.search input[type=search]{width:100%}.wy-dropdown-menu>dd.call-to-action{background:#e3e3e3;text-transform:uppercase;font-weight:500;font-size:80%}.wy-dropdown-menu>dd.call-to-action:hover{background:#e3e3e3}.wy-dropdown-menu>dd.call-to-action .btn{color:#fff}.wy-dropdown.wy-dropdown-up .wy-dropdown-menu{bottom:100%;top:auto;left:auto;right:0}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu{background:#fcfcfc;margin-top:2px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a{padding:6px 12px}.wy-dropdown.wy-dropdown-bubble .wy-dropdown-menu a:hover{background:#2980b9;color:#fff}.wy-dropdown.wy-dropdown-left .wy-dropdown-menu{right:0;left:auto;text-align:right}.wy-dropdown-arrow:before{content:" ";border-bottom:5px solid #f5f5f5;border-left:5px solid transparent;border-right:5px solid transparent;position:absolute;display:block;top:-4px;left:50%;margin-left:-3px}.wy-dropdown-arrow.wy-dropdown-arrow-left:before{left:11px}.wy-form-stacked select{display:block}.wy-form-aligned .wy-help-inline,.wy-form-aligned input,.wy-form-aligned label,.wy-form-aligned select,.wy-form-aligned textarea{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-form-aligned .wy-control-group>label{display:inline-block;vertical-align:middle;width:10em;margin:6px 12px 0 0;float:left}.wy-form-aligned .wy-control{float:left}.wy-form-aligned .wy-control label{display:block}.wy-form-aligned .wy-control select{margin-top:6px}fieldset{margin:0}fieldset,legend{border:0;padding:0}legend{width:100%;white-space:normal;margin-bottom:24px;font-size:150%;*margin-left:-7px}label,legend{display:block}label{margin:0 0 .3125em;color:#333;font-size:90%}input,select,textarea{font-size:100%;margin:0;vertical-align:baseline;*vertical-align:middle}.wy-control-group{margin-bottom:24px;max-width:1200px;margin-left:auto;margin-right:auto;*zoom:1}.wy-control-group:after,.wy-control-group:before{display:table;content:""}.wy-control-group:after{clear:both}.wy-control-group.wy-control-group-required>label:after{content:" *";color:#e74c3c}.wy-control-group .wy-form-full,.wy-control-group .wy-form-halves,.wy-control-group .wy-form-thirds{padding-bottom:12px}.wy-control-group .wy-form-full input[type=color],.wy-control-group .wy-form-full input[type=date],.wy-control-group .wy-form-full input[type=datetime-local],.wy-control-group .wy-form-full input[type=datetime],.wy-control-group .wy-form-full input[type=email],.wy-control-group .wy-form-full input[type=month],.wy-control-group .wy-form-full input[type=number],.wy-control-group .wy-form-full input[type=password],.wy-control-group .wy-form-full input[type=search],.wy-control-group .wy-form-full input[type=tel],.wy-control-group .wy-form-full input[type=text],.wy-control-group .wy-form-full input[type=time],.wy-control-group .wy-form-full input[type=url],.wy-control-group .wy-form-full input[type=week],.wy-control-group .wy-form-full select,.wy-control-group .wy-form-halves input[type=color],.wy-control-group .wy-form-halves input[type=date],.wy-control-group .wy-form-halves input[type=datetime-local],.wy-control-group .wy-form-halves input[type=datetime],.wy-control-group .wy-form-halves input[type=email],.wy-control-group .wy-form-halves input[type=month],.wy-control-group .wy-form-halves input[type=number],.wy-control-group .wy-form-halves input[type=password],.wy-control-group .wy-form-halves input[type=search],.wy-control-group .wy-form-halves input[type=tel],.wy-control-group .wy-form-halves input[type=text],.wy-control-group .wy-form-halves input[type=time],.wy-control-group .wy-form-halves input[type=url],.wy-control-group .wy-form-halves input[type=week],.wy-control-group .wy-form-halves select,.wy-control-group .wy-form-thirds input[type=color],.wy-control-group .wy-form-thirds input[type=date],.wy-control-group .wy-form-thirds input[type=datetime-local],.wy-control-group .wy-form-thirds input[type=datetime],.wy-control-group .wy-form-thirds input[type=email],.wy-control-group .wy-form-thirds input[type=month],.wy-control-group .wy-form-thirds input[type=number],.wy-control-group .wy-form-thirds input[type=password],.wy-control-group .wy-form-thirds input[type=search],.wy-control-group .wy-form-thirds input[type=tel],.wy-control-group .wy-form-thirds input[type=text],.wy-control-group .wy-form-thirds input[type=time],.wy-control-group .wy-form-thirds input[type=url],.wy-control-group .wy-form-thirds input[type=week],.wy-control-group .wy-form-thirds select{width:100%}.wy-control-group .wy-form-full{float:left;display:block;width:100%;margin-right:0}.wy-control-group .wy-form-full:last-child{margin-right:0}.wy-control-group .wy-form-halves{float:left;display:block;margin-right:2.35765%;width:48.82117%}.wy-control-group .wy-form-halves:last-child,.wy-control-group .wy-form-halves:nth-of-type(2n){margin-right:0}.wy-control-group .wy-form-halves:nth-of-type(odd){clear:left}.wy-control-group .wy-form-thirds{float:left;display:block;margin-right:2.35765%;width:31.76157%}.wy-control-group .wy-form-thirds:last-child,.wy-control-group .wy-form-thirds:nth-of-type(3n){margin-right:0}.wy-control-group .wy-form-thirds:nth-of-type(3n+1){clear:left}.wy-control-group.wy-control-group-no-input .wy-control,.wy-control-no-input{margin:6px 0 0;font-size:90%}.wy-control-no-input{display:inline-block}.wy-control-group.fluid-input input[type=color],.wy-control-group.fluid-input input[type=date],.wy-control-group.fluid-input input[type=datetime-local],.wy-control-group.fluid-input input[type=datetime],.wy-control-group.fluid-input input[type=email],.wy-control-group.fluid-input input[type=month],.wy-control-group.fluid-input input[type=number],.wy-control-group.fluid-input input[type=password],.wy-control-group.fluid-input input[type=search],.wy-control-group.fluid-input input[type=tel],.wy-control-group.fluid-input input[type=text],.wy-control-group.fluid-input input[type=time],.wy-control-group.fluid-input input[type=url],.wy-control-group.fluid-input input[type=week]{width:100%}.wy-form-message-inline{padding-left:.3em;color:#666;font-size:90%}.wy-form-message{display:block;color:#999;font-size:70%;margin-top:.3125em;font-style:italic}.wy-form-message p{font-size:inherit;font-style:italic;margin-bottom:6px}.wy-form-message p:last-child{margin-bottom:0}input{line-height:normal}input[type=button],input[type=reset],input[type=submit]{-webkit-appearance:button;cursor:pointer;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;*overflow:visible}input[type=color],input[type=date],input[type=datetime-local],input[type=datetime],input[type=email],input[type=month],input[type=number],input[type=password],input[type=search],input[type=tel],input[type=text],input[type=time],input[type=url],input[type=week]{-webkit-appearance:none;padding:6px;display:inline-block;border:1px solid #ccc;font-size:80%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;box-shadow:inset 0 1px 3px #ddd;border-radius:0;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}input[type=datetime-local]{padding:.34375em .625em}input[disabled]{cursor:default}input[type=checkbox],input[type=radio]{padding:0;margin-right:.3125em;*height:13px;*width:13px}input[type=checkbox],input[type=radio],input[type=search]{-webkit-box-sizing:border-box;-moz-box-sizing:border-box;box-sizing:border-box}input[type=search]::-webkit-search-cancel-button,input[type=search]::-webkit-search-decoration{-webkit-appearance:none}input[type=color]:focus,input[type=date]:focus,input[type=datetime-local]:focus,input[type=datetime]:focus,input[type=email]:focus,input[type=month]:focus,input[type=number]:focus,input[type=password]:focus,input[type=search]:focus,input[type=tel]:focus,input[type=text]:focus,input[type=time]:focus,input[type=url]:focus,input[type=week]:focus{outline:0;outline:thin dotted\9;border-color:#333}input.no-focus:focus{border-color:#ccc!important}input[type=checkbox]:focus,input[type=file]:focus,input[type=radio]:focus{outline:thin dotted #333;outline:1px auto #129fea}input[type=color][disabled],input[type=date][disabled],input[type=datetime-local][disabled],input[type=datetime][disabled],input[type=email][disabled],input[type=month][disabled],input[type=number][disabled],input[type=password][disabled],input[type=search][disabled],input[type=tel][disabled],input[type=text][disabled],input[type=time][disabled],input[type=url][disabled],input[type=week][disabled]{cursor:not-allowed;background-color:#fafafa}input:focus:invalid,select:focus:invalid,textarea:focus:invalid{color:#e74c3c;border:1px solid #e74c3c}input:focus:invalid:focus,select:focus:invalid:focus,textarea:focus:invalid:focus{border-color:#e74c3c}input[type=checkbox]:focus:invalid:focus,input[type=file]:focus:invalid:focus,input[type=radio]:focus:invalid:focus{outline-color:#e74c3c}input.wy-input-large{padding:12px;font-size:100%}textarea{overflow:auto;vertical-align:top;width:100%;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif}select,textarea{padding:.5em .625em;display:inline-block;border:1px solid #ccc;font-size:80%;box-shadow:inset 0 1px 3px #ddd;-webkit-transition:border .3s linear;-moz-transition:border .3s linear;transition:border .3s linear}select{border:1px solid #ccc;background-color:#fff}select[multiple]{height:auto}select:focus,textarea:focus{outline:0}input[readonly],select[disabled],select[readonly],textarea[disabled],textarea[readonly]{cursor:not-allowed;background-color:#fafafa}input[type=checkbox][disabled],input[type=radio][disabled]{cursor:not-allowed}.wy-checkbox,.wy-radio{margin:6px 0;color:#404040;display:block}.wy-checkbox input,.wy-radio input{vertical-align:baseline}.wy-form-message-inline{display:inline-block;*display:inline;*zoom:1;vertical-align:middle}.wy-input-prefix,.wy-input-suffix{white-space:nowrap;padding:6px}.wy-input-prefix .wy-input-context,.wy-input-suffix .wy-input-context{line-height:27px;padding:0 8px;display:inline-block;font-size:80%;background-color:#f3f6f6;border:1px solid #ccc;color:#999}.wy-input-suffix .wy-input-context{border-left:0}.wy-input-prefix .wy-input-context{border-right:0}.wy-switch{position:relative;display:block;height:24px;margin-top:12px;cursor:pointer}.wy-switch:before{left:0;top:0;width:36px;height:12px;background:#ccc}.wy-switch:after,.wy-switch:before{position:absolute;content:"";display:block;border-radius:4px;-webkit-transition:all .2s ease-in-out;-moz-transition:all .2s ease-in-out;transition:all .2s ease-in-out}.wy-switch:after{width:18px;height:18px;background:#999;left:-3px;top:-3px}.wy-switch span{position:absolute;left:48px;display:block;font-size:12px;color:#ccc;line-height:1}.wy-switch.active:before{background:#1e8449}.wy-switch.active:after{left:24px;background:#27ae60}.wy-switch.disabled{cursor:not-allowed;opacity:.8}.wy-control-group.wy-control-group-error .wy-form-message,.wy-control-group.wy-control-group-error>label{color:#e74c3c}.wy-control-group.wy-control-group-error input[type=color],.wy-control-group.wy-control-group-error input[type=date],.wy-control-group.wy-control-group-error input[type=datetime-local],.wy-control-group.wy-control-group-error input[type=datetime],.wy-control-group.wy-control-group-error input[type=email],.wy-control-group.wy-control-group-error input[type=month],.wy-control-group.wy-control-group-error input[type=number],.wy-control-group.wy-control-group-error input[type=password],.wy-control-group.wy-control-group-error input[type=search],.wy-control-group.wy-control-group-error input[type=tel],.wy-control-group.wy-control-group-error input[type=text],.wy-control-group.wy-control-group-error input[type=time],.wy-control-group.wy-control-group-error input[type=url],.wy-control-group.wy-control-group-error input[type=week],.wy-control-group.wy-control-group-error textarea{border:1px solid #e74c3c}.wy-inline-validate{white-space:nowrap}.wy-inline-validate .wy-input-context{padding:.5em .625em;display:inline-block;font-size:80%}.wy-inline-validate.wy-inline-validate-success .wy-input-context{color:#27ae60}.wy-inline-validate.wy-inline-validate-danger .wy-input-context{color:#e74c3c}.wy-inline-validate.wy-inline-validate-warning .wy-input-context{color:#e67e22}.wy-inline-validate.wy-inline-validate-info .wy-input-context{color:#2980b9}.rotate-90{-webkit-transform:rotate(90deg);-moz-transform:rotate(90deg);-ms-transform:rotate(90deg);-o-transform:rotate(90deg);transform:rotate(90deg)}.rotate-180{-webkit-transform:rotate(180deg);-moz-transform:rotate(180deg);-ms-transform:rotate(180deg);-o-transform:rotate(180deg);transform:rotate(180deg)}.rotate-270{-webkit-transform:rotate(270deg);-moz-transform:rotate(270deg);-ms-transform:rotate(270deg);-o-transform:rotate(270deg);transform:rotate(270deg)}.mirror{-webkit-transform:scaleX(-1);-moz-transform:scaleX(-1);-ms-transform:scaleX(-1);-o-transform:scaleX(-1);transform:scaleX(-1)}.mirror.rotate-90{-webkit-transform:scaleX(-1) rotate(90deg);-moz-transform:scaleX(-1) rotate(90deg);-ms-transform:scaleX(-1) rotate(90deg);-o-transform:scaleX(-1) rotate(90deg);transform:scaleX(-1) rotate(90deg)}.mirror.rotate-180{-webkit-transform:scaleX(-1) rotate(180deg);-moz-transform:scaleX(-1) rotate(180deg);-ms-transform:scaleX(-1) rotate(180deg);-o-transform:scaleX(-1) rotate(180deg);transform:scaleX(-1) rotate(180deg)}.mirror.rotate-270{-webkit-transform:scaleX(-1) rotate(270deg);-moz-transform:scaleX(-1) rotate(270deg);-ms-transform:scaleX(-1) rotate(270deg);-o-transform:scaleX(-1) rotate(270deg);transform:scaleX(-1) rotate(270deg)}@media only screen and (max-width:480px){.wy-form button[type=submit]{margin:.7em 0 0}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=text],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week],.wy-form label{margin-bottom:.3em;display:block}.wy-form input[type=color],.wy-form input[type=date],.wy-form input[type=datetime-local],.wy-form input[type=datetime],.wy-form input[type=email],.wy-form input[type=month],.wy-form input[type=number],.wy-form input[type=password],.wy-form input[type=search],.wy-form input[type=tel],.wy-form input[type=time],.wy-form input[type=url],.wy-form input[type=week]{margin-bottom:0}.wy-form-aligned .wy-control-group label{margin-bottom:.3em;text-align:left;display:block;width:100%}.wy-form-aligned .wy-control{margin:1.5em 0 0}.wy-form-message,.wy-form-message-inline,.wy-form .wy-help-inline{display:block;font-size:80%;padding:6px 0}}@media screen and (max-width:768px){.tablet-hide{display:none}}@media screen and (max-width:480px){.mobile-hide{display:none}}.float-left{float:left}.float-right{float:right}.full-width{width:100%}.rst-content table.docutils,.rst-content table.field-list,.wy-table{border-collapse:collapse;border-spacing:0;empty-cells:show;margin-bottom:24px}.rst-content table.docutils caption,.rst-content table.field-list caption,.wy-table caption{color:#000;font:italic 85%/1 arial,sans-serif;padding:1em 0;text-align:center}.rst-content table.docutils td,.rst-content table.docutils th,.rst-content table.field-list td,.rst-content table.field-list th,.wy-table td,.wy-table th{font-size:90%;margin:0;overflow:visible;padding:8px 16px}.rst-content table.docutils td:first-child,.rst-content table.docutils th:first-child,.rst-content table.field-list td:first-child,.rst-content table.field-list th:first-child,.wy-table td:first-child,.wy-table th:first-child{border-left-width:0}.rst-content table.docutils thead,.rst-content table.field-list thead,.wy-table thead{color:#000;text-align:left;vertical-align:bottom;white-space:nowrap}.rst-content table.docutils thead th,.rst-content table.field-list thead th,.wy-table thead th{font-weight:700;border-bottom:2px solid #e1e4e5}.rst-content table.docutils td,.rst-content table.field-list td,.wy-table td{background-color:transparent;vertical-align:middle}.rst-content table.docutils td p,.rst-content table.field-list td p,.wy-table td p{line-height:18px}.rst-content table.docutils td p:last-child,.rst-content table.field-list td p:last-child,.wy-table td p:last-child{margin-bottom:0}.rst-content table.docutils .wy-table-cell-min,.rst-content table.field-list .wy-table-cell-min,.wy-table .wy-table-cell-min{width:1%;padding-right:0}.rst-content table.docutils .wy-table-cell-min input[type=checkbox],.rst-content table.field-list .wy-table-cell-min input[type=checkbox],.wy-table .wy-table-cell-min input[type=checkbox]{margin:0}.wy-table-secondary{color:grey;font-size:90%}.wy-table-tertiary{color:grey;font-size:80%}.rst-content table.docutils:not(.field-list) tr:nth-child(2n-1) td,.wy-table-backed,.wy-table-odd td,.wy-table-striped tr:nth-child(2n-1) td{background-color:#f3f6f6}.rst-content table.docutils,.wy-table-bordered-all{border:1px solid #e1e4e5}.rst-content table.docutils td,.wy-table-bordered-all td{border-bottom:1px solid #e1e4e5;border-left:1px solid #e1e4e5}.rst-content table.docutils tbody>tr:last-child td,.wy-table-bordered-all tbody>tr:last-child td{border-bottom-width:0}.wy-table-bordered{border:1px solid #e1e4e5}.wy-table-bordered-rows td{border-bottom:1px solid #e1e4e5}.wy-table-bordered-rows tbody>tr:last-child td{border-bottom-width:0}.wy-table-horizontal td,.wy-table-horizontal th{border-width:0 0 1px;border-bottom:1px solid #e1e4e5}.wy-table-horizontal tbody>tr:last-child td{border-bottom-width:0}.wy-table-responsive{margin-bottom:24px;max-width:100%;overflow:auto}.wy-table-responsive table{margin-bottom:0!important}.wy-table-responsive table td,.wy-table-responsive table th{white-space:nowrap}a{color:#2980b9;text-decoration:none;cursor:pointer}a:hover{color:#3091d1}a:visited{color:#9b59b6}html{height:100%}body,html{overflow-x:hidden}body{font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;font-weight:400;color:#404040;min-height:100%;background:#edf0f2}.wy-text-left{text-align:left}.wy-text-center{text-align:center}.wy-text-right{text-align:right}.wy-text-large{font-size:120%}.wy-text-normal{font-size:100%}.wy-text-small,small{font-size:80%}.wy-text-strike{text-decoration:line-through}.wy-text-warning{color:#e67e22!important}a.wy-text-warning:hover{color:#eb9950!important}.wy-text-info{color:#2980b9!important}a.wy-text-info:hover{color:#409ad5!important}.wy-text-success{color:#27ae60!important}a.wy-text-success:hover{color:#36d278!important}.wy-text-danger{color:#e74c3c!important}a.wy-text-danger:hover{color:#ed7669!important}.wy-text-neutral{color:#404040!important}a.wy-text-neutral:hover{color:#595959!important}.rst-content .toctree-wrapper>p.caption,h1,h2,h3,h4,h5,h6,legend{margin-top:0;font-weight:700;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif}p{line-height:24px;font-size:16px;margin:0 0 24px}h1{font-size:175%}.rst-content .toctree-wrapper>p.caption,h2{font-size:150%}h3{font-size:125%}h4{font-size:115%}h5{font-size:110%}h6{font-size:100%}hr{display:block;height:1px;border:0;border-top:1px solid #e1e4e5;margin:24px 0;padding:0}.rst-content code,.rst-content tt,code{white-space:nowrap;max-width:100%;background:#fff;border:1px solid #e1e4e5;font-size:75%;padding:0 5px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;color:#e74c3c;overflow-x:auto}.rst-content tt.code-large,code.code-large{font-size:90%}.rst-content .section ul,.rst-content .toctree-wrapper ul,.wy-plain-list-disc,article ul{list-style:disc;line-height:24px;margin-bottom:24px}.rst-content .section ul li,.rst-content .toctree-wrapper ul li,.wy-plain-list-disc li,article ul li{list-style:disc;margin-left:24px}.rst-content .section ul li p:last-child,.rst-content .section ul li ul,.rst-content .toctree-wrapper ul li p:last-child,.rst-content .toctree-wrapper ul li ul,.wy-plain-list-disc li p:last-child,.wy-plain-list-disc li ul,article ul li p:last-child,article ul li ul{margin-bottom:0}.rst-content .section ul li li,.rst-content .toctree-wrapper ul li li,.wy-plain-list-disc li li,article ul li li{list-style:circle}.rst-content .section ul li li li,.rst-content .toctree-wrapper ul li li li,.wy-plain-list-disc li li li,article ul li li li{list-style:square}.rst-content .section ul li ol li,.rst-content .toctree-wrapper ul li ol li,.wy-plain-list-disc li ol li,article ul li ol li{list-style:decimal}.rst-content .section ol,.rst-content ol.arabic,.wy-plain-list-decimal,article ol{list-style:decimal;line-height:24px;margin-bottom:24px}.rst-content .section ol li,.rst-content ol.arabic li,.wy-plain-list-decimal li,article ol li{list-style:decimal;margin-left:24px}.rst-content .section ol li p:last-child,.rst-content .section ol li ul,.rst-content ol.arabic li p:last-child,.rst-content ol.arabic li ul,.wy-plain-list-decimal li p:last-child,.wy-plain-list-decimal li ul,article ol li p:last-child,article ol li ul{margin-bottom:0}.rst-content .section ol li ul li,.rst-content ol.arabic li ul li,.wy-plain-list-decimal li ul li,article ol li ul li{list-style:disc}.wy-breadcrumbs{*zoom:1}.wy-breadcrumbs:after,.wy-breadcrumbs:before{display:table;content:""}.wy-breadcrumbs:after{clear:both}.wy-breadcrumbs li{display:inline-block}.wy-breadcrumbs li.wy-breadcrumbs-aside{float:right}.wy-breadcrumbs li a{display:inline-block;padding:5px}.wy-breadcrumbs li a:first-child{padding-left:0}.rst-content .wy-breadcrumbs li tt,.wy-breadcrumbs li .rst-content tt,.wy-breadcrumbs li code{padding:5px;border:none;background:none}.rst-content .wy-breadcrumbs li tt.literal,.wy-breadcrumbs li .rst-content tt.literal,.wy-breadcrumbs li code.literal{color:#404040}.wy-breadcrumbs-extra{margin-bottom:0;color:#b3b3b3;font-size:80%;display:inline-block}@media screen and (max-width:480px){.wy-breadcrumbs-extra,.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}@media print{.wy-breadcrumbs li.wy-breadcrumbs-aside{display:none}}html{font-size:16px}.wy-affix{position:fixed;top:1.618em}.wy-menu a:hover{text-decoration:none}.wy-menu-horiz{*zoom:1}.wy-menu-horiz:after,.wy-menu-horiz:before{display:table;content:""}.wy-menu-horiz:after{clear:both}.wy-menu-horiz li,.wy-menu-horiz ul{display:inline-block}.wy-menu-horiz li:hover{background:hsla(0,0%,100%,.1)}.wy-menu-horiz li.divide-left{border-left:1px solid #404040}.wy-menu-horiz li.divide-right{border-right:1px solid #404040}.wy-menu-horiz a{height:32px;display:inline-block;line-height:32px;padding:0 16px}.wy-menu-vertical{width:300px}.wy-menu-vertical header,.wy-menu-vertical p.caption{color:#55a5d9;height:32px;line-height:32px;padding:0 1.618em;margin:12px 0 0;display:block;font-weight:700;text-transform:uppercase;font-size:85%;white-space:nowrap}.wy-menu-vertical ul{margin-bottom:0}.wy-menu-vertical li.divide-top{border-top:1px solid #404040}.wy-menu-vertical li.divide-bottom{border-bottom:1px solid #404040}.wy-menu-vertical li.current{background:#e3e3e3}.wy-menu-vertical li.current a{color:grey;border-right:1px solid #c9c9c9;padding:.4045em 2.427em}.wy-menu-vertical li.current a:hover{background:#d6d6d6}.rst-content .wy-menu-vertical li tt,.wy-menu-vertical li .rst-content tt,.wy-menu-vertical li code{border:none;background:inherit;color:inherit;padding-left:0;padding-right:0}.wy-menu-vertical li span.toctree-expand{display:block;float:left;margin-left:-1.2em;line-height:18px;color:#4d4d4d}.wy-menu-vertical li.current>a,.wy-menu-vertical li.on a{color:#404040;font-weight:700;position:relative;background:#fcfcfc;border:none;padding:.4045em 1.618em}.wy-menu-vertical li.current>a:hover,.wy-menu-vertical li.on a:hover{background:#fcfcfc}.wy-menu-vertical li.current>a:hover span.toctree-expand,.wy-menu-vertical li.on a:hover span.toctree-expand{color:grey}.wy-menu-vertical li.current>a span.toctree-expand,.wy-menu-vertical li.on a span.toctree-expand{display:block;line-height:18px;color:#333}.wy-menu-vertical li.toctree-l1.current>a{border-bottom:1px solid #c9c9c9;border-top:1px solid #c9c9c9}.wy-menu-vertical .toctree-l1.current .toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .toctree-l11>ul{display:none}.wy-menu-vertical .toctree-l1.current .current.toctree-l2>ul,.wy-menu-vertical .toctree-l2.current .current.toctree-l3>ul,.wy-menu-vertical .toctree-l3.current .current.toctree-l4>ul,.wy-menu-vertical .toctree-l4.current .current.toctree-l5>ul,.wy-menu-vertical .toctree-l5.current .current.toctree-l6>ul,.wy-menu-vertical .toctree-l6.current .current.toctree-l7>ul,.wy-menu-vertical .toctree-l7.current .current.toctree-l8>ul,.wy-menu-vertical .toctree-l8.current .current.toctree-l9>ul,.wy-menu-vertical .toctree-l9.current .current.toctree-l10>ul,.wy-menu-vertical .toctree-l10.current .current.toctree-l11>ul{display:block}.wy-menu-vertical li.toctree-l3,.wy-menu-vertical li.toctree-l4{font-size:.9em}.wy-menu-vertical li.toctree-l2 a,.wy-menu-vertical li.toctree-l3 a,.wy-menu-vertical li.toctree-l4 a,.wy-menu-vertical li.toctree-l5 a,.wy-menu-vertical li.toctree-l6 a,.wy-menu-vertical li.toctree-l7 a,.wy-menu-vertical li.toctree-l8 a,.wy-menu-vertical li.toctree-l9 a,.wy-menu-vertical li.toctree-l10 a{color:#404040}.wy-menu-vertical li.toctree-l2 a:hover span.toctree-expand,.wy-menu-vertical li.toctree-l3 a:hover span.toctree-expand,.wy-menu-vertical li.toctree-l4 a:hover span.toctree-expand,.wy-menu-vertical li.toctree-l5 a:hover span.toctree-expand,.wy-menu-vertical li.toctree-l6 a:hover span.toctree-expand,.wy-menu-vertical li.toctree-l7 a:hover span.toctree-expand,.wy-menu-vertical li.toctree-l8 a:hover span.toctree-expand,.wy-menu-vertical li.toctree-l9 a:hover span.toctree-expand,.wy-menu-vertical li.toctree-l10 a:hover span.toctree-expand{color:grey}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a,.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a,.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a,.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a,.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a,.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a,.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a,.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{display:block}.wy-menu-vertical li.toctree-l2.current>a{padding:.4045em 2.427em}.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{padding:.4045em 1.618em .4045em 4.045em}.wy-menu-vertical li.toctree-l3.current>a{padding:.4045em 4.045em}.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{padding:.4045em 1.618em .4045em 5.663em}.wy-menu-vertical li.toctree-l4.current>a{padding:.4045em 5.663em}.wy-menu-vertical li.toctree-l4.current li.toctree-l5>a{padding:.4045em 1.618em .4045em 7.281em}.wy-menu-vertical li.toctree-l5.current>a{padding:.4045em 7.281em}.wy-menu-vertical li.toctree-l5.current li.toctree-l6>a{padding:.4045em 1.618em .4045em 8.899em}.wy-menu-vertical li.toctree-l6.current>a{padding:.4045em 8.899em}.wy-menu-vertical li.toctree-l6.current li.toctree-l7>a{padding:.4045em 1.618em .4045em 10.517em}.wy-menu-vertical li.toctree-l7.current>a{padding:.4045em 10.517em}.wy-menu-vertical li.toctree-l7.current li.toctree-l8>a{padding:.4045em 1.618em .4045em 12.135em}.wy-menu-vertical li.toctree-l8.current>a{padding:.4045em 12.135em}.wy-menu-vertical li.toctree-l8.current li.toctree-l9>a{padding:.4045em 1.618em .4045em 13.753em}.wy-menu-vertical li.toctree-l9.current>a{padding:.4045em 13.753em}.wy-menu-vertical li.toctree-l9.current li.toctree-l10>a{padding:.4045em 1.618em .4045em 15.371em}.wy-menu-vertical li.toctree-l10.current>a{padding:.4045em 15.371em}.wy-menu-vertical li.toctree-l10.current li.toctree-l11>a{padding:.4045em 1.618em .4045em 16.989em}.wy-menu-vertical li.toctree-l2.current>a,.wy-menu-vertical li.toctree-l2.current li.toctree-l3>a{background:#c9c9c9}.wy-menu-vertical li.toctree-l2 span.toctree-expand{color:#a3a3a3}.wy-menu-vertical li.toctree-l3.current>a,.wy-menu-vertical li.toctree-l3.current li.toctree-l4>a{background:#bdbdbd}.wy-menu-vertical li.toctree-l3 span.toctree-expand{color:#969696}.wy-menu-vertical li.current ul{display:block}.wy-menu-vertical li ul{margin-bottom:0;display:none}.wy-menu-vertical li ul li a{margin-bottom:0;color:#d9d9d9;font-weight:400}.wy-menu-vertical a{line-height:18px;padding:.4045em 1.618em;display:block;position:relative;font-size:90%;color:#d9d9d9}.wy-menu-vertical a:hover{background-color:#4e4a4a;cursor:pointer}.wy-menu-vertical a:hover span.toctree-expand{color:#d9d9d9}.wy-menu-vertical a:active{background-color:#2980b9;cursor:pointer;color:#fff}.wy-menu-vertical a:active span.toctree-expand{color:#fff}.wy-side-nav-search{display:block;width:300px;padding:.809em;margin-bottom:.809em;z-index:200;background-color:#2980b9;text-align:center;color:#fcfcfc}.wy-side-nav-search input[type=text]{width:100%;border-radius:50px;padding:6px 12px;border-color:#2472a4}.wy-side-nav-search img{display:block;margin:auto auto .809em;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-side-nav-search .wy-dropdown>a,.wy-side-nav-search>a{color:#fcfcfc;font-size:100%;font-weight:700;display:inline-block;padding:4px 6px;margin-bottom:.809em}.wy-side-nav-search .wy-dropdown>a:hover,.wy-side-nav-search>a:hover{background:hsla(0,0%,100%,.1)}.wy-side-nav-search .wy-dropdown>a img.logo,.wy-side-nav-search>a img.logo{display:block;margin:0 auto;height:auto;width:auto;border-radius:0;max-width:100%;background:transparent}.wy-side-nav-search .wy-dropdown>a.icon img.logo,.wy-side-nav-search>a.icon img.logo{margin-top:.85em}.wy-side-nav-search>div.version{margin-top:-.4045em;margin-bottom:.809em;font-weight:400;color:hsla(0,0%,100%,.3)}.wy-nav .wy-menu-vertical header{color:#2980b9}.wy-nav .wy-menu-vertical a{color:#b3b3b3}.wy-nav .wy-menu-vertical a:hover{background-color:#2980b9;color:#fff}[data-menu-wrap]{-webkit-transition:all .2s ease-in;-moz-transition:all .2s ease-in;transition:all .2s ease-in;position:absolute;opacity:1;width:100%;opacity:0}[data-menu-wrap].move-center{left:0;right:auto;opacity:1}[data-menu-wrap].move-left{right:auto;left:-100%;opacity:0}[data-menu-wrap].move-right{right:-100%;left:auto;opacity:0}.wy-body-for-nav{background:#fcfcfc}.wy-grid-for-nav{position:absolute;width:100%;height:100%}.wy-nav-side{position:fixed;top:0;bottom:0;left:0;padding-bottom:2em;width:300px;overflow-x:hidden;overflow-y:hidden;min-height:100%;color:#9b9b9b;background:#343131;z-index:200}.wy-side-scroll{width:320px;position:relative;overflow-x:hidden;overflow-y:scroll;height:100%}.wy-nav-top{display:none;background:#2980b9;color:#fff;padding:.4045em .809em;position:relative;line-height:50px;text-align:center;font-size:100%;*zoom:1}.wy-nav-top:after,.wy-nav-top:before{display:table;content:""}.wy-nav-top:after{clear:both}.wy-nav-top a{color:#fff;font-weight:700}.wy-nav-top img{margin-right:12px;height:45px;width:45px;background-color:#2980b9;padding:5px;border-radius:100%}.wy-nav-top i{font-size:30px;float:left;cursor:pointer;padding-top:inherit}.wy-nav-content-wrap{margin-left:300px;background:#fcfcfc;min-height:100%}.wy-nav-content{padding:1.618em 3.236em;height:100%;max-width:800px;margin:auto}.wy-body-mask{position:fixed;width:100%;height:100%;background:rgba(0,0,0,.2);display:none;z-index:499}.wy-body-mask.on{display:block}footer{color:grey}footer p{margin-bottom:12px}.rst-content footer span.commit tt,footer span.commit .rst-content tt,footer span.commit code{padding:0;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:1em;background:none;border:none;color:grey}.rst-footer-buttons{*zoom:1}.rst-footer-buttons:after,.rst-footer-buttons:before{width:100%;display:table;content:""}.rst-footer-buttons:after{clear:both}.rst-breadcrumbs-buttons{margin-top:12px;*zoom:1}.rst-breadcrumbs-buttons:after,.rst-breadcrumbs-buttons:before{display:table;content:""}.rst-breadcrumbs-buttons:after{clear:both}#search-results .search li{margin-bottom:24px;border-bottom:1px solid #e1e4e5;padding-bottom:24px}#search-results .search li:first-child{border-top:1px solid #e1e4e5;padding-top:24px}#search-results .search li a{font-size:120%;margin-bottom:12px;display:inline-block}#search-results .context{color:grey;font-size:90%}.genindextable li>ul{margin-left:24px}@media screen and (max-width:768px){.wy-body-for-nav{background:#fcfcfc}.wy-nav-top{display:block}.wy-nav-side{left:-300px}.wy-nav-side.shift{width:85%;left:0}.wy-menu.wy-menu-vertical,.wy-side-nav-search,.wy-side-scroll{width:auto}.wy-nav-content-wrap{margin-left:0}.wy-nav-content-wrap .wy-nav-content{padding:1.618em}.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:85%;top:0;height:100%;overflow:hidden}}@media screen and (min-width:1100px){.wy-nav-content-wrap{background:rgba(0,0,0,.05)}.wy-nav-content{margin:0;background:#fcfcfc}}@media print{.rst-versions,.wy-nav-side,footer{display:none}.wy-nav-content-wrap{margin-left:0}}.rst-versions{position:fixed;bottom:0;left:0;width:300px;color:#fcfcfc;background:#1f1d1d;font-family:Lato,proxima-nova,Helvetica Neue,Arial,sans-serif;z-index:400}.rst-versions a{color:#2980b9;text-decoration:none}.rst-versions .rst-badge-small{display:none}.rst-versions .rst-current-version{padding:12px;background-color:#272525;display:block;text-align:right;font-size:90%;cursor:pointer;color:#27ae60;*zoom:1}.rst-versions .rst-current-version:after,.rst-versions .rst-current-version:before{display:table;content:""}.rst-versions .rst-current-version:after{clear:both}.rst-content .code-block-caption .rst-versions .rst-current-version .headerlink,.rst-content .rst-versions .rst-current-version .admonition-title,.rst-content code.download .rst-versions .rst-current-version span:first-child,.rst-content dl dt .rst-versions .rst-current-version .headerlink,.rst-content h1 .rst-versions .rst-current-version .headerlink,.rst-content h2 .rst-versions .rst-current-version .headerlink,.rst-content h3 .rst-versions .rst-current-version .headerlink,.rst-content h4 .rst-versions .rst-current-version .headerlink,.rst-content h5 .rst-versions .rst-current-version .headerlink,.rst-content h6 .rst-versions .rst-current-version .headerlink,.rst-content p.caption .rst-versions .rst-current-version .headerlink,.rst-content table>caption .rst-versions .rst-current-version .headerlink,.rst-content tt.download .rst-versions .rst-current-version span:first-child,.rst-versions .rst-current-version .fa,.rst-versions .rst-current-version .icon,.rst-versions .rst-current-version .rst-content .admonition-title,.rst-versions .rst-current-version .rst-content .code-block-caption .headerlink,.rst-versions .rst-current-version .rst-content code.download span:first-child,.rst-versions .rst-current-version .rst-content dl dt .headerlink,.rst-versions .rst-current-version .rst-content h1 .headerlink,.rst-versions .rst-current-version .rst-content h2 .headerlink,.rst-versions .rst-current-version .rst-content h3 .headerlink,.rst-versions .rst-current-version .rst-content h4 .headerlink,.rst-versions .rst-current-version .rst-content h5 .headerlink,.rst-versions .rst-current-version .rst-content h6 .headerlink,.rst-versions .rst-current-version .rst-content p.caption .headerlink,.rst-versions .rst-current-version .rst-content table>caption .headerlink,.rst-versions .rst-current-version .rst-content tt.download span:first-child,.rst-versions .rst-current-version .wy-menu-vertical li span.toctree-expand,.wy-menu-vertical li .rst-versions .rst-current-version span.toctree-expand{color:#fcfcfc}.rst-versions .rst-current-version .fa-book,.rst-versions .rst-current-version .icon-book{float:left}.rst-versions .rst-current-version.rst-out-of-date{background-color:#e74c3c;color:#fff}.rst-versions .rst-current-version.rst-active-old-version{background-color:#f1c40f;color:#000}.rst-versions.shift-up{height:auto;max-height:100%;overflow-y:scroll}.rst-versions.shift-up .rst-other-versions{display:block}.rst-versions .rst-other-versions{font-size:90%;padding:12px;color:grey;display:none}.rst-versions .rst-other-versions hr{display:block;height:1px;border:0;margin:20px 0;padding:0;border-top:1px solid #413d3d}.rst-versions .rst-other-versions dd{display:inline-block;margin:0}.rst-versions .rst-other-versions dd a{display:inline-block;padding:6px;color:#fcfcfc}.rst-versions.rst-badge{width:auto;bottom:20px;right:20px;left:auto;border:none;max-width:300px;max-height:90%}.rst-versions.rst-badge .fa-book,.rst-versions.rst-badge .icon-book{float:none;line-height:30px}.rst-versions.rst-badge.shift-up .rst-current-version{text-align:right}.rst-versions.rst-badge.shift-up .rst-current-version .fa-book,.rst-versions.rst-badge.shift-up .rst-current-version .icon-book{float:left}.rst-versions.rst-badge>.rst-current-version{width:auto;height:30px;line-height:30px;padding:0 6px;display:block;text-align:center}@media screen and (max-width:768px){.rst-versions{width:85%;display:none}.rst-versions.shift{display:block}}.rst-content img{max-width:100%;height:auto}.rst-content div.figure{margin-bottom:24px}.rst-content div.figure p.caption{font-style:italic}.rst-content div.figure p:last-child.caption{margin-bottom:0}.rst-content div.figure.align-center{text-align:center}.rst-content .section>a>img,.rst-content .section>img{margin-bottom:24px}.rst-content abbr[title]{text-decoration:none}.rst-content.style-external-links a.reference.external:after{font-family:FontAwesome;content:"\f08e";color:#b3b3b3;vertical-align:super;font-size:60%;margin:0 .2em}.rst-content blockquote{margin-left:24px;line-height:24px;margin-bottom:24px}.rst-content pre.literal-block{white-space:pre;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;display:block;overflow:auto}.rst-content div[class^=highlight],.rst-content pre.literal-block{border:1px solid #e1e4e5;overflow-x:auto;margin:1px 0 24px}.rst-content div[class^=highlight] div[class^=highlight],.rst-content pre.literal-block div[class^=highlight]{padding:0;border:none;margin:0}.rst-content div[class^=highlight] td.code{width:100%}.rst-content .linenodiv pre{border-right:1px solid #e6e9ea;margin:0;padding:12px;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;user-select:none;pointer-events:none}.rst-content div[class^=highlight] pre{white-space:pre;margin:0;padding:12px;display:block;overflow:auto}.rst-content div[class^=highlight] pre .hll{display:block;margin:0 -12px;padding:0 12px}.rst-content .linenodiv pre,.rst-content div[class^=highlight] pre,.rst-content pre.literal-block{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;font-size:12px;line-height:1.4}.rst-content div.highlight .gp{user-select:none;pointer-events:none}.rst-content .code-block-caption{font-style:italic;font-size:85%;line-height:1;padding:1em 0;text-align:center}@media print{.rst-content .codeblock,.rst-content div[class^=highlight],.rst-content div[class^=highlight] pre{white-space:pre-wrap}}.rst-content .admonition,.rst-content .admonition-todo,.rst-content .attention,.rst-content .caution,.rst-content .danger,.rst-content .error,.rst-content .hint,.rst-content .important,.rst-content .note,.rst-content .seealso,.rst-content .tip,.rst-content .warning{clear:both}.rst-content .admonition-todo .last,.rst-content .admonition-todo>:last-child,.rst-content .admonition .last,.rst-content .admonition>:last-child,.rst-content .attention .last,.rst-content .attention>:last-child,.rst-content .caution .last,.rst-content .caution>:last-child,.rst-content .danger .last,.rst-content .danger>:last-child,.rst-content .error .last,.rst-content .error>:last-child,.rst-content .hint .last,.rst-content .hint>:last-child,.rst-content .important .last,.rst-content .important>:last-child,.rst-content .note .last,.rst-content .note>:last-child,.rst-content .seealso .last,.rst-content .seealso>:last-child,.rst-content .tip .last,.rst-content .tip>:last-child,.rst-content .warning .last,.rst-content .warning>:last-child{margin-bottom:0}.rst-content .admonition-title:before{margin-right:4px}.rst-content .admonition table{border-color:rgba(0,0,0,.1)}.rst-content .admonition table td,.rst-content .admonition table th{background:transparent!important;border-color:rgba(0,0,0,.1)!important}.rst-content .section ol.loweralpha,.rst-content .section ol.loweralpha>li{list-style:lower-alpha}.rst-content .section ol.upperalpha,.rst-content .section ol.upperalpha>li{list-style:upper-alpha}.rst-content .section ol li>*,.rst-content .section ul li>*{margin-top:12px;margin-bottom:12px}.rst-content .section ol li>:first-child,.rst-content .section ul li>:first-child{margin-top:0}.rst-content .section ol li>p,.rst-content .section ol li>p:last-child,.rst-content .section ul li>p,.rst-content .section ul li>p:last-child{margin-bottom:12px}.rst-content .section ol li>p:only-child,.rst-content .section ol li>p:only-child:last-child,.rst-content .section ul li>p:only-child,.rst-content .section ul li>p:only-child:last-child{margin-bottom:0}.rst-content .section ol li>ol,.rst-content .section ol li>ul,.rst-content .section ul li>ol,.rst-content .section ul li>ul{margin-bottom:12px}.rst-content .section ol.simple li>*,.rst-content .section ol.simple li ol,.rst-content .section ol.simple li ul,.rst-content .section ul.simple li>*,.rst-content .section ul.simple li ol,.rst-content .section ul.simple li ul{margin-top:0;margin-bottom:0}.rst-content .line-block{margin-left:0;margin-bottom:24px;line-height:24px}.rst-content .line-block .line-block{margin-left:24px;margin-bottom:0}.rst-content .topic-title{font-weight:700;margin-bottom:12px}.rst-content .toc-backref{color:#404040}.rst-content .align-right{float:right;margin:0 0 24px 24px}.rst-content .align-left{float:left;margin:0 24px 24px 0}.rst-content .align-center{margin:auto}.rst-content .align-center:not(table){display:block}.rst-content .code-block-caption .headerlink,.rst-content .toctree-wrapper>p.caption .headerlink,.rst-content dl dt .headerlink,.rst-content h1 .headerlink,.rst-content h2 .headerlink,.rst-content h3 .headerlink,.rst-content h4 .headerlink,.rst-content h5 .headerlink,.rst-content h6 .headerlink,.rst-content p.caption .headerlink,.rst-content table>caption .headerlink{visibility:hidden;font-size:14px}.rst-content .code-block-caption .headerlink:after,.rst-content .toctree-wrapper>p.caption .headerlink:after,.rst-content dl dt .headerlink:after,.rst-content h1 .headerlink:after,.rst-content h2 .headerlink:after,.rst-content h3 .headerlink:after,.rst-content h4 .headerlink:after,.rst-content h5 .headerlink:after,.rst-content h6 .headerlink:after,.rst-content p.caption .headerlink:after,.rst-content table>caption .headerlink:after{content:"\f0c1";font-family:FontAwesome}.rst-content .code-block-caption:hover .headerlink:after,.rst-content .toctree-wrapper>p.caption:hover .headerlink:after,.rst-content dl dt:hover .headerlink:after,.rst-content h1:hover .headerlink:after,.rst-content h2:hover .headerlink:after,.rst-content h3:hover .headerlink:after,.rst-content h4:hover .headerlink:after,.rst-content h5:hover .headerlink:after,.rst-content h6:hover .headerlink:after,.rst-content p.caption:hover .headerlink:after,.rst-content table>caption:hover .headerlink:after{visibility:visible}.rst-content table>caption .headerlink:after{font-size:12px}.rst-content .centered{text-align:center}.rst-content .sidebar{float:right;width:40%;display:block;margin:0 0 24px 24px;padding:24px;background:#f3f6f6;border:1px solid #e1e4e5}.rst-content .sidebar dl,.rst-content .sidebar p,.rst-content .sidebar ul{font-size:90%}.rst-content .sidebar .last,.rst-content .sidebar>:last-child{margin-bottom:0}.rst-content .sidebar .sidebar-title{display:block;font-family:Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif;font-weight:700;background:#e1e4e5;padding:6px 12px;margin:-24px -24px 24px;font-size:100%}.rst-content .highlighted{background:#f1c40f;box-shadow:0 0 0 2px #f1c40f;display:inline;font-weight:700}.rst-content .citation-reference,.rst-content .footnote-reference{vertical-align:baseline;position:relative;top:-.4em;line-height:0;font-size:90%}.rst-content .hlist{width:100%}html.writer-html4 .rst-content table.docutils.citation,html.writer-html4 .rst-content table.docutils.footnote{background:none;border:none}html.writer-html4 .rst-content table.docutils.citation td,html.writer-html4 .rst-content table.docutils.citation tr,html.writer-html4 .rst-content table.docutils.footnote td,html.writer-html4 .rst-content table.docutils.footnote tr{border:none;background-color:transparent!important;white-space:normal}html.writer-html4 .rst-content table.docutils.citation td.label,html.writer-html4 .rst-content table.docutils.footnote td.label{padding-left:0;padding-right:0;vertical-align:top}html.writer-html5 .rst-content dl dt span.classifier:before{content:" : "}html.writer-html5 .rst-content dl.field-list,html.writer-html5 .rst-content dl.footnote{display:grid;grid-template-columns:max-content auto}html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dt{padding-left:1rem}html.writer-html5 .rst-content dl.field-list>dt:after,html.writer-html5 .rst-content dl.footnote>dt:after{content:":"}html.writer-html5 .rst-content dl.field-list>dd,html.writer-html5 .rst-content dl.field-list>dt,html.writer-html5 .rst-content dl.footnote>dd,html.writer-html5 .rst-content dl.footnote>dt{margin-bottom:0}html.writer-html5 .rst-content dl.footnote{font-size:.9rem}html.writer-html5 .rst-content dl.footnote>dt{margin:0 .5rem .5rem 0;line-height:1.2rem;word-break:break-all;font-weight:400}html.writer-html5 .rst-content dl.footnote>dt>span.brackets{margin-right:.5rem}html.writer-html5 .rst-content dl.footnote>dt>span.brackets:before{content:"["}html.writer-html5 .rst-content dl.footnote>dt>span.brackets:after{content:"]"}html.writer-html5 .rst-content dl.footnote>dt>span.fn-backref{font-style:italic}html.writer-html5 .rst-content dl.footnote>dd{margin:0 0 .5rem;line-height:1.2rem}html.writer-html5 .rst-content dl.footnote>dd p,html.writer-html5 .rst-content dl.option-list kbd{font-size:.9rem}.rst-content table.docutils.footnote,html.writer-html4 .rst-content table.docutils.citation,html.writer-html5 .rst-content dl.footnote{color:grey}.rst-content table.docutils.footnote code,.rst-content table.docutils.footnote tt,html.writer-html4 .rst-content table.docutils.citation code,html.writer-html4 .rst-content table.docutils.citation tt,html.writer-html5 .rst-content dl.footnote code,html.writer-html5 .rst-content dl.footnote tt{color:#555}.rst-content .wy-table-responsive.citation,.rst-content .wy-table-responsive.footnote{margin-bottom:0}.rst-content .wy-table-responsive.citation+:not(.citation),.rst-content .wy-table-responsive.footnote+:not(.footnote){margin-top:24px}.rst-content .wy-table-responsive.citation:last-child,.rst-content .wy-table-responsive.footnote:last-child{margin-bottom:24px}.rst-content table.docutils th{border-color:#e1e4e5}html.writer-html5 .rst-content table.docutils th{border:1px solid #e1e4e5}html.writer-html5 .rst-content table.docutils td>p,html.writer-html5 .rst-content table.docutils th>p{line-height:1rem;margin-bottom:0;font-size:.9rem}.rst-content table.docutils td .last,.rst-content table.docutils td .last>:last-child{margin-bottom:0}.rst-content table.field-list,.rst-content table.field-list td{border:none}.rst-content table.field-list td p{font-size:inherit;line-height:inherit}.rst-content table.field-list td>strong{display:inline-block}.rst-content table.field-list .field-name{padding-right:10px;text-align:left;white-space:nowrap}.rst-content table.field-list .field-body{text-align:left}.rst-content code,.rst-content tt{color:#000;font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;padding:2px 5px}.rst-content code big,.rst-content code em,.rst-content tt big,.rst-content tt em{font-size:100%!important;line-height:normal}.rst-content code.literal,.rst-content tt.literal{color:#e74c3c;white-space:normal}.rst-content code.xref,.rst-content tt.xref,a .rst-content code,a .rst-content tt{font-weight:700;color:#404040}.rst-content kbd,.rst-content pre,.rst-content samp{font-family:SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace}.rst-content a code,.rst-content a tt{color:#2980b9}.rst-content dl{margin-bottom:24px}.rst-content dl dt{font-weight:700;margin-bottom:12px}.rst-content dl ol,.rst-content dl p,.rst-content dl table,.rst-content dl ul{margin-bottom:12px}.rst-content dl dd{margin:0 0 12px 24px;line-height:24px}html.writer-html4 .rst-content dl:not(.docutils),html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple){margin-bottom:24px}html.writer-html4 .rst-content dl:not(.docutils)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt{display:table;margin:6px 0;font-size:90%;line-height:normal;background:#e7f2fa;color:#2980b9;border-top:3px solid #6ab0de;padding:6px;position:relative}html.writer-html4 .rst-content dl:not(.docutils)>dt:before,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt:before{color:#6ab0de}html.writer-html4 .rst-content dl:not(.docutils)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.field-list)>dt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dl:not(.field-list)>dt{margin-bottom:6px;border:none;border-left:3px solid #ccc;background:#f0f0f0;color:#555}html.writer-html4 .rst-content dl:not(.docutils) dl:not(.field-list)>dt .headerlink,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) dl:not(.field-list)>dt .headerlink{color:#404040;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils)>dt:first-child,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt:first-child{margin-top:0}html.writer-html4 .rst-content dl:not(.docutils) code,html.writer-html4 .rst-content dl:not(.docutils) tt,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) code,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) tt{font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) code.descclassname,html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descclassname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) code.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) tt.descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) tt.descname{background-color:transparent;border:none;padding:0;font-size:100%!important}html.writer-html4 .rst-content dl:not(.docutils) code.descname,html.writer-html4 .rst-content dl:not(.docutils) tt.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) code.descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) tt.descname{font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .optional,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .optional{display:inline-block;padding:0 4px;color:#000;font-weight:700}html.writer-html4 .rst-content dl:not(.docutils) .property,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .property{display:inline-block;padding-right:8px}.rst-content .viewcode-back,.rst-content .viewcode-link{display:inline-block;color:#27ae60;font-size:80%;padding-left:24px}.rst-content .viewcode-back{display:block;float:right}.rst-content p.rubric{margin-bottom:12px;font-weight:700}.rst-content code.download,.rst-content tt.download{background:inherit;padding:inherit;font-weight:400;font-family:inherit;font-size:inherit;color:inherit;border:inherit;white-space:inherit}.rst-content code.download span:first-child,.rst-content tt.download span:first-child{-webkit-font-smoothing:subpixel-antialiased}.rst-content code.download span:first-child:before,.rst-content tt.download span:first-child:before{margin-right:4px}.rst-content .guilabel{border:1px solid #7fbbe3;background:#e7f2fa;font-size:80%;font-weight:700;border-radius:4px;padding:2.4px 6px;margin:auto 2px}.rst-content .versionmodified{font-style:italic}@media screen and (max-width:480px){.rst-content .sidebar{width:100%}}span[id*=MathJax-Span]{color:#404040}.math{text-align:center}@font-face{font-family:Lato;src:url(fonts/lato-normal.woff2?bd03a2cc277bbbc338d464e679fe9942) format("woff2"),url(fonts/lato-normal.woff?27bd77b9162d388cb8d4c4217c7c5e2a) format("woff");font-weight:400;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold.woff2?cccb897485813c7c256901dbca54ecf2) format("woff2"),url(fonts/lato-bold.woff?d878b6c29b10beca227e9eef4246111b) format("woff");font-weight:700;font-style:normal;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-bold-italic.woff2?0b6bb6725576b072c5d0b02ecdd1900d) format("woff2"),url(fonts/lato-bold-italic.woff?9c7e4e9eb485b4a121c760e61bc3707c) format("woff");font-weight:700;font-style:italic;font-display:block}@font-face{font-family:Lato;src:url(fonts/lato-normal-italic.woff2?4eb103b4d12be57cb1d040ed5e162e9d) format("woff2"),url(fonts/lato-normal-italic.woff?f28f2d6482446544ef1ea1ccc6dd5892) format("woff");font-weight:400;font-style:italic;font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:400;src:url(fonts/Roboto-Slab-Regular.woff2?7abf5b8d04d26a2cafea937019bca958) format("woff2"),url(fonts/Roboto-Slab-Regular.woff?c1be9284088d487c5e3ff0a10a92e58c) format("woff");font-display:block}@font-face{font-family:Roboto Slab;font-style:normal;font-weight:700;src:url(fonts/Roboto-Slab-Bold.woff2?9984f4a9bda09be08e83f2506954adbe) format("woff2"),url(fonts/Roboto-Slab-Bold.woff?bed5564a116b05148e3b3bea6fb1162a) format("woff");font-display:block}
\ No newline at end of file
diff --git a/_static/doctools.js b/_static/doctools.js
new file mode 100644
index 0000000000..8cbf1b161a
--- /dev/null
+++ b/_static/doctools.js
@@ -0,0 +1,323 @@
+/*
+ * doctools.js
+ * ~~~~~~~~~~~
+ *
+ * Sphinx JavaScript utilities for all documentation.
+ *
+ * :copyright: Copyright 2007-2021 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
+/**
+ * select a different prefix for underscore
+ */
+$u = _.noConflict();
+
+/**
+ * make the code below compatible with browsers without
+ * an installed firebug like debugger
+if (!window.console || !console.firebug) {
+ var names = ["log", "debug", "info", "warn", "error", "assert", "dir",
+ "dirxml", "group", "groupEnd", "time", "timeEnd", "count", "trace",
+ "profile", "profileEnd"];
+ window.console = {};
+ for (var i = 0; i < names.length; ++i)
+ window.console[names[i]] = function() {};
+}
+ */
+
+/**
+ * small helper function to urldecode strings
+ *
+ * See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/decodeURIComponent#Decoding_query_parameters_from_a_URL
+ */
+jQuery.urldecode = function(x) {
+ if (!x) {
+ return x
+ }
+ return decodeURIComponent(x.replace(/\+/g, ' '));
+};
+
+/**
+ * small helper function to urlencode strings
+ */
+jQuery.urlencode = encodeURIComponent;
+
+/**
+ * This function returns the parsed url parameters of the
+ * current request. Multiple values per key are supported,
+ * it will always return arrays of strings for the value parts.
+ */
+jQuery.getQueryParameters = function(s) {
+ if (typeof s === 'undefined')
+ s = document.location.search;
+ var parts = s.substr(s.indexOf('?') + 1).split('&');
+ var result = {};
+ for (var i = 0; i < parts.length; i++) {
+ var tmp = parts[i].split('=', 2);
+ var key = jQuery.urldecode(tmp[0]);
+ var value = jQuery.urldecode(tmp[1]);
+ if (key in result)
+ result[key].push(value);
+ else
+ result[key] = [value];
+ }
+ return result;
+};
+
+/**
+ * highlight a given string on a jquery object by wrapping it in
+ * span elements with the given class name.
+ */
+jQuery.fn.highlightText = function(text, className) {
+ function highlight(node, addItems) {
+ if (node.nodeType === 3) {
+ var val = node.nodeValue;
+ var pos = val.toLowerCase().indexOf(text);
+ if (pos >= 0 &&
+ !jQuery(node.parentNode).hasClass(className) &&
+ !jQuery(node.parentNode).hasClass("nohighlight")) {
+ var span;
+ var isInSVG = jQuery(node).closest("body, svg, foreignObject").is("svg");
+ if (isInSVG) {
+ span = document.createElementNS("http://www.w3.org/2000/svg", "tspan");
+ } else {
+ span = document.createElement("span");
+ span.className = className;
+ }
+ span.appendChild(document.createTextNode(val.substr(pos, text.length)));
+ node.parentNode.insertBefore(span, node.parentNode.insertBefore(
+ document.createTextNode(val.substr(pos + text.length)),
+ node.nextSibling));
+ node.nodeValue = val.substr(0, pos);
+ if (isInSVG) {
+ var rect = document.createElementNS("http://www.w3.org/2000/svg", "rect");
+ var bbox = node.parentElement.getBBox();
+ rect.x.baseVal.value = bbox.x;
+ rect.y.baseVal.value = bbox.y;
+ rect.width.baseVal.value = bbox.width;
+ rect.height.baseVal.value = bbox.height;
+ rect.setAttribute('class', className);
+ addItems.push({
+ "parent": node.parentNode,
+ "target": rect});
+ }
+ }
+ }
+ else if (!jQuery(node).is("button, select, textarea")) {
+ jQuery.each(node.childNodes, function() {
+ highlight(this, addItems);
+ });
+ }
+ }
+ var addItems = [];
+ var result = this.each(function() {
+ highlight(this, addItems);
+ });
+ for (var i = 0; i < addItems.length; ++i) {
+ jQuery(addItems[i].parent).before(addItems[i].target);
+ }
+ return result;
+};
+
+/*
+ * backward compatibility for jQuery.browser
+ * This will be supported until firefox bug is fixed.
+ */
+if (!jQuery.browser) {
+ jQuery.uaMatch = function(ua) {
+ ua = ua.toLowerCase();
+
+ var match = /(chrome)[ \/]([\w.]+)/.exec(ua) ||
+ /(webkit)[ \/]([\w.]+)/.exec(ua) ||
+ /(opera)(?:.*version|)[ \/]([\w.]+)/.exec(ua) ||
+ /(msie) ([\w.]+)/.exec(ua) ||
+ ua.indexOf("compatible") < 0 && /(mozilla)(?:.*? rv:([\w.]+)|)/.exec(ua) ||
+ [];
+
+ return {
+ browser: match[ 1 ] || "",
+ version: match[ 2 ] || "0"
+ };
+ };
+ jQuery.browser = {};
+ jQuery.browser[jQuery.uaMatch(navigator.userAgent).browser] = true;
+}
+
+/**
+ * Small JavaScript module for the documentation.
+ */
+var Documentation = {
+
+ init : function() {
+ this.fixFirefoxAnchorBug();
+ this.highlightSearchWords();
+ this.initIndexTable();
+ if (DOCUMENTATION_OPTIONS.NAVIGATION_WITH_KEYS) {
+ this.initOnKeyListeners();
+ }
+ },
+
+ /**
+ * i18n support
+ */
+ TRANSLATIONS : {},
+ PLURAL_EXPR : function(n) { return n === 1 ? 0 : 1; },
+ LOCALE : 'unknown',
+
+ // gettext and ngettext don't access this so that the functions
+ // can safely bound to a different name (_ = Documentation.gettext)
+ gettext : function(string) {
+ var translated = Documentation.TRANSLATIONS[string];
+ if (typeof translated === 'undefined')
+ return string;
+ return (typeof translated === 'string') ? translated : translated[0];
+ },
+
+ ngettext : function(singular, plural, n) {
+ var translated = Documentation.TRANSLATIONS[singular];
+ if (typeof translated === 'undefined')
+ return (n == 1) ? singular : plural;
+ return translated[Documentation.PLURALEXPR(n)];
+ },
+
+ addTranslations : function(catalog) {
+ for (var key in catalog.messages)
+ this.TRANSLATIONS[key] = catalog.messages[key];
+ this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')');
+ this.LOCALE = catalog.locale;
+ },
+
+ /**
+ * add context elements like header anchor links
+ */
+ addContextElements : function() {
+ $('div[id] > :header:first').each(function() {
+ $('\u00B6').
+ attr('href', '#' + this.id).
+ attr('title', _('Permalink to this headline')).
+ appendTo(this);
+ });
+ $('dt[id]').each(function() {
+ $('\u00B6').
+ attr('href', '#' + this.id).
+ attr('title', _('Permalink to this definition')).
+ appendTo(this);
+ });
+ },
+
+ /**
+ * workaround a firefox stupidity
+ * see: https://bugzilla.mozilla.org/show_bug.cgi?id=645075
+ */
+ fixFirefoxAnchorBug : function() {
+ if (document.location.hash && $.browser.mozilla)
+ window.setTimeout(function() {
+ document.location.href += '';
+ }, 10);
+ },
+
+ /**
+ * highlight the search words provided in the url in the text
+ */
+ highlightSearchWords : function() {
+ var params = $.getQueryParameters();
+ var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : [];
+ if (terms.length) {
+ var body = $('div.body');
+ if (!body.length) {
+ body = $('body');
+ }
+ window.setTimeout(function() {
+ $.each(terms, function() {
+ body.highlightText(this.toLowerCase(), 'highlighted');
+ });
+ }, 10);
+ $('
/*Copyright2009-2016EPFL,Lausanne*/
+
+import stainless.lang._
+
+object BraunTree {
+ abstractclass Tree
+ caseclass Node(value: Int, left: Tree, right: Tree) extends Tree
+ caseclass Leaf() extends Tree
+
+ definsert(tree: Tree, x: Int): Tree = {
+ require(isBraun(tree))
+ tree match {
+ caseNode(value, left, right) =>
+ Node(value, insert(left, x), right)
+ caseLeaf() =>Node(x, Leaf(), Leaf())
+ }
+ } ensuring { res =>isBraun(res) }
+// Counterexample for postcondition violation in `insert`:
+// when x is:
+// 0
+// when tree is:
+// Node(0, Node(0, Leaf(), Leaf()), Leaf())
+
+ defheight(tree: Tree): Int = {
+ tree match {
+ caseNode(value, left, right) =>
+ val l =height(left)
+ val r =height(right)
+ val max =if (l > r) l else r
+ 1 + max
+ caseLeaf() => 0
+ }
+ }
+
+ defisBraun(tree: Tree): Boolean = {
+ tree match {
+ caseNode(value, left, right) =>
+ isBraun(left) && isBraun(right) && {
+ val l =height(left)
+ val r =height(right)
+ l == r || l == r + 1
+ }
+ caseLeaf() =>true
+ }
+ }
+}
+
/*Copyright2009-2016EPFL,Lausanne*/
+
+import stainless.annotation._
+import stainless.lang._
+
+object Mean {
+
+ defmeanOverflow(x: Int, y: Int): Int = {
+ require(x <= y && x >= 0 && y >= 0)
+ (x + y)/2
+ } ensuring(m => m >= x && m <= y)
+// Counterexample for postcondition violation in `meanOverflow`:
+// when y is:
+// 1865154560
+// when x is:
+// 1277440000
+
+}
+
diff --git a/_static/invalid/SpecWithExtern.scala b/_static/invalid/SpecWithExtern.scala
new file mode 100644
index 0000000000..4480b715f1
--- /dev/null
+++ b/_static/invalid/SpecWithExtern.scala
@@ -0,0 +1,22 @@
+import stainless.annotation._
+
+object SpecWithExtern {
+
+
+ //random between returns any value between l and h.
+ //For execution via scalac, we pick one valid implementation, but
+ //we would like the program to be verified versus any possible
+ //implementation, which should happen thanks to @extern
+ @extern
+ def randomBetween(l: Int, h: Int): Int = {
+ require(l <= h)
+ l
+ } ensuring(res => (res >= l && res <= h))
+
+ //postcondition is wrong, but if stainless considers
+ //actual body of randomBetween it would be correct
+ def wrongProp(): Int = {
+ randomBetween(0, 10)
+ } ensuring(res => res >= 0 && res < 10)
+
+}
diff --git a/_static/jquery.js b/_static/jquery.js
new file mode 100644
index 0000000000..624bca829e
--- /dev/null
+++ b/_static/jquery.js
@@ -0,0 +1,10879 @@
+/*!
+ * jQuery JavaScript Library v3.6.0
+ * https://jquery.com/
+ *
+ * Includes Sizzle.js
+ * https://sizzlejs.com/
+ *
+ * Copyright OpenJS Foundation and other contributors
+ * Released under the MIT license
+ * https://jquery.org/license
+ */
+( function( global, factory ) {
+
+ "use strict";
+
+ if ( typeof module === "object" && typeof module.exports === "object" ) {
+
+ // For CommonJS and CommonJS-like environments where a proper `window`
+ // is present, execute the factory and get jQuery.
+ // For environments that do not have a `window` with a `document`
+ // (such as Node.js), expose a factory as module.exports.
+ // This accentuates the need for the creation of a real `window`.
+ // e.g. var jQuery = require("jquery")(window);
+ // See ticket #14549 for more info.
+ module.exports = global.document ?
+ factory( global, true ) :
+ function( w ) {
+ if ( !w.document ) {
+ throw new Error( "jQuery requires a window with a document" );
+ }
+ return factory( w );
+ };
+ } else {
+ factory( global );
+ }
+
+// Pass this if window is not defined yet
+} )( typeof window !== "undefined" ? window : this, function( window, noGlobal ) {
+
+// Edge <= 12 - 13+, Firefox <=18 - 45+, IE 10 - 11, Safari 5.1 - 9+, iOS 6 - 9.1
+// throw exceptions when non-strict code (e.g., ASP.NET 4.5) accesses strict mode
+// arguments.callee.caller (trac-13335). But as of jQuery 3.0 (2016), strict mode should be common
+// enough that all such attempts are guarded in a try block.
+"use strict";
+
+var arr = [];
+
+var getProto = Object.getPrototypeOf;
+
+var slice = arr.slice;
+
+var flat = arr.flat ? function( array ) {
+ return arr.flat.call( array );
+} : function( array ) {
+ return arr.concat.apply( [], array );
+};
+
+
+var push = arr.push;
+
+var indexOf = arr.indexOf;
+
+var class2type = {};
+
+var toString = class2type.toString;
+
+var hasOwn = class2type.hasOwnProperty;
+
+var fnToString = hasOwn.toString;
+
+var ObjectFunctionString = fnToString.call( Object );
+
+var support = {};
+
+var isFunction = function isFunction( obj ) {
+
+ // Support: Chrome <=57, Firefox <=52
+ // In some browsers, typeof returns "function" for HTML