Differential Specification Syntax Key

The differential specification is effectively described through a system modeling syntax. The symbols referenced in the differential specification diagram are described here. Note that all information flows described are feed-forward, feedback of state to any process is implicit. Furthermore, the differential specification is laid on a grid where the rows are:

  • The Policies determine the inputs to the system dynamics regardless of whether they come from the outside environment, user behavior or algorithmic decision systems.

  • The State Update Logic determines how the state of the system changes as a result of the inputs provided. Note that not all outcomes are the outcomes intended by the actor (system or agent) when the input decision was made due to the interdependence of these inputs.

  • The State is flattened and summarized in order to keep track of the the interdependence of the mechanisms on the same state variables. Note that the full data model for the state space is generally a network object for which the shown states are mid-level aggregates or summary statistics.

  • The Metrics are values computed from the state variables in order to assess the economic system. In a computational model, metrics may be used for governance decisions, algorithmic policies or to inform the behavior of individual agents.

The columns in a differential specification refer to the Partial State Update Block also called substeps, which break the logic up into an ordered sequence in order to support second order dependencies. For example, there may be a set of user behavior functions that resolve a decision to participate and incur some costs, and then a set of environmental process drivers that determine the rewards those participants receive as a result of all of their decisions and the events which transpire there after. A simple differential specification will have one or two substeps, whereas a complex economic system could have 8 to 10 substeps.

  • Information Flow: Any data structure may be used to convey state update execution. The expected path is from actions, policies, and processes to mechanisms to states variables to metrics.

  • Environmental Process Driver: Data feed that informs an exogenous process. This may be real or assumed data to provide updated input for a model representing a change of external conditions.

  • User Behavior Function: A population or agent-based strategy developed using information gathered from available state variables, metrics, external factors, internal beliefs, and utility functions. The action space available to achieve the strategy is executed through the mechanisms. No action may be fulfillment of the strategy. The user behavior/action should not directly be a state variable.

  • Control Function: The controllable action space under the controlling entity. May be actively controlled through a strategy developed using information gathered from available publicly and privately known state variables, metrics, external factors, internal beliefs, and utility functions. The action space available to achieve the strategy is executed through the mechanisms. Passive control (no action) may correctly model this behavior. Policy functions should not directly modify a state variable, but may affect any parameters in a mechanism as well as the availability of a mechanism.

  • Environmental Process Model: A modelled generator providing an update to state variables using external input signals from an environmental process driver. User action behavior and control functions should not affect this model. The affected state variables should be purely exogenously based, but may be blended from the internal state if necessary to model the system. The exogenous state variables are the link between the changes from the outside world germane to the modeled system, and provides the information necessary for users and controllers to make decisions.

  • Mechanism: System defined functions that take user actions and control policy input to update a set of state variables. Mechanism functions may be logically or operationally grouped to be executed concurrently as a partial state update.

  • State Variable: Defined to capture the shape and property of the network, representing publicly or privately held output of the system. The updates to the information can only come through mechanisms and exogenous models and not user or control actions. The data may be updated repeatedly within a simulated step. The resolution of all partial updates is the state update.

  • *Performance Indicator: Metrics calculated from a subset of state variables. The indicator may represent actual publicly or privately available data. The metric could also be a computed signal from the state used to determine the condition of a control policy. Also, this may be an expected indicator employed by users to execute on their strategy. Care must be taken to update the metric after the input state variable(s) are updated as to obtain the correct result within a state update.

Here is a stylized example of a differential specification for a generic service economy with minted rewards:


a tid bit misleading still the “System Decision”, b/c system is the entirety; If you don’t want to call these policies; why not call them “smart rules” or similar; as this is basically the part that is hard-wired coded transactional logic of the ecosystem, correct?

or “Programmed Decisions”

That’s a good point. The reason we refer to them as system policies is that our reference cases for these kinds of things mining rewards policies or the difficulty controller in bitcoin. These essential algorithms that define system level properties. They need not be “system level” but they do need to be under the control of the system designer, as opposed to being under the control of participants. Interestingly, they may not always be “programmed decisions” we’ve had cases with clients where these policies are “wet coded” meaning they still represent a predefined operational policy being implemented by a business unit.

Definitely room here to understand how to represent these kinds of logics that fall in the middle of the decision making spectrum:

Generally low level protocols appear in the green ovals but algorithmic policies are green boxes and discretionary policies can fall in pink diamonds or green pentagons depending on the context.


This post was really useful. I’m still a bit vague on the overall process. From what I gather it’s something along the lines of:

  1. Requirements gathering
  2. Differential specification
  3. Deciding on and modelling agent behaviour?
  4. Producing partial differential equations to describe the system?
  5. Coding the cadCAD model.

Do I have that roughly right?


Would add “Stock & flow diagram” in between 1. and 2. unless, you included it as part of your req. gathering step. Agents, and their behavior would be also input to your stock & flow diagram. I like the step I borrowed from Ville (he borrowed it from Platform design toolkit) where you create a matrix of your systems agents, to show who offers/needs what from whom when. And take that as the input spec for your stock & flow diagram.

Really looking forward to the next 2 weeks, starting with tonight, putting up more material for the Diffusion2019 TE track!

  1. Requirements gathering (interviews/workshops with domain experts)
  2. System overview (System Purpose/Goal, Agents, Motivations/Value-adds/Needs, System Needs)
  3. Stock & Flow diagram (e.g. https://community.cadcad.org/uploads/default/original/1X/a1d10c2c09d4d4c5403d8eb1908fe33802bbaad2.jpeg)
  4. Differential Specification (Differential Specification Syntax Key)
  5. Producing differential equations to describe system dynamics (will depend on aspects picked for modeling)
  6. Coding

This is awesome thanks Sebnam!

Do you have an example of the Platform Design Toolkit matrix?

Is there something similar to the Differential Specification Key for the Stock and Flow diagrams? The ones we seem to use look quite different from the diagrams used in the “Thinking in systems” book Donella Meadoews.

I’m trying to pull all this info together in a template google doc as well as diagram templates so it’s easier for the next group of people coming in.

1 Like

This is what I have so far:
Google Doc
Miro Board


Can’t wait! It would be awesome to flesh out the “cadCAD modelling process” doc along side doing the actual models for the TE hackathon.

1 Like

Does the diagram need an update - wrt course materials? https://www.cadcad.education/course/bootcamp

1 Like

Started a Figma version of the cadCAD differential specification syntax key. Anyone should be able to view the page and copypasta all the things.

The goal is to create a template so that when you want to create a differential specification you can do so quickly and easily. Figma was chosen because (at the time of writing) it’s free for everyone to use. It’s also used by a lot of designers. This has the potential to close the gap between engineering and community engagement by making it easier to turn cadCAD diagrams into educational or promotional content. Time will tell…

Anyways, to start this is just a copy of the current cadCAD differential specification syntax key started this thread. Please fork it, update and add stuff, and when you do share your work here so that others can benefit!

1 Like