Demo models‎ > ‎MacroABM‎ > ‎

The Capital Good Firm class (KFirm)

1 Entities

The KFirm class represents a Capital Good producing Firm.  As discussed in The Class Hierarchy of 'Agents', the KFirm class is derived from (i.e. is a subclass of) the Firm class, which itself is derived from the Agent class.  The relationship with the Firm class can be seen at the start of the class declaration, where the keyword extends is used to show that the KFirm class is derived from the Firm class:
public class KFirm extends Firm {
In the MacroABM model, KFirm is an Entity class, as specified by the @Entity annotation.  This implies that the class is linked to a table in the database with the same name, and that all fields which are not annotated as @Transient are persisted in the database, when the simulation output is dumped to the output database. Entity classes must specify a PanelEntityKey (annotated as @Id), which is a three-dimensional object which identifies the agent id, the simulation time and the simulation run. These three keys uniquely identify each record in the database:
private PanelEntityKey key;

The Object Relational Mapping (ORM) embedded in JAS-mine, which handles the representation of Java objects to the database, expects that the field names in the database are the same as the property names in the Java class.  Indeed, when exporting data to .csv files instead of the output database, the data is labelled using the name of the field as it appears in the code.

Class fields that are not simple types such as numerical values, strings or booleans cannot easily be represented in the output database.  Examples include Java objects such as the KFirm class' BalanceSheetKFirm object, which is thus annotated @Transient, which indicates to JAS-mine to ignore this field when exporting data to the output database or .csv file.  If the user wanted to store information about the balance sheet, the solution would be to define the BalanceSheetKFirm object as an Entity class itself, thus allowing its simple field types of numerical values, strings or booleans to be recorded in the same way as the KFirm.

2 The EventListener interface

Although not explicitly defined as implementing the EventListener interface, the KFirm class inherits this property from its superclass Agent, whose class declaration begins in the following way:

public abstract class Agent implements EventListener

This means that the KFirm objects are able to be activated by the scheduler with the onEvent() method.  The calls that a KFirm is able to respond to, are enumerated in a specific Enum called Processes (see Box 1).

public enum Processes {



public void onEvent(Enum<?> type) {

        switch ((Processes) type) {
        case Update:
        case Research:
        case Brochure:
        case LaborDemand:
        case MachineProduction:
        case Accounting:


Box 1. The KFirm implements the EventListener interface.

These enum Processes are usually added to the schedule in the MacroModel class' buildSchedule() method, with lines such as:

modelEventGroup.addCollectionEvent(kFirms, KFirm.Processes.Update);

modelEventGroup.addCollectionEvent(kFirms, KFirm.Processes.Research);

This means that the Process represented by the enums 'Update' and 'Research' are added as Events to the EventGroup, which is scheduled to fire at each time-step.  The addCollectionEvent() method is used, because the Update and Research events are to be applied to a collection of objects, in this case the set of kFirms, which is the first argument of the method.  This results in the Update and Research events being fired by each KFirm object in the kFirms set, so in effect every KFirm object performs the code for the relevant case in the switch code in Box 1 (i.e. run update() and research() methods respectively).

The significant methods of the KFirm class, often ones that are called via the EventListener implementation, are discussed in the next section.

3 Methods

We discuss the enum processes of the EventListener interface in Box 1, highlighting the important methods of the KFirm class.

3.1 research()

As specified in the Dosi paper, Capital Good Firms spend a constant proportion of their past sales investing in research and development.  The research and development is further subdivided into expenditure funding innovation, i.e. the development of completely new technology, and expenditure trying to imitate other KFirms' technologies.  This innovation is executed by the innovation() method, and the imitation is executed in the imitation() method.  The KFirm update their technology to produce any new machine that, as a result of either imitation or innovation, has a lower time-averaged selling price.

3.2 innovation()

This method samples a Bernoulli distribution to decide whether the innovation phase takes place, with the result of the innovation modelled by sampling a Beta distribution to determine a factor adjustment to the current machine price and productivity.  As described above, in the research() method, the firm only adopts the new innovation if it leads to an improvement in the machine technology as measured by its price and productivity.

3.3 imitation()

Similarly to the innovation method, this also samples a Bernoulli distribution to ascertain whether imitation takes place.  If it does, the KFirm chooses another KFirm's technology to imitate, with probability based on how similar the other KFirm's technology is to its own (in terms of price and productivity).

3.4 brochure()

In this method, KFirms send 'brochures' advertising their machine technology to their set of existing CFirm clients, and also randomly 'discovers' a set of new Firm clients to potentially become their machine supplier.

3.5 laborDemand()

The KFirm calculates the amount of labor it needs to fulfill all its orders for machine production, in addition to its own labor demand for research and development.

3.6 laborRationing()

This method reduces the amount of labor the KFirm demands due to a shortage of labor in the economy, i.e. labor demand exceeds labor supply in this time-step.  The quantity of machines produced and the investment from CFirm clients is also reduced accordingly.  Note that the labor demanded by KFirms for research and development is unaffected by labor rationing.

NOTE: because investments are rounded down in terms of integer machine units produced, the sum of the new investments may be smaller than what can actually be produced by the capital-good firm, i.e. there are 'leftovers'. In this case, we assume that the KFirm ranks its CFirm clients from the biggest one to the smallest one
in terms of their order size, and distributes those 'leftovers' until they become nil.  This procedure is not specified in the Dosi model, so it is possible that we depart from their original model here.

3.7 machineProduction() and machineDelivery()

In these methods, the KFirm produces and immediately delivers the machines to its CFirm clients.  Note that in the Dosi paper, it is specified that any newly created machines ordered by the CFirms are only available for use in the CFirms' production activities at the next time-step.  In this way, we may depart from the original Dosi model, depending on if we schedule these events to occur before CFirm production.

3.8 accounting()

This method updates the various fields related to the accounts of the KFirm, such as the KFirm's profit, liquid assets and production size, and also handles the transfer of taxes from the KFirm sector to the government.

Previous: The Model class        Next: The Consumption Good Firm class (CFirm)