Core¶

High-level functions and classes for solving a wide variety of economic models. The “core” of HARK is a framework for “microeconomic” and “macroeconomic” models. A micro model concerns the dynamic optimization problem for some type of agents, where agents take the inputs to their problem as exogenous. A macro model adds an additional layer, endogenizing some of the inputs to the micro problem by finding a general equilibrium dynamic rule.

class HARK.core.AgentType(solution_terminal=None, cycles=1, pseudo_terminal=True, tolerance=1e-06, seed=0, **kwds)¶

Bases: HARK.core.HARKobject

A superclass for economic agents in the HARK framework. Each model should specify its own subclass of AgentType, inheriting its methods and overwriting as necessary. Critically, every subclass of AgentType should define class- specific static values of the attributes time_vary and time_inv as lists of strings. Each element of time_vary is the name of a field in AgentSubType that varies over time in the model. Each element of time_inv is the name of a field in AgentSubType that is constant over time in the model.

state_vars¶

The string labels for this AgentType’s model state variables.

Type:	list of string

addToTimeInv(*params)¶

Adds any number of parameters to time_inv for this instance.

Parameters:	params (string) – Any number of strings naming attributes to be added to time_inv
Returns:
Return type:	None

addToTimeVary(*params)¶

Adds any number of parameters to time_vary for this instance.

Parameters:	params (string) – Any number of strings naming attributes to be added to time_vary
Returns:
Return type:	None

checkElementsOfTimeVaryAreLists()¶: A method to check that elements of time_vary are lists.

checkRestrictions()¶: A method to check that various restrictions are met for the model class.

clearHistory()¶

Clears the histories of the attributes named in self.track_vars.

Parameters:	None –
Returns:
Return type:	None

delFromTimeInv(*params)¶

Removes any number of parameters from time_inv for this instance.

Parameters:	params (string) – Any number of strings naming attributes to be removed from time_inv
Returns:
Return type:	None

delFromTimeVary(*params)¶

Removes any number of parameters from time_vary for this instance.

Parameters:	params (string) – Any number of strings naming attributes to be removed from time_vary
Returns:
Return type:	None

getControls()¶

Gets values of control variables for the current period, probably by using current states. Does nothing by default, but can be overwritten by subclasses of AgentType.

Parameters:	None –
Returns:
Return type:	None

getMortality()¶

Simulates mortality or agent turnover according to some model-specific rules named simDeath and simBirth (methods of an AgentType subclass). simDeath takes no arguments and returns a Boolean array of size AgentCount, indicating which agents of this type have “died” and must be replaced. simBirth takes such a Boolean array as an argument and generates initial post-decision states for those agent indices.

Parameters:	None –
Returns:
Return type:	None

getPostStates()¶

Gets values of post-decision state variables for the current period, probably by current states and controls and maybe market-level events or shock variables. Does nothing by default, but can be overwritten by subclasses of AgentType.

Parameters:	None –
Returns:
Return type:	None

getShocks()¶

Gets values of shock variables for the current period. Does nothing by default, but can be overwritten by subclasses of AgentType.

Parameters:	None –
Returns:
Return type:	None

getStates()¶

Gets values of state variables for the current period. By default, calls transition function and assigns values to the state_now dictionary.

Parameters:	None –
Returns:
Return type:	None

initializeSim()¶

Prepares this AgentType for a new simulation. Resets the internal random number generator, makes initial states for all agents (using simBirth), clears histories of tracked variables.

Parameters:	None –
Returns:
Return type:	None

makeShockHistory()¶

Makes a pre-specified history of shocks for the simulation. Shock variables should be named in self.shock_vars, a list of strings that is subclass-specific. This method runs a subset of the standard simulation loop by simulating only mortality and shocks; each variable named in shock_vars is stored in a T_sim x AgentCount array in history dictionary self.history[X]. Automatically sets self.read_shocks to True so that these pre-specified shocks are used for all subsequent calls to simulate().

Parameters:	None –
Returns:
Return type:	None

postSolve()¶

A method that is run immediately after the model is solved, to finalize the solution in some way. Does nothing here.

Parameters:	none –
Returns:
Return type:	none

preSolve()¶

A method that is run immediately before the model is solved, to check inputs or to prepare the terminal solution, perhaps.

Parameters:	none –
Returns:
Return type:	none

readShocks()¶

Reads values of shock variables for the current period from history arrays. For each variable X named in self.shock_vars, this attribute of self is set to self.history[X][self.t_sim,:].

This method is only ever called if self.read_shocks is True. This can be achieved by using the method makeShockHistory() (or manually after storing a “handcrafted” shock history).

Parameters:	None –
Returns:
Return type:	None

resetRNG()¶

Reset the random number generator for this type.

Parameters:	none –
Returns:
Return type:	none

simBirth(which_agents)¶

Makes new agents for the simulation. Takes a boolean array as an input, indicating which agent indices are to be “born”. Does nothing by default, must be overwritten by a subclass.

Parameters:	which_agents (np.array(Bool)) – Boolean array of size self.AgentCount indicating which agents should be “born”.
Returns:
Return type:	None

simDeath()¶

Determines which agents in the current population “die” or should be replaced. Takes no inputs, returns a Boolean array of size self.AgentCount, which has True for agents who die and False for those that survive. Returns all False by default, must be overwritten by a subclass to have replacement events.

Parameters:	None –
Returns:	who_dies – Boolean array of size self.AgentCount indicating which agents die and are replaced.
Return type:	np.array

simOnePeriod()¶

Simulates one period for this type. Calls the methods getMortality(), getShocks() or readShocks, getStates(), getControls(), and getPostStates(). These should be defined for AgentType subclasses, except getMortality (define its components simDeath and simBirth instead) and readShocks.

Parameters:	None –
Returns:
Return type:	None

simulate(sim_periods=None)¶

Simulates this agent type for a given number of periods. Defaults to self.T_sim if no input. Records histories of attributes named in self.track_vars in self.history[varname].

Parameters:	None –
Returns:
Return type:	None

solve(verbose=False)¶

Solve the model for this instance of an agent type by backward induction. Loops through the sequence of one period problems, passing the solution from period t+1 to the problem for period t.

Parameters:	verbose (boolean) – If True, solution progress is printed to screen.
Returns:
Return type:	none

state_vars = []

transition()¶

Parameters:	None – to match dolo spec ([Eventually,) – endogenous_prev, controls, exogenous, parameters] (exogenous_prev,) –
Returns:	endogenous_state – Tuple with new values of the endogenous states
Return type:	()

unpack(parameter)¶

Unpacks a parameter from a solution object for easier access. After the model has been solved, the parameters (like consumption function) reside in the attributes of each element of ConsumerType.solution (e.g. cFunc). This method creates a (time varying) attribute of the given parameter name that contains a list of functions accessible by ConsumerType.parameter.

Parameters:	parameter (str) – Name of the function to unpack from the solution
Returns:
Return type:	none

class HARK.core.HARKobject¶

Bases: object

A superclass for object classes in HARK. Comes with two useful methods: a generic/universal distance method and an attribute assignment method.

assignParameters(**kwds)¶

Assign an arbitrary number of attributes to this agent.

Parameters:	*kwds (keyword arguments*) – Any number of keyword arguments of the form key=value. Each value will be assigned to the attribute named in self.
Returns:
Return type:	none

distance(other)¶

A generic distance method, which requires the existence of an attribute called distance_criteria, giving a list of strings naming the attributes to be considered by the distance metric.

Parameters:	other (object) – Another object to compare this instance to.
Returns:	(unnamed) – The distance between this object and another, using the “universal distance” metric.
Return type:	float

distance_criteria = []¶

getAvg(varname, **kwds)¶

Calculates the average of an attribute of this instance. Returns NaN if no such attribute.

Parameters:	varname (string) – The name of the attribute whose average is to be calculated. This attribute must be an np.array or other class compatible with np.mean.
Returns:	avg – The average of this attribute. Might be an array if the axis keyword is passed.
Return type:	float or np.array

class HARK.core.Market(agents=None, sow_vars=None, reap_vars=None, const_vars=None, track_vars=None, dyn_vars=None, millRule=None, calcDynamics=None, act_T=1000, tolerance=1e-06, **kwds)¶

Bases: HARK.core.HARKobject

A superclass to represent a central clearinghouse of information. Used for dynamic general equilibrium models to solve the “macroeconomic” model as a layer on top of the “microeconomic” models of one or more AgentTypes.

cultivate()¶

Has each AgentType in agents perform their marketAction method, using variables sown from the market (and maybe also “private” variables). The marketAction method should store new results in attributes named in reap_vars to be reaped later.

Parameters:	none –
Returns:
Return type:	none

makeHistory()¶

Runs a loop of sow–>cultivate–>reap–>mill act_T times, tracking the evolution of variables X named in track_vars in dictionary fields history[X].

Parameters:	none –
Returns:
Return type:	none

mill()¶

Processes the variables collected from agents using the function millRule, storing the results in attributes named in aggr_sow.

Parameters:	none –
Returns:
Return type:	none

reap()¶

Collects attributes named in reap_vars from each AgentType in the market, storing them in respectively named attributes of self.

Parameters:	none –
Returns:
Return type:	none

reset()¶

Reset the state of the market (attributes in sow_vars, etc) to some user-defined initial state, and erase the histories of tracked variables.

Parameters:	none –
Returns:
Return type:	none

solve()¶

“Solves” the market by finding a “dynamic rule” that governs the aggregate market state such that when agents believe in these dynamics, their actions collectively generate the same dynamic rule.

Parameters:	None –
Returns:
Return type:	None

solveAgents()¶

Solves the microeconomic problem for all AgentTypes in this market.

Parameters:	None –
Returns:
Return type:	None

sow()¶

Distributes attrributes named in sow_vars from self to each AgentType in the market, storing them in respectively named attributes.

Parameters:	none –
Returns:
Return type:	none

store()¶

Record the current value of each variable X named in track_vars in an dictionary field named history[X].

Parameters:	none –
Returns:
Return type:	none

updateDynamics()¶

Calculates a new “aggregate dynamic rule” using the history of variables named in track_vars, and distributes this rule to AgentTypes in agents.

Parameters:	none –
Returns:	dynamics – The new “aggregate dynamic rule” that agents believe in and act on. Should have attributes named in dyn_vars.
Return type:	instance

HARK.core.distanceMetric(thing_A, thing_B)¶

A “universal distance” metric that can be used as a default in many settings.

Parameters:	thing_A (object) – A generic object. thing_B (object) – Another generic object. Returns – ------------ – distance (float) – The “distance” between thing_A and thing_B.

HARK.core.distributeParams(agent, param_name, param_count, distribution)¶

Distributes heterogeneous values of one parameter to the AgentTypes in self.agents. :param agent: An agent to clone. :type agent: AgentType :param param_name: Name of the parameter to be assigned. :type param_name: string :param param_count: Number of different values the parameter will take on. :type param_count: int :param distribution: A distribution. :type distribution: Distribution

Returns:	agent_set – A list of param_count agents, ex ante heterogeneous with respect to param_name. The AgentCount of the original will be split between the agents of the returned list in proportion to the given distribution.
Return type:	[AgentType]

HARK.core.makeOnePeriodOOSolver(solver_class)¶: Returns a function that solves a single period consumption-saving problem. :param solver_class: A class of Solver to be used. :type solver_class: Solver :param ——-: :param solver_function: A function for solving one period of a problem. :type solver_function: function

HARK.core.solveAgent(agent, verbose)¶

Solve the dynamic model for one agent type using backwards induction. This function iterates on “cycles” of an agent’s model either a given number of times or until solution convergence if an infinite horizon model is used (with agent.cycles = 0).

Parameters:	agent (AgentType) – The microeconomic AgentType whose dynamic problem is to be solved. verbose (boolean) – If True, solution progress is printed to screen (when cycles != 1).
Returns:	solution – A list of solutions to the one period problems that the agent will encounter in his “lifetime”.
Return type:	[Solution]

HARK.core.solveOneCycle(agent, solution_last)¶

Solve one “cycle” of the dynamic model for one agent type. This function iterates over the periods within an agent’s cycle, updating the time-varying parameters and passing them to the single period solver(s).

Parameters:	agent (AgentType) – The microeconomic AgentType whose dynamic problem is to be solved. solution_last (Solution) – A representation of the solution of the period that comes after the end of the sequence of one period problems. This might be the term- inal period solution, a “pseudo terminal” solution, or simply the solution to the earliest period from the succeeding cycle.
Returns:	solution_cycle – A list of one period solutions for one “cycle” of the AgentType’s microeconomic model.
Return type:	[Solution]