Network Specification

oguerrer edited this page May 28, 2015 · 5 revisions

This page documents how networks can be formally specified using JSON objects.

Before defining the specification format, let us first review some basic conventions.

We use the following abbreviations:

  • BOOL means either the constant false or true;
  • NUM is any natural number;
  • PROB means a real number between 0 and 1. Both decimal (e.g. 0.387)and scientific (e.g. 38.7E-2) notations are accepted;
  • ID means a string, delimited using double quotes as for instance "Hi I am a string!". A string can contain any UNICODE character. Be aware that \ acts as an escape character.

In JSON, a list of items is expressed with square brackets and commas, i.e. [ITEM1, ITEM2, ... , ITEMn]. For instance, the following is a list of three strings: ["labor", "flows", "rocks"]. Items can be any JSON value (even lists themselves).

A JSON object is similar to a record in C or a dict literal in Python. It consists of a collection of fields, each associated to a JSON value (which in turn can be a JSON object or list, etc). The syntax uses curly braces: { "labor": VAL1, "flows": VAL2 } defines an object with two fields named labor and flows. Note that:

  • a field name is specified using the string syntax
  • the order of appearance of the fields is irrelevant
  • there cannot be two fields with the same name in the same object

Also note that white-space can be used quite liberally and its judicious use can improve readability of the specification.

Network specifications

A network specification consists of a JSON object of the form

{
  "isHiringProb": PROB,
  "firms": FIRMS_SPECS,
  "links": LINKS_SPECS,
  "firm_default": FIRM_SPEC,
  "worker_default": WORKER_SPEC
}

Of these fields, none is mandatory; when they are omitted, default values are used (see Defaults for more info).

Hiring probability

The parameter isHiringProb can be set to a real number representing the probability that a firm is hiring. It defaults to 0.5 (50%).

Firm specification

The value of the firms field has the following shape:

{
  ID1: FIRM_SPEC,
  ID2: FIRM_SPEC,
  ...
  IDn: FIRM_SPEC,
}

where each ID1...IDn is a string representing the unique identifier associated with each firm.

A FIRM_SPEC is an object of the form:

{
  "hireProb": PROB,
  "fireProb": PROB,
  "isHiring": BOOL,
  "color": COLOR,
  "neighbors": [ID1, ..., IDk],
  "workers": WORKER_SPEC
}

If omitted, the first four parameters are inherited from the firm_default field of the network specification. When neighbors or workers are omitted, they are assumed to be the empty list.

The isHiring parameter specifies the initial state of the firm.

The color field associates a color with the firm. If unspecified it is inherited from firm_default. If the default is left unspecified (or set to null), an arbitrary color will be chosen by the application.

The neighbors field takes a list of strings as value. The strings represent the ids of the firms connected to the current one. This field can be omitted and links can be specified using the links field of the network specification. If both neighbors and links indicate that some firms are connected, the meaning of the specification will be the union of the two indications.

The workers field specifies the workforce associated with the firm. When omitted, the firm has no workers.

Worker specification

The workforce of a firm is described using worker specifications. A worker specification can have one of two forms:

  1. a list of objects
  2. a natural number

In the first case, each item in the list is an object of the form:

{
  "num": NUM,
  "searchingProb": PROB,
  "employed": BOOL
}

The field num defines the number of identical workers to be created with the characteristics specified by the other fields. It can be omitted and defaults to 1.

The searchingProb field represents the probability with which the worker will look for jobs if unemployed. The employed field determines the initial state of the worker(s). These two fields can be omitted and their default value is then fetched from the worker_default field of the network specification.

In the second case, a natural number N is interpreted as the specification [{ "num": N }] (thus inheriting the missing fields from worker_default).

Link specifications

The connection structure of the network can be fully specified using the neighbors field of the firms specifications. One may prefer to put this information in a separate section; the (optional) links field of a network specification allows exactly this.

A link specification consists of a JSON object of the form

{
  ID1: [ID, ID, ... ID],
  ID2: [ID, ID, ... ID],
  ...
  IDn: [ID, ID, ... ID]
}

where the list associated with each id is the list of its neighbors. An association ID1: ID2 is interpreted as ID1: [ID2].

When both the neighbors fields of firm specifications and the links field are used, the combined specification is the union of the neighbors. For example

{
  "firms": {
    "A": {"neighbors": ["B", "C"], ... },
    ...
  },
  "links": {
    "A": ["C", "D"],
    ...
  },
  ...
}

will link firm A with B, C and D.

Note that

  • self links have no effect;
  • linking two firms multiple times has the same effect of linking them once;
  • links are undirected, i.e. symmetric. Setting B as a neighbor of A is the same as setting A as a neighbor of B. A practical convention to avoid specifying the same link multiple times is to only include a neighbor X in the list of a firm Y if X < Y, for some total order < (for example lexical order).

Defaults

The isHiringProb parameter defaults to 0.5 when omitted.

When firms or links are not specified, they are assumed to be empty, i.e. {}.

The default value for firm_default is

{
  "hireProb": 0.8,
  "fireProb": 0.1,
  "isHiring": true,
  "color": null
}

The default value for worker_default is

{
  "searchingProb": 1,
  "employed": true
}

Examples

A simple example:

{
  "firms": {
    "A": {"workers": [{"num": 50, "employed": true}, {"num": 60, "employed": false}]},
    "B": {"workers": 40, "fireProb": 0.8}
  },
  "links": {
    "A": ["B"]
  },
  "firm_default": {"fireProb": 0.2},
  "worker_default": {"employed": false}
}

defines a network of two linked firms A and B. Firm A will have fireProb set to 0.2 by virtue of firm_default. Firm B instead overwrites the default setting fireProb to 0.8. Firm A will have 50 employees and 60 unemployed affiliates. Firm B has 40 unemployed affiliates; they are unemployed by virtue of worker_default.

Another, longer, example:

{
  "isHiringProb": 0.5,
  
  "firms": {
    "F0": {
      "workers": [
        {"num": 23, "employed": true},
        {"num": 35, "employed": false}
      ]
    },
    "F1": {
      "workers": [
        {"num": 81, "employed": true},
        {"num": 91, "employed": false}
      ],
      "neighbors": ["F0"]
    },
    "F2": {
      "workers": [
        {"num": 51, "employed": true},
        {"num": 82, "employed": false}
      ]
    },
    "F3": {
      "workers": [
        {"num": 11, "employed": true},
        {"num": 54, "employed": false}
      ]
    },
    "F4": {
      "workers": [
        {"num": 72, "employed": true},
        {"num": 89, "employed": false}
      ],
      "neighbors": ["F1"]
    },
    "F5": {
      "workers": [
        {"num": 51, "employed": true},
        {"num": 13, "employed": false}
      ]
    },
    "F6": {
      "workers": [
        {"num": 32, "employed": true},
        {"num": 41, "employed": false}
      ],
      "neighbors": ["F5"]
    },
    "F7": {
      "workers": [
        {"num": 42, "employed": true},
        {"num": 63, "employed": false}
      ],
      "neighbors": ["F0", "F1"]
    },
    "F8": {
      "workers": [
        {"num": 49, "employed": true},
        {"num": 38, "employed": false}
      ],
      "neighbors": ["F0", "F2", "F4", "F5", "F6"]
    },
    "F9": {
      "workers": [
        {"num": 46, "employed": true},
        {"num": 22, "employed": false}
      ],
      "neighbors": ["F0", "F2", "F3", "F7", "F8"]
    }
  },

  "firm_default": {
    "hireProb": 0.8,
    "fireProb": 0.1,
    "isHiring": true
  },
  
  "worker_default": {
    "searchingProb": 1,
    "employed": true
  }
}

Giving rise to the following network

example1

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.