Improved README.

README.md

@@ -146,35 +146,32 @@ difference from maximisation ("Max").
 ```
 
 Please note, these default semantics can be substituted
-using the `dsl_classes` arg of `calc()` (see below).
+using the `dsl_classes` arg of `calc()` below.
 
 
 ### Software
 
-The work of a quantitative analyst involves modelling optionality,
-calibrating a stochastic process for the underlyings, simulating future prices,
-and evaluating the model against the simulation.
-
-In implementing the semantics and syntax, this software provides an
-application object class  `QuantDslApplication` which has methods that
-support this work: `compile()`, `simulate()` and `evaluate()`.
+The scope of the work of a quantitative analyst involves modelling optionality,
+simulating future prices, and evaluating the model against the simulation. In
+implementing the syntax and semantics of Quant DSL, this software provides an
+application object class `QuantDslApplication` which has methods that support
+this work: `compile()`, `simulate()` and `evaluate()`.
 
 In addition to the Quant DSL expressions above, function `def`
 statements are supported. User defined functions can be used
 to refactor complex or extensive Quant DSL expressions, to model complex
-optionality concisely.
-
-The `import` statement is also supported, to allow Quant DSL function 
-definitions and expressions to be used and maintained in a library as
-normal Python code, allowing Python IDEs to be used to write, navigate,
-and refactor Quant DSL source code.
-
-During compilation of Quant DSL source code, the application `QuantDslApplication` constructs a
-dependency graph of Quant DSL expressions. The simulation is generated by a calibrated price process,
-according to requirements derived from the compiled dependency graph. During evaluation, the nodes of
-the dependency graph are evaluated when they are ready to be evaluated, and intermediate call results
+optionality concisely. The `import` statement is also supported, so Quant
+DSL function definitions and expressions to be developed and maintained as
+Python files. Since Quant DSL syntax is a strict subset of Python, the
+full power of Python IDEs can be used to write, navigate and refactor
+Quant DSL source code.
+
+During *compilation* of Quant DSL source code, the application `QuantDslApplication` constructs a
+graph of Quant DSL expressions. The *simulation* is generated by a calibrated price process,
+according to requirements derived from the compiled dependency graph. During *evaluation*, the nodes of
+the dependency graph are evaluated when they are ready to be evaluated. Intermediate results
 are discarded as soon as they are no longer required, such that memory usage is mostly constant during
-evaluation. For the delta calculations, nodes are selectively re-evaluated with perturbed values,
+evaluation. For the "greeks", nodes are selectively re-evaluated with perturbed values,
 according to the periods and markets they involve, avoiding unnecessary computation.
 
 
@@ -183,7 +180,7 @@ according to the periods and markets they involve, avoiding unnecessary computat
 ### calc()
 
 The examples below use the library function `calc()` to evaluate Quant DSL source code. `calc()` uses the
-methods of the `QuantDslApplication` described above.
+methods of the `QuantDslApplication` mentioned above.
 
 ```python
 from quantdsl.interfaces.calcandplot import calc
@@ -269,6 +266,10 @@ present time (`t` in the semantics above) when the element is evaluated.
 <Settlement> ::= "Settlement(" <Date> ", " <Expression> ")"
 ```
 
+```
+[[Settlement(d, x)]](t) = e ** (r * (t−d)) * [[x]](t)
+```
+
 For example, with a continuously compounding `interest_rate` of `2.5` percent per year, the value `10` settled on 
 `'2111-1-1'` has a present value of `82.08` on `'2011-1-1'`.
 
@@ -307,6 +308,10 @@ The `Fixing` element simply conditions the effective present time of its include
 <Fixing> ::= "Fixing(" <Date> "," <Expression> ")"
 ```
 
+```
+[[Fixing(d, x)]](t) = [[x]](d)
+```
+
 For example, if a `Fixing` element includes a `Settlement` element, then the effective present time of the 
 included `Settlement` element will be the given date of the `Fixing`.
 
@@ -330,6 +335,10 @@ The `Market` element effectively estimates prices that could be agreed in the fu
 <Market> ::= "Market(" <MarketName> ")"
 ```
 
+```
+[[Market(i)]](t) = Si * e ** (σi * z(t − t0)) − 0.5 * σi ** 2 * (t − t0)
+```
+
 When a `Market` element is evaluated, it returns a random variable selected from a simulation
  of market prices.
 
@@ -491,6 +500,10 @@ effective present time when evaluating the `Wait` element.
 <Wait> ::= "Wait(" <Date> "," <Expression> ")"
 ```
 
+```
+[[Wait(d, x)]](t) = [[Settlement(d, Fixing(d, x))]](t)
+```
+
 For example, the present value at the `observation_date` of `'2011-1-1'` of one unit of `'GAS'` delivered on 
 `'2111-1-1'` is approximately `82.18`. The `Wait` element sets the delivery date of the `Market` element,
  which is used to pick the value `1000` from the forward curve. The `Wait` element also sets the fixing date
@@ -515,11 +528,13 @@ assert round(results.fair_value.std(), 2) == 16.46
 
 ### Choice
 
-The `Choice` element uses the least-squares Monte Carlo approach proposed by Longstaff and 
-Schwartz (1998) to compare the conditional expected value of each alternative `Expression`.
+The `Choice` element uses the least-squares Monte Carlo approach (Longstaff
+Schwartz, 1998) to compare the conditional expected value of each alternative `Expression`.
 
 ```
 <Choice> ::= "Choice(" <Expression> "," <Expression> ")"
+
+[[Choice(x, y)]](t) = max(E[[[x]](t) | F(t)], E[[[y]](t) | F(t)])
 ```
 
 For example, the value of the choice at `observation_date` of `'2011-1-1'` between one unit of `'GAS'` either on 
@@ -541,6 +556,16 @@ results = calc(source_code,
 assert round(results.fair_value.mean(), 2) == 82.06, round(results.fair_value.mean(), 2)
 ```
 
+When the `Choice` element is evaluated, the value of each alternative is
+regressed as a random variable by least squares to the simulated value of the underlyings
+at the effective present time of the choice. The choice of alternative on each path is then
+made using the regressed value (the "conditional expected value") but the chosen
+value on each path is taken from the unregressed value of the chosen alternative for that path
+(the "expected continuation value"). The result is a new simulated value that combines the
+expected continuation value of the alternatives, according to information in the simulation
+at the time of the choice. This conditioning gives a quantitatively different result from simple
+maximisation of the alternative expected continuation values (`Max`). 
+
 ### Functions definitions
 
 Quant DSL source code can include function definitions. Expressions can involve calls to functions.