DynarePython.md

@@ -5,7 +5,7 @@ The general goal of the project is to create a Python package that can
 - trigger the Dynare Preprocessor
 - apply Python algorithms to Python representation of a Dynare model
 - call Julia to leverage DynareJulia algorithms and recover results as Python objects
-- call Matlab/Octave to leverage Dynare Matlab/Octave algorithms and recover results as Python objects
+- call MATLAB/Octave to leverage Dynare MATLAB/Octave algorithms and recover results as Python objects
 
 ## Development tasks
 
@@ -13,19 +13,34 @@ The general goal of the project is to create a Python package that can
 
 Either
 
-- as \*.py file
-- calling the bytecode library generated by the preprosessor
+- as \*.py files
+- by interpreting the bytecode output
 
 #### \*.py files
 
+The Dynare preprocessor has a generic infrastructure for handling different output languages. Currently, it supports MATLAB/Octave, C and Julia. The idea is thus to add Python as a 4th output language, leveraging the existing infrastructure.
+
+In terms of calling interface, the preprocessor accepts a command-line option `language` whose value can be either `matlab` or `julia` (C output is subsumed in the `matlab` option value when used in combination with the `use_dll` option); this is handled in `DynareMain.cc`. A new `python` option value should be added (and the `LanguageOutputType` class enum in `ExtendedPreprocessorTypes.hh` should be expanded accordingly). Throughout the preprocessor code, the distinction between MATLAB/Octave and Julia is currently passed through a `bool julia` function argument in calling trees; this should probably be replaced by passing a `LanguageOutputType` value that covers the three languages.
+
+The engine for manipulating and outputting symbolic algebraic expressions is located in `ExprNode.hh` and `ExprNode.cc`. In particular, there is a generic framework for outputting expressions in various contexts, depending on the programming language (MATLAB/Octave, C, Julia) and in the type of expression (dynamic expression with leads and lags, static expression, time series…), as reflected in the `ExprNodeOutputType`. For Python, the following values should be added:
+- `pythonDynamicModel` (for outputting the dynamic model)
+- `pythonStaticModel` (for outputting the static model)
+- `pythonDynamicSteadyStateOperator` (used inside a `STEADY_STATE` operator within a dynamic model)
+- `pythonSteadyStateFile` (for writing the contents of the `steady_state_model` block)
+- and maybe some type for writing time series in some native Python object (similar to `matlabDseries` and `juliaTimeDataFrame`)
+Once these new enums are in place, they should be handled throughout the expression writing engine, in particular:
+- within the helpers `isSteadyStateOperatorOutput()`, `isSparseModelOutput()` (should always return `true` for Python), `ARRAY_SUBSCRIPT_OFFSET()` (array indexing is 0-based in Python); a new `isPythonOutput()` helper should also be created; NB: `LEFT_ARRAY_SUBSCRIPT()` and `RIGHT_ARRAY_SUBSCRIPT()` need no adjustment since Python uses brackets for array-indexing;
+- in the `writeOutput()` methods of the various classes, so as to write use the correct objects and mathematical function names for the Python context
+- maybe also adapt the `cost()` methods
+
+
+
+
 - Adapt the Julia specific code for Python in
   * `ModelTree.hh`
   * `DynamicModel.cc` and `DynamicModel.hh`
   * `StaticModel.cc` and `StaticModel.hh`
-  * `ExtendedPreprocessorTypes.hh`
-  * `ExprNode.hh`
   * `ModelEquationBlock.cc` and `ModelEquationsBlock.hh`
-  * add language Python as language option in `DynareMain.cc` (see Julia option)
   * the main differences between Python code and Julia code relevant here are
     - `def` instead of `function`
     - array indexing starts with 0 instead of 1