Version 0.4 Of sfc_models Released

The sfc_models package (available at GitHub) is now in the "beta" phase, at version 0.4.1 (The first production release will 1.0.) This version involved a fairly hefty code cleanup, and the programming interface underwent a lot of changes. This was expected, and which is why previous versions were labelled as "alpha." Now that the library is in beta, the objective is to avoid making any changes that will break existing code. Even if there is a cleaner way to do things, the old interface will be supported.

Update Version 0.4.0 was packaged incorrectly; it will have to be replaced with Version 0.4.1. (Oops.) The replacement should be up by 5 pm EST on 2017-03-06.

I am attaching some of the documentation describing the update, and the "Road to Version 1.0."

Road To Version 1.0

Another text file "RoadToVersion1.rst" describes the functionality that is aimed to be incorporated in Version 1.0 of sfc_models. [Attached below.]

Version 0.4.0 is being released on 2017-03-06. This version involves a major refactoring of the code, and has changed behaviour.

• The framework now injects a double underscore ('__') instead of a single one ('_') between the sector FullCode and the local variable name. For example, the household financial assets are now 'HH__F' instead of 'HH_F'. Furthermore, the creation of local variables with '__' is blocked. This means that the presence of '__' in a variable name means that it is the full name of a variable; otherwise it is a local variable. (Or perhaps a global variable like 't'.)
• An Equation class was created. It has replaced the strings held in the Equations member of the Sector class. It allows us to add terms to equations, so that the financial assets and income equations (see below) are always well-defined. This Equation class should be used by the solver, but it is not yet incorporated; there is no guarantee that such a change will be done before version 1.0 release.
• A pre-tax income variable ('INC') was created. It is normally equal to cash inflows minus outflows, but there are some exceptions. (Household consumption, business dividends, etc.) The sectors in the framework do their best to classify cash flows as whether they affect income, but users may need to create exceptions (or additions) manually. (Previously, the income was ad hoc.)
• A new module - sfc_models.sector was created; it pulled the Sector class out of the models module. The existing sectors.py was renamed to sector_definitions.py. My old example code that did "import **" from sfc_models.models no longer works. (?)

There are no major refactorings now expected to take place before version 1.0 release. As a result, the project status will be changed to 'beta' in Version 0.4. Methods that are not expected to be used by people who are not creating new classes will have '_' added in front of their name (so they disappear from help()), but this is viewed as acceptable. Otherwise, variables and methods will only be renamed if they are obviously not following a standard pattern.

Road To Version 1.0

Introduction

This document outlines what is expected to be implemented for Version 1.0 of sfc_models. This version is what will be described in the (first edition) of Introduction to SFC Models Using Python (by Brian Romanchuk). It seems likely that the sfc_models will evolve considerably as it used by others, but this Version 1.0 will act as a base implementation that matches the book documentation.

There will be a "book" branch created for the source code. In this book branch, functionality will be frozen to match what is within the book. User code developed against the code in this branch will see a frozen sfc_models API. The only developments that might occur may be an improvement of documentation and examples. This code may be released as versions 1.0.x; e.g., 1.0.3 is the third update on the book branch.

This document outlines the economic functionality that will be added, and then the code functionality. The list of features to be added is viewed as frozen; ideas that may be useful for the future will be added to the TODO document, but development will occur in versions 1.1 and later.

Economic Functionality

The following models from Monetary Economics (Godley and Lavoie) are hoped to be implemented.

• Model REG from Chapter 6. [DONE]
• Model REG2 = Model REG with sectors in two Country objects.
• Model OPEN from Chapter 6.
• Model DIS from Chapter 9.
• Possibly: Model DISINF from Chapter 9.
• Possibly: Model INSOUT from Chapter 10.

Furthermore, a SFC model from the literature may be implemented.

The implementation of these models will require more work on international models (Model OPEN) and prices and inventories (DIS, DISINF).

Code Cleanup

The following are the areas of code that will be examined.

• Logging will be back-filled throughout the code base. The user should be able to see what is happening by looking at the log. [Started.]
• An Equation class may be added. Previously, equations were just lists of strings (str). Only limited functionality is expected to be embedded in Version 1.0; the main feature is ensure that the user operations are safe. [DONE]
• Methods that are viewed as "private" will be renamed with "_" in their names; they will not show up in help [Started.]
• Refactoring to ensure greater consistency of naming and parameter usage.
• Allow users to define functions to be used within equations. [DONE]
• Example scripts will either be updated or moved to the "deprecated" folder. [DONE]

Documentation

The main documentation work will revolve around adding doc strings to all methods. Example scripts are expected to provide more context. Of course, there will be a book available for sale explaining the high level working of the library.

The book will include a technical description of the solver, as well as an explanation of the object hierarchy.

Excerpts of the book will be placed on the BondEconomics blog (http://bondeconomics.com ), and may be incorporated within the documentation base.

Since it is expected that the library will evolve once others start to use it, placing too much high level documentation within the library early on may be counter-productive. The book is aimed to work against the fixed Version 1.0 of the code base, but the library documentation needs to be compatible with Versions 2.0, etc.

(c) Brian Romanchuk 2017