Tuesday, December 13, 2016

Introduction To The Python SFC Models Package

The sfc_models models Python package is designed to allow users to be able to build stock-flow consistent (SFC) economic models in a streamlined fashion. The approach is distinctive because it relies on algorithms to generate the model equations; the user only needs to set up the high level description of the sectors of the economy using existing building blocks. The advantage is that this makes it easy to experiment with different configurations, while still having a model that respects accounting conventions.

This article is not attempting to be a user guide, rather an introduction to the basic concepts used. This is because it would be premature to write a user guide.

At the time of the writing of the initial draft, the production branch is at version 0.2.1, while the development branch has some important new features which are not yet in the production branch. The low version number is a clue that this is viewed as something resembling an "alpha" release. Once the core modelling functions are proven to work, the class interfaces will probably be cleaned up, with inconsistencies in naming conventions removed. Such a renaming of functions ("refactoring") is easily done with modern development tools, but it means that user documentation would become out-of-date very rapidly.

What are SFC Models?

My assumption is that most of the readers here are aware what SFC models are; for those less familiar with them, I have a primer on this page, which also has links to further resources.

To quickly summarise, SFC models are used within the post-Keynesian economics community to build models. Within the academic community, the usual method to solve these models was to implement them in the Eviews programming environment, although there has been other developments in R and even Python. (I discuss some of those other packages in the sfc_models documentation.)

One of the best sources for information on SFC models is sfc-models.net.

Why Python? Why sfc_models?

It would have been possible to build a similar package in other languages, but Python has a few main advantages.

  1. It is open source, unlike Eviews (or Matlab).
  2. I find that the programming tools available for Python are superior to those available for the main open source competitor, R. (That assessment may reflect my greater experience with Python, but it also reflects the reality that Python was developed by programmers in order to make programming more efficient, while R was mainly developed by academics in statistical sciences.)
  3. In particular, the object-oriented programming in Python is extremely clean and powerful.
The last point -- about object-oriented programming -- may appear to be programming jargon, but it is critical. In object-oriented programming, we fuse together data structures the related code into objects, and the language is built around the interactions of those objects.

In practice, this makes it possible to create a variant of an existing model of a sector, and extend it to add new functionality by just creating a child object (a subclass). This typically can be done with just a few new lines of code. Furthermore, the new class can substitute for the old one in new models, without breaking existing code.

User Workflow

To create a new SFC model, the user would follow the steps below.
  • If necessary, create new models for sectors of the economy with new functionality.
  • Create a model object.
  • Within the model object, we then create one or more countries. (A closed economy model would have just one country, an open economy model at least two.)
  • For each country, create the various sectors. As we create each sector, we set behavioural parameter values.
  • We add in interconnections between sectors: the labour market, product markets, tax flows.
  • Once all interconnections are defined, we invoke a method on the main model object that causes it to create all of the equations defining the system.
  • The system of equations is put into a multi-line string, which is saved in a log file, and also sen to a solver program,
  • The solver program will simulate the system of equations. If the model is badly specified, the solver will not converge to a solution.
  • The output is saved as Python variables, and also dumped into a text file (csv). The user can then use a spreadsheet program to see the time series of all variables in the model.
The advantage of this workflow is that the user does not attempt to write down all of the equations by hand. Since the equations are generated by algorithms, it is easy to make a change to the model structure without having to redo all of the algebra. However, since the equations and output are available for manual inspection, the system is not just a numerical black box.


The system defines all variables of interest, even redundant variables where the two are defined to be equal to each other.  As a result, the number of equations generated for even a simple system are quite large. This makes it somewhat harder to debug the output, but it also makes it clear that no variables are being ignored.

The solver uses some basic rules to reduce the number of variables before starting to compute the equation, so the over-determination of the system has so far not been an issue.

The variable names can be quite long, and follow the convention:

{country code}_{sector code}_{variable code}.

For example, the code uses a convention that the market value of financial asset holdings has the variable code "F". Therefore, if we are looking at a country (Canada) with country code "CA", and the household sector has code "HH", the household sector financial holdings is the variable "CA_HH_F".

  • If the model has only one country, the country code is omitted. In this case, the household financial assets would be the variable HH_F.
  • Some variable codes are broken down further. For example, DEM_LAB is the demand for labour, while SUP_LAB is the supply of labour. Therefore, the Canadian household sector supply of labour would be CA_HH_SUP_LAB.
No attempt has been made to match variables to standard economist symbols. Such matching could be done in a second pass through the model. Since it is possible to split up standard sectors into multiple subsector objects, matching up variables to standard national accounting definitions would have to be determined once the entire system of sectors is defined.


The present means of solving the system of equations is via a brute force iterative procedure. It has worked on the simple classes of systems studied so far, but there is little reason to expect it to always find the solution.

The implementation uses computer-generated code, and can only be described as baroque. I love computer-generated code, but I have now thought of a more straightforward solution.

Future Steps

The main objective is to be able to implement the main models of Godley and Lavoie's classic text, Monetary Economics. Once that is possible, it is arguable that the framework can then be adapted to take on whatever is needed for future research.

Other steps to be taken:
  • Integration with R.
  • A more straightforward implementation of the iterative solver.
  • Finding a more powerful solution technique.
  • User documentation.

Robustness and Ease of Collaboration

The sfc_models package is an open source project, under the Apache 2.0 license. The author welcomes collaboration, but does not expect it until the package has added more features. The source code is on Github, and uses the powerful git source control system for collaboration.

The documentation at this point is minimal, under the theory that there is no point in documenting something that will radically change. Once it is clear that the core functionality is stable, the interfaces will be made more uniform, and easier to document.

The master branch of the code is being held to a 100% unit test coverage standard (although some code is inherently non-testable and is marked to be ignored in the test coverage statistic). Since all code is covered by unit tests, the expectation is that it will be easy to make changes to the code base without breaking any functionality. That is, the package will always do what it says it supposed to do.

Why Develop This Package?

I will be writing a book "Introduction to SFC Models in Python." Needless to say, the sfc_models package is the core of the book. Readers who are interested in applying the techniques to current economic research topics can then attempt to extend the framework beyond what I cover in my book.

(c) Brian Romanchuk 2016

No comments:

Post a Comment