[Refactor] Add a lower-level IR for C++ code generation

README.md

@@ -88,7 +88,7 @@ flowchart TB
 1. Analyze & optimize (MIR -> MIR)
 1. Code generation  (MIR -> [C++](src/stan_math_backend/Stan_math_code_gen.ml)) (or other outputs, like [Tensorflow](https://github.com/stan-dev/stan2tfp/)).
 
-### The two central data structures
+### The central data structures
 
 1. `src/frontend/Ast.ml` defines the AST. The AST is intended to have a direct 1-1 mapping with the syntax, so there are things like parentheses being kept around.
 The pretty-printer in the frontend uses the AST and attempts to keep user syntax the same while just adjusting whitespace.
@@ -97,10 +97,16 @@ The pretty-printer in the frontend uses the AST and attempts to keep user syntax
 
     The AST intends to keep very close to Stan-level semantics and syntax in every way.
 
-2. `src/middle/Program.ml` contains the MIR (Middle Intermediate Language - we're saving room at the bottom for later). `src/frontend/Ast_to_Mir.ml` performs the lowering and attempts to strip out as much Stan-specific semantics and syntax as possible, though this is still something of a work-in-progress.
+2. `src/middle/Program.ml` contains the MIR (Middle Intermediate Language). `src/frontend/Ast_to_Mir.ml` performs the lowering and attempts to strip out as much Stan-specific semantics and syntax as possible, though this is still something of a work-in-progress.
 
     The MIR uses the same two-level types idea to add metadata, notably expression types and autodiff levels as well as locations on many things. The MIR is used as the output data type from the frontend and the input for dataflow analysis, optimization (which also outputs MIR), and code generation.
 
+
+3. `src/stan_math_backend/Cpp.ml` defines a minimal representation of C++ used in code generation.
+
+    This is intentionally simpler than both the above structures and than a true C++ AST and is tailored pretty specifically
+    to the C++ generated in our model class.
+
 ## Design goals
 * **Multiple phases** - each with human-readable intermediate representations for easy debugging and optimization design.
 * **Optimizing** - takes advantage of info known at the Stan language level. Minimize information we must teach users for them to write performant code.

docs/cpp_ir.mld

@@ -0,0 +1,43 @@
+{0 C++ Code Generation}
+
+The main backend of the compiler is the "Stan Math" (C++) backend.
+We represent C++ code with a data types and functions found in
+{!module-Stan_math_backend.Cpp}.
+
+We also define a sort of miniature embedded domain specific language (DSL)
+for using these types. These helper functions and operators are all in sub-modules
+of {!module-Stan_math_backend.Cpp}, for example {!module-Stan_math_backend.Cpp.Expression_syntax}.
+
+These allow writing OCaml code which looks or feels more like the C++ it will generate. These
+constructs should be used when they improve clarity, and avoided when they make the code harder to
+read. When combined with good variable names, this can lead to code like
+[ lp_accum__.@?(("add", [Var "lp__"])) ], which hopefully reads quite clearly as equivalent to
+the C++ [lp_accum__.add(lp__)].
+
+
+After a Stan program is lowered to this type, it can be printed to C++ using
+{!module-Stan_math_backend.Cpp.Printing}. This module uses [Fmt], but keeps
+the question of how C++ should be formatted separate from the question of what
+the generated C++ {e is}.
+
+
+{1 DSL Example}
+For example, lets say one wanted to generate the expression
+{[
+(Eigen::Matrix<double,1,-1>(3) << 1, a, 3).finished()
+]}
+
+This could be written down as the literal OCaml type it is:
+{[
+(MethodCall (Parens (StreamInsertion (Constructor (Matrix (Double, 1, -1), [Literal "3"]), [Literal "1"; Var "a"; Literal "3"]), "finished", [], [])
+]}
+
+Or, using the DSL constructs, the same expression could be written
+
+{[
+let open Expression_syntax in
+let open Types in
+let vector = Constructor (row_vector Double, [Literal "3"]) in
+let values = [Literal "1"; Var "a"; Literal "3"] in
+(vector << values).@!("finished")
+]}

docs/index.mld

@@ -28,7 +28,10 @@ to a new developer.
 
 - {{!page-exposing_new_functions}
   Page on exposing a new function of the Stan Math library}
-
+
+- {{!page-cpp_ir}
+  Page on how we implement C++ code generation with a structured type and mini-DSL}
+
 - {{:https://github.com/stan-dev/stanc3/wiki/Software-Engineering-best-practices}
   Wiki on generic software best practices}