Skip to content

Resources

Natural resources: harvesting, extracting, and cultivating renewable and nonrenewable stocks.

BidRentInteraction(label, *, target, yields, prices, costs, rates)

Bases: Interaction

Land use of highest bid rent, where crop i bids Y_i (p_i - c_i) - Y_i f_i d at the distance d of a market.

A cell grows the crop of the highest positive bid, and lies idle as crop 0 when no bid is positive.

Parameters:

Name Type Description Default
label str

The label of the interaction.

 required
target Annotated[str, RoleSpec()]

The path of the field of cells, whose members hold crop and distance.

 required
yields Sequence[float]

The yield Y_i of every crop per cell.

 required
prices Sequence[float]

The price p_i of every crop at the market.

 required
costs Sequence[float]

The cost c_i of every crop per unit of yield.

 required
rates Sequence[float]

The transport rate f_i of every crop per unit of yield and of distance.

 required

Raises:

Type Description
ValidationError

The four sequences do not have one value per crop, raised by prepare.

Examples:

>>> from skcomplex.systems.economics.resources import BidRentInteraction
>>> bid = BidRentInteraction('bid', target='plain', yields=(2.0,), prices=(3.0,), costs=(1.0,), rates=(0.1,))
>>> bid.rates
(0.1,)
Source code in src/skcomplex/systems/economics/resources/_land_use.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def __init__(
    self,
    label: str,
    *,
    target: Annotated[str, RoleSpec()],
    yields: Sequence[float],
    prices: Sequence[float],
    costs: Sequence[float],
    rates: Sequence[float],
) -> None:
    super().__init__(label)
    self.target = target
    self.yields = yields
    self.prices = prices
    self.costs = costs
    self.rates = rates

CowElement(label, visual=VisualSpec('agents', {'color_by': 'energy'}), *, owner=-1.0, energy=4.0)

Bases: Element

Cow of a herder that gains the energy of the grass it eats, burns its metabolism, and starves without food.

Parameters:

Name Type Description Default
label str

The label of the agent or group.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 VisualSpec('agents', {'color_by': 'energy'})
owner Annotated[float, StateSpec(reference=herders)]

The id of the herder that owns the cow, given initially as its position in the group herders.

 -1.0
energy Annotated[float, StateSpec()]

The energy of the cow.

 4.0

Examples:

>>> from skcomplex.core.components.elements import GroupElement
>>> from skcomplex.systems.economics.resources import CowElement
>>> GroupElement('cows', element=CowElement, size=3, values={'energy': 4.0}).size
3
Source code in src/skcomplex/systems/economics/resources/_commons.py 
148
149
150
151
152
153
154
155
156
157
158
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = VisualSpec('agents', {'color_by': 'energy'}),
    *,
    owner: Annotated[float, StateSpec(reference='herders')] = -1.0,
    energy: Annotated[float, StateSpec()] = 4.0,
) -> None:
    super().__init__(label, visual=visual)
    self.owner = owner
    self.energy = energy

CropLivestockElement(label, visual=None, *, wealth=10000.0, livestock=4.0, yield_multiplier=1.0, purchases=0.0, crop_area=0.5, yield_normal=3.2, price=50000.0, unit_price=35000.0, purchase_price=15000.0, household_consumption=75000.0, max_livestock=8.0, sale_fraction=0.2, yield_regeneration=0.0, cropping_intensity=0.0)

Bases: Element

Farming household with crop land, wealth, and livestock, whose purchases join the herd after a maturation delay.

Every year the household sells INT(livestock sale_fraction) animals and buys INT(wealth / purchase_price) animals when that number is at most max_livestock + sale - livestock, and none otherwise. Its wealth grows by the crop income, the area times the normal yield times the yield multiplier times the price, and the livestock income, and falls by the purchases and the household consumption. Purchased animals join the herd three years later, and the yield multiplier regenerates and degenerates at fractions of itself.

Parameters:

Name Type Description Default
label str

The label of the household.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
wealth Annotated[float, StateSpec()]

The wealth of the household.

 10000.0
livestock Annotated[float, StateSpec(domain=closed_open(0, oo))]

The animals of the herd.

 4.0
yield_multiplier Annotated[float, StateSpec(domain=closed_open(0, oo))]

The multiplier of the normal crop yield.

 1.0
purchases Annotated[float, StateSpec(domain=closed_open(0, oo), lags=2)]

The animals bought in the previous year.

 0.0
crop_area Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The crop area, in hectares.

 0.5
yield_normal Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The normal crop yield, in tonnes per hectare.

 3.2
price Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The price of a tonne of crop.

 50000.0
unit_price Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The price an animal sells for.

 35000.0
purchase_price Annotated[float, ParameterSpec(domain=open(0, oo))]

The price of an animal bought.

 15000.0
household_consumption Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The consumption of the household per year.

 75000.0
max_livestock Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The largest herd the household can rear.

 8.0
sale_fraction Annotated[float, ParameterSpec(domain=closed(0, 1))]

The fraction of the herd sold every year.

 0.2
yield_regeneration Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction by which the yield multiplier regenerates every year.

 0.0
cropping_intensity Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction by which the yield multiplier degenerates every year.

 0.0

Examples:

>>> from skcomplex.systems.economics.resources import CropLivestockElement
>>> CropLivestockElement('household', max_livestock=10.0).max_livestock
10.0
Source code in src/skcomplex/systems/economics/resources/_crop_livestock.py 
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    wealth: Annotated[float, StateSpec()] = 10000.0,
    livestock: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 4.0,
    yield_multiplier: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    purchases: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), lags=2)] = 0.0,
    crop_area: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
    yield_normal: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 3.2,
    price: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 50000.0,
    unit_price: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 35000.0,
    purchase_price: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 15000.0,
    household_consumption: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 75000.0,
    max_livestock: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 8.0,
    sale_fraction: Annotated[float, ParameterSpec(domain=RealSet.closed(0, 1))] = 0.2,
    yield_regeneration: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    cropping_intensity: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
) -> None:
    super().__init__(label, visual=visual)
    self.wealth = wealth
    self.livestock = livestock
    self.yield_multiplier = yield_multiplier
    self.purchases = purchases
    self.crop_area = crop_area
    self.yield_normal = yield_normal
    self.price = price
    self.unit_price = unit_price
    self.purchase_price = purchase_price
    self.household_consumption = household_consumption
    self.max_livestock = max_livestock
    self.sale_fraction = sale_fraction
    self.yield_regeneration = yield_regeneration
    self.cropping_intensity = cropping_intensity

get_crop_production(s) staticmethod

Return the crop production, the area times the normal yield times the yield multiplier.

Parameters:

Name Type Description Default
s SimpleNamespace

The namespace of the household.

 required

Returns:

Name Type Description
production Expression

The crop production, in tonnes per year.
Source code in src/skcomplex/systems/economics/resources/_crop_livestock.py 
150
151
152
153
154
155
156
157
158
159
160
161
162
@staticmethod
def get_crop_production(s: SimpleNamespace) -> Expression:
    """Return the crop production, the area times the normal yield times the yield multiplier.

    Args:
        s:
            The namespace of the household.

    Returns:
        production:
            The crop production, in tonnes per year.
    """
    return s.crop_area * s.yield_normal * s.yield_multiplier

get_income_from_crop(s) staticmethod

Return the income from the crop, the production times the price.

Parameters:

Name Type Description Default
s SimpleNamespace

The namespace of the household.

 required

Returns:

Name Type Description
income Expression

The income from the crop per year.
Source code in src/skcomplex/systems/economics/resources/_crop_livestock.py 
164
165
166
167
168
169
170
171
172
173
174
175
176
@staticmethod
def get_income_from_crop(s: SimpleNamespace) -> Expression:
    """Return the income from the crop, the production times the price.

    Args:
        s:
            The namespace of the household.

    Returns:
        income:
            The income from the crop per year.
    """
    return CropLivestockElement.get_crop_production(s) * s.price

get_income_from_livestock(s) staticmethod

Return the income from the livestock, the animals sold times their price.

Parameters:

Name Type Description Default
s SimpleNamespace

The namespace of the household.

 required

Returns:

Name Type Description
income Expression

The income from the livestock per year.
Source code in src/skcomplex/systems/economics/resources/_crop_livestock.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
@staticmethod
def get_income_from_livestock(s: SimpleNamespace) -> Expression:
    """Return the income from the livestock, the animals sold times their price.

    Args:
        s:
            The namespace of the household.

    Returns:
        income:
            The income from the livestock per year.
    """
    return CropLivestockElement.get_sale(s) * s.unit_price

get_purchase(s) staticmethod

Return the animals bought in the year, the affordable ones when the herd has room for them.

Parameters:

Name Type Description Default
s SimpleNamespace

The namespace of the household.

 required

Returns:

Name Type Description
purchase Expression

The animals bought.
Source code in src/skcomplex/systems/economics/resources/_crop_livestock.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
@staticmethod
def get_purchase(s: SimpleNamespace) -> Expression:
    """Return the animals bought in the year, the affordable ones when the herd has room for them.

    Args:
        s:
            The namespace of the household.

    Returns:
        purchase:
            The animals bought.
    """
    affordable = floor(s.wealth / s.purchase_price)
    room = s.max_livestock + CropLivestockElement.get_sale(s) - s.livestock
    return where(affordable <= room, affordable, 0)

get_sale(s) staticmethod

Return the animals sold in the year, INT(livestock sale_fraction).

Parameters:

Name Type Description Default
s SimpleNamespace

The namespace of the household.

 required

Returns:

Name Type Description
sale Expression

The animals sold.
Source code in src/skcomplex/systems/economics/resources/_crop_livestock.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
@staticmethod
def get_sale(s: SimpleNamespace) -> Expression:
    """Return the animals sold in the year, `INT(livestock sale_fraction)`.

    Args:
        s:
            The namespace of the household.

    Returns:
        sale:
            The animals sold.
    """
    return floor(s.livestock * s.sale_fraction)

FarmerElement(label, visual=None, *, wealth=0.0, resource='land/stock.n', effort='harvest.effort')

Bases: Element

Farmer who adds the catch of every step to its wealth, reading the resource from the other partition.

Parameters:

Name Type Description Default
label str

The label of the agent or group.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
wealth Annotated[float, StateSpec(domain=closed_open(0, oo))]

The initial wealth.

 0.0
resource str

The dotted name of the resource stock.

 'land/stock.n'
effort str

The dotted name of the harvest effort per farmer.

 'harvest.effort'

Examples:

>>> from skcomplex.core.components.elements import GroupElement
>>> from skcomplex.systems.economics.resources import FarmerElement
>>> GroupElement('farmers', element=FarmerElement, size=10).size
10
Source code in src/skcomplex/systems/economics/resources/_harvesting.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    wealth: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    resource: str = 'land/stock.n',
    effort: str = 'harvest.effort',
) -> None:
    super().__init__(label, visual=visual)
    self.wealth = wealth
    self.resource = resource
    self.effort = effort

catch(agent, system)

Add the effort times the resource stock at the last synchronisation point to the wealth.

Parameters:

Name Type Description Default
agent FarmerView

The farmer.

 required
system SystemView

The system.

 required
Source code in src/skcomplex/systems/economics/resources/_harvesting.py 
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
def catch(self, agent: FarmerView, system: SystemView) -> None:
    """Add the effort times the resource stock at the last synchronisation point to the wealth.

    Args:
        agent:
            The farmer.

        system:
            The system.
    """
    stock = system.inputs.get(self.resource, 0.0)
    if not isinstance(stock, int | float | np.number):
        error_msg = f'The input {self.resource!r} of the farmers is {stock!r}, not a number.'
        raise ValidationError(error_msg)
    agent.wealth += system.parameters[self.effort] * float(stock)

FisheryElement(label, visual=None, *, resource=1000.0, capital=5.0, cost=1.0, growth_goal=0.1, lifetime=20.0, yield_table=FISH_YIELD, regeneration_table=REGENERATION, price_table=PRICE_BY_YIELD)

Bases: Element

Capital that harvests a regenerating resource, with a price that rises as the yield falls.

The resource regenerates at a rate per unit of stock that is a hump-shaped table of the stock, zero when it is empty or full. The harvest is the capital times the yield per unit of capital, a table of the stock. The fishery holds the stocks, the parameters, and the tables, and transfers within it of the system move the resource and the capital.

Parameters:

Name Type Description Default
label str

The label of the fishery.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
resource Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=fish)]

The initial resource stock.

 1000.0
capital Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=capital)]

The initial capital.

 5.0
cost Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The operating cost per unit of capital.

 1.0
growth_goal Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The largest investment per unit of capital.

 0.1
lifetime Annotated[float, ParameterSpec(domain=open(0, oo))]

The average lifetime of the capital.

 20.0
yield_table Sequence[float]

The yield per unit of capital at the resource levels 0, 100, ..., 1000.

 FISH_YIELD
regeneration_table Sequence[float]

The regeneration rate at the resource levels 0, 100, ..., 1000.

 REGENERATION
price_table Sequence[float]

The price at the yields 0, 0.1, 0.2, 0.4, 0.6, 0.8, and 1.

 PRICE_BY_YIELD

Examples:

>>> from skcomplex.systems.economics.resources import FisheryElement
>>> FisheryElement('fishery', lifetime=15.0).lifetime
15.0
Source code in src/skcomplex/systems/economics/resources/_extraction.py 
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    resource: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='fish')] = 1000.0,
    capital: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='capital')] = 5.0,
    cost: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    growth_goal: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.1,
    lifetime: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 20.0,
    yield_table: Sequence[float] = FISH_YIELD,
    regeneration_table: Sequence[float] = REGENERATION,
    price_table: Sequence[float] = PRICE_BY_YIELD,
) -> None:
    super().__init__(label, visual=visual)
    self.resource = resource
    self.capital = capital
    self.cost = cost
    self.growth_goal = growth_goal
    self.lifetime = lifetime
    self.yield_table = yield_table
    self.regeneration_table = regeneration_table
    self.price_table = price_table

GrazingInteraction(label, *, requesters, providers, rule=RandomSearchSpec(), phase='grazing', herders, appetite=1.0, metabolism=0.5, milk=1.0)

Bases: MatchingInteraction[SystemView]

Grazing of the meadow, a matching of the cows with the pastures, after which every cow eats and burns energy.

The rule of the matching pairs the cows with the pastures, such as PartnerSpec('local', 'score', score=GrazingInteraction.score, clearing='provider'), which pairs every cow, in random order, with the free pasture of most grass in its cell or the cells around it, ties broken at random. A pasture takes one cow, its default quantity of one unit. Every matched cow moves to its pasture and eats up to its appetite as a transfer of grass to its energy, and its herder earns milk for what it ate. Then every cow burns its metabolism and counts in the herd of its herder, and a cow whose energy runs out dies.

Parameters:

Name Type Description Default
label str

The label of the grazing.

 required
requesters Annotated[str, RoleSpec()]

The path of the group of cows.

 required
providers Annotated[str, RoleSpec()]

The path of the group of pastures.

 required
rule MatchingRule

The spec of the algorithm that pairs the cows with the pastures.

 RandomSearchSpec()
phase str | None

The phase the grazing runs in.

 'grazing'
herders Annotated[str, RoleSpec()]

The path of the group of herders.

 required
appetite Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The most grass a cow eats in a step.

 1.0
metabolism Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The energy a cow burns in a step.

 0.5
milk Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The income of a herder per unit of grass its cows eat.

 1.0

Examples:

>>> from skcomplex.systems.economics.resources import GrazingInteraction
>>> GrazingInteraction('grazing', requesters='cows', providers='meadow', herders='herders').appetite
1.0
Source code in src/skcomplex/systems/economics/resources/_commons.py 
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
def __init__(
    self,
    label: str,
    *,
    requesters: Annotated[str, RoleSpec()],
    providers: Annotated[str, RoleSpec()],
    rule: MatchingRule = RandomSearchSpec(),
    phase: str | None = 'grazing',
    herders: Annotated[str, RoleSpec()],
    appetite: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    metabolism: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
    milk: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
) -> None:
    super().__init__(label, requesters=requesters, providers=providers, rule=rule, phase=phase)
    self.herders = herders
    self.appetite = appetite
    self.metabolism = metabolism
    self.milk = milk

match(system)

Pair and feed the cows, then let every cow burn its metabolism, count it in its herd, and starve.

Parameters:

Name Type Description Default
system SystemView

The system view of the grazing.

 required
Source code in src/skcomplex/systems/economics/resources/_commons.py 
374
375
376
377
378
379
380
381
382
383
384
385
386
def match(self, system: SystemView) -> None:
    """Pair and feed the cows, then let every cow burn its metabolism, count it in its herd, and starve.

    Args:
        system:
            The system view of the grazing.
    """
    super().match(system)
    for cow in system.agents('requesters', CowView):
        cow.energy -= system.parameter('metabolism')
        self._get_herder(cow).herd += 1
        if cow.energy < 0:
            cow.remove()

score(cow, pasture) staticmethod

Return the score of a pasture for a cow, the grass on the pasture.

Parameters:

Name Type Description Default
cow object

The agent view of the cow.

 required
pasture object

The agent view of the pasture.

 required

Returns:

Name Type Description
score float

The grass on the pasture, or minus infinity for an agent that is not a pasture.
Source code in src/skcomplex/systems/economics/resources/_commons.py 
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
@staticmethod
def score(cow: object, pasture: object) -> float:
    """Return the score of a pasture for a cow, the grass on the pasture.

    Args:
        cow:
            The agent view of the cow.

        pasture:
            The agent view of the pasture.

    Returns:
        score:
            The grass on the pasture, or minus infinity for an agent that is not a pasture.
    """
    del cow
    return float(pasture.grass) if isinstance(pasture, PastureView) else -np.inf

HarvestInteraction(label, *, target, harvesters, effort=0.05, state='n')

Bases: RateInteraction

Harvest of a stock proportional to the stock and to the number of harvesters, the rate -effort * N * n.

A rate on the state n of the target whose coefficient counts the members of the group of harvesters, which may live in another subsystem.

Parameters:

Name Type Description Default
label str

The label of the interaction.

 required
target Annotated[str, RoleSpec()]

The path of the harvested stock.

 required
harvesters Annotated[str, RoleSpec()]

The path of the group of harvesters, which the harvest counts.

 required
effort Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The harvest rate per harvester and unit of stock.

 0.05
state str

The name of the state of the target that holds the stock.

 'n'

Examples:

>>> from skcomplex.systems.economics.resources import HarvestInteraction
>>> HarvestInteraction('harvest', target='land/stock', harvesters='village/farmers', effort=0.05).effort
0.05
Source code in src/skcomplex/systems/economics/resources/_harvesting.py 
186
187
188
189
190
191
192
193
194
195
196
197
def __init__(
    self,
    label: str,
    *,
    target: Annotated[str, RoleSpec()],
    harvesters: Annotated[str, RoleSpec()],
    effort: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.05,
    state: str = 'n',
) -> None:
    super().__init__(label, target=target, state=state)
    self.harvesters = harvesters
    self.effort = effort

HarvestedResourceElement(label, visual=None, *, x=1.0, effort=0.0, r=1.0, K=1.0, q=1.0, p=1.0, c=0.2, delta=0.1)

Bases: Element

Logistic resource whose harvest effort is a bounded control input, after Clark.

The stock follows x' = r x (1 - x / K) - q E x under the effort E between 0 and its largest value. The harvest earns the price p per unit of catch and costs c per unit of effort, and the owner maximises the discounted profit ∫ exp(-delta t) (p q x - c) E dt. The profit is linear in the effort, so the optimal effort is bang-bang or singular: it takes a bound until the stock reaches the level where the yield net of costs earns the discount rate, holds the stock there, and harvests at the largest effort at the end of the horizon.

Parameters:

Name Type Description Default
label str

The label of the resource.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
x Annotated[float, StateSpec(domain=closed_open(0, oo))]

The initial stock.

 1.0
effort Annotated[float, ParameterSpec(adaptive=True, bounds=(0.0, MAX_EFFORT))]

The harvest effort, the control input.

 0.0
r Annotated[float, ParameterSpec(domain=open(0, oo))]

The intrinsic growth rate.

 1.0
K Annotated[float, ParameterSpec(domain=open(0, oo))]

The carrying capacity.

 1.0
q Annotated[float, ParameterSpec(domain=open(0, oo))]

The catchability.

 1.0
p Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The price per unit of catch.

 1.0
c Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The cost per unit of effort.

 0.2
delta Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The discount rate.

 0.1

Examples:

>>> from skcomplex.systems.economics.resources import HarvestedResourceElement
>>> HarvestedResourceElement('resource', x=0.5).x
0.5
Source code in src/skcomplex/systems/economics/resources/_optimal_harvesting.py 
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    effort: Annotated[float, ParameterSpec(adaptive=True, bounds=(0.0, MAX_EFFORT))] = 0.0,
    r: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    K: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    q: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    p: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    c: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.2,
    delta: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.1,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.effort = effort
    self.r = r
    self.K = K
    self.q = q
    self.p = p
    self.c = c
    self.delta = delta

HerderElement(label, visual=None, *, income=0.0, herd=0.0, upkeep=0.3, newborn=4.0, quota=UNLIMITED)

Bases: Element

Herder who adds a cow whenever a cow earned more than its upkeep, and sells one when the herd exceeds its quota.

The life cycle investment of the system buys a cow, at a random cell, or sells the first cow the herder owns, and two maps clear the income and the herd the grazing tallies, all member interactions in the phase of herding.

Parameters:

Name Type Description Default
label str

The label of the agent or group.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
income Annotated[float, StateSpec(domain=closed_open(0, oo))]

The milk income of the herder in the last step.

 0.0
herd Annotated[float, StateSpec(domain=closed_open(0, oo))]

The number of cows of the herder in the last step.

 0.0
upkeep Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The cost of keeping a cow for a step.

 0.3
newborn Annotated[float, ParameterSpec(domain=open(0, oo))]

The energy of a new cow.

 4.0
quota Annotated[float, ParameterSpec(domain=open(0, oo), adaptive=True)]

The largest herd of a herder, an adaptive parameter that a regulator may change.

 UNLIMITED

Examples:

>>> from skcomplex.core.components.elements import GroupElement
>>> from skcomplex.systems.economics.resources import HerderElement
>>> GroupElement('herders', element=HerderElement, size=5).size
5
Source code in src/skcomplex/systems/economics/resources/_commons.py 
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    income: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    herd: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    upkeep: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.3,
    newborn: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 4.0,
    quota: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo), adaptive=True)] = UNLIMITED,
) -> None:
    super().__init__(label, visual=visual)
    self.income = income
    self.herd = herd
    self.upkeep = upkeep
    self.newborn = newborn
    self.quota = quota

HilsaElement(label, visual=None, *, eggs=0.0, larvae=0.0, juveniles=0.0, yearlings=0.0, adults=0.0, migrants=0.0, spawners=375.0, female_fraction=FEMALE_FRACTION, eggs_per_nest=200000.0, max_nests=MAX_NESTS, spawning_time=SPAWNING_TIME, hatching_time=1.0, larval_time=2.0, river_time=8.0, ocean_time=12.0, adult_ocean_time=12.0, migration_time=2.0, egg_loss=0.99, larval_loss=0.8, juvenile_loss=0.4, first_year_loss=0.3, second_year_loss=0.5, migration_loss=0.25, juvenile_harvest=0.48, adult_harvest=0.8, weight_per_adult=0.82, weight_per_juvenile=0.09)

Bases: Element

Life cycle of the hilsa, with one stock of fish per stage and the parameters of the stages and the catch.

Parameters:

Name Type Description Default
label str

The label of the element.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
eggs Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=fish)]

The eggs in the nests, in millions of fish.

 0.0
larvae Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=fish)]

The larvae in the rivers, in millions of fish.

 0.0
juveniles Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=fish)]

The juveniles in the rivers, in millions of fish.

 0.0
yearlings Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=fish)]

The fish in their first year in the ocean, in millions of fish.

 0.0
adults Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=fish)]

The fish in their second year in the ocean, in millions of fish.

 0.0
migrants Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=fish)]

The adults migrating back to the rivers, in millions of fish.

 0.0
spawners Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=fish)]

The adults about to spawn, in millions of fish.

 375.0
female_fraction Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction of the spawners that are female and build a nest.

 FEMALE_FRACTION
eggs_per_nest Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The number of eggs per nest.

 200000.0
max_nests Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The most nests the spawning grounds hold.

 MAX_NESTS
spawning_time Annotated[float, ParameterSpec(domain=open(0, oo))]

The duration of the spawning, in months.

 SPAWNING_TIME
hatching_time Annotated[float, ParameterSpec(domain=open(0, oo))]

The time the eggs take to hatch, in months.

 1.0
larval_time Annotated[float, ParameterSpec(domain=open(0, oo))]

The time the larvae take to become juveniles, in months.

 2.0
river_time Annotated[float, ParameterSpec(domain=open(0, oo))]

The time the juveniles stay in the rivers, in months.

 8.0
ocean_time Annotated[float, ParameterSpec(domain=open(0, oo))]

The time the fish spend in their first year in the ocean, in months.

 12.0
adult_ocean_time Annotated[float, ParameterSpec(domain=open(0, oo))]

The time the fish spend in their second year in the ocean, in months.

 12.0
migration_time Annotated[float, ParameterSpec(domain=open(0, oo))]

The time the migration back to the rivers takes, in months.

 2.0
egg_loss Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction of the eggs lost to natural mortality.

 0.99
larval_loss Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction of the larvae lost to natural mortality.

 0.8
juvenile_loss Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction of the juveniles lost to natural mortality.

 0.4
first_year_loss Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction of the fish lost to natural mortality in their first year in the ocean.

 0.3
second_year_loss Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction of the fish lost to natural mortality in their second year in the ocean.

 0.5
migration_loss Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction of the adults lost during their migration to the rivers.

 0.25
juvenile_harvest Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction of the juveniles leaving the rivers that the fishery catches.

 0.48
adult_harvest Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction of the adults about to spawn that the fishery catches.

 0.8
weight_per_adult Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The weight of an adult, in kilograms.

 0.82
weight_per_juvenile Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The weight of a juvenile, in kilograms.

 0.09
Source code in src/skcomplex/systems/economics/resources/_fisheries.py 
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    eggs: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='fish')] = 0.0,
    larvae: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='fish')] = 0.0,
    juveniles: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='fish')] = 0.0,
    yearlings: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='fish')] = 0.0,
    adults: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='fish')] = 0.0,
    migrants: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='fish')] = 0.0,
    spawners: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='fish')] = 375.0,
    female_fraction: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = FEMALE_FRACTION,
    eggs_per_nest: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 2e5,
    max_nests: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = MAX_NESTS,
    spawning_time: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = SPAWNING_TIME,
    hatching_time: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    larval_time: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 2.0,
    river_time: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 8.0,
    ocean_time: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 12.0,
    adult_ocean_time: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 12.0,
    migration_time: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 2.0,
    egg_loss: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.99,
    larval_loss: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.8,
    juvenile_loss: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.4,
    first_year_loss: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.3,
    second_year_loss: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
    migration_loss: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.25,
    juvenile_harvest: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.48,
    adult_harvest: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.8,
    weight_per_adult: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.82,
    weight_per_juvenile: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.09,
) -> None:
    super().__init__(label, visual=visual)
    self.eggs = eggs
    self.larvae = larvae
    self.juveniles = juveniles
    self.yearlings = yearlings
    self.adults = adults
    self.migrants = migrants
    self.spawners = spawners
    self.female_fraction = female_fraction
    self.eggs_per_nest = eggs_per_nest
    self.max_nests = max_nests
    self.spawning_time = spawning_time
    self.hatching_time = hatching_time
    self.larval_time = larval_time
    self.river_time = river_time
    self.ocean_time = ocean_time
    self.adult_ocean_time = adult_ocean_time
    self.migration_time = migration_time
    self.egg_loss = egg_loss
    self.larval_loss = larval_loss
    self.juvenile_loss = juvenile_loss
    self.first_year_loss = first_year_loss
    self.second_year_loss = second_year_loss
    self.migration_loss = migration_loss
    self.juvenile_harvest = juvenile_harvest
    self.adult_harvest = adult_harvest
    self.weight_per_adult = weight_per_adult
    self.weight_per_juvenile = weight_per_juvenile

LandCellElement(label, crop=0.0, distance=0.0)

Bases: Element

Cell of a plain that grows one crop, numbered from 1, or lies idle as crop 0.

Parameters:

Name Type Description Default
label str

The label of the cell or the field.

 required
crop Annotated[float, StateSpec()]

The initial guess of the crop, which the equation replaces.

 0.0
distance Annotated[float, StateSpec()]

The distance from the market.

 0.0

Examples:

>>> from skcomplex.systems.economics.resources import LandCellElement
>>> LandCellElement('cell', distance=3.0).distance
3.0
Source code in src/skcomplex/systems/economics/resources/_land_use.py 
44
45
46
47
48
49
50
51
52
def __init__(
    self,
    label: str,
    crop: Annotated[float, StateSpec()] = 0.0,
    distance: Annotated[float, StateSpec()] = 0.0,
) -> None:
    super().__init__(label)
    self.crop = crop
    self.distance = distance

MeasuredFisheryElement(label, visual=None, *, x=0.5, catch=0.0, r0=1.0, sigma_r=1.0, K=1.0, error=0.0, step=0.01, restocking=0.0)

Bases: Element

Logistic fish stock with a noisy growth rate, harvested by a quota set from a measurement with an error.

Every step of length step is an Euler-Maruyama step of dx = (R0 + sigma_R W) x (1 - x / K) dt - gamma dt, where W is white noise. The fishermen measure x~ = x + e, with a Gaussian error e of standard deviation error, and set the quota gamma = x~ - K / 2, which is never negative unless restocking lets a negative quota release fish. A stock that reaches zero is extinct and stays at zero.

Parameters:

Name Type Description Default
label str

The label of the fishery.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
x Annotated[float, StateSpec(domain=closed_open(0, oo))]

The fish stock.

 0.5
catch Annotated[float, StateSpec()]

The quota of the last step, per unit of time.

 0.0
r0 Annotated[float, ParameterSpec(domain=open(0, oo))]

The mean growth rate R0.

 1.0
sigma_r Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The standard deviation sigma_R of the noise of the growth rate.

 1.0
K Annotated[float, ParameterSpec(domain=open(0, oo))]

The carrying capacity.

 1.0
error Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The standard deviation of the measurement error.

 0.0
step Annotated[float, ParameterSpec(domain=open(0, oo))]

The length of a step in units of time.

 0.01
restocking Annotated[float, ParameterSpec(domain=closed(0, 1))]

1 to let a negative quota release fish into the stock, 0 to floor the quota at zero.

 0.0

Examples:

>>> from skcomplex.systems.economics.resources import MeasuredFisheryElement
>>> MeasuredFisheryElement('fishery', error=0.1).error
0.1
Source code in src/skcomplex/systems/economics/resources/_measurement_errors.py 
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    x: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
    catch: Annotated[float, StateSpec()] = 0.0,
    r0: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    sigma_r: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    K: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    error: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    step: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 0.01,
    restocking: Annotated[float, ParameterSpec(domain=RealSet.closed(0, 1))] = 0.0,
) -> None:
    super().__init__(label, visual=visual)
    self.x = x
    self.catch = catch
    self.r0 = r0
    self.sigma_r = sigma_r
    self.K = K
    self.error = error
    self.step = step
    self.restocking = restocking

OilEconomyElement(label, visual=None, *, resource=1000.0, capital=5.0, price=3.0, cost=0.1, growth_goal=0.1, lifetime=20.0, yield_table=OIL_YIELD, price_table=None)

Bases: Element

Capital that extracts a nonrenewable resource and reinvests its profit up to a growth goal.

Extraction is the capital times the yield per unit of capital, a table of the resource stock. The profit is the price times the extraction minus the operating cost of the capital. The price is constant, or a table of the yield when a price table is given. The economy holds the stocks, the parameters, and the tables, and transfers within it of the system move the resource and the capital.

Parameters:

Name Type Description Default
label str

The label of the economy.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
resource Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=oil)]

The initial resource stock.

 1000.0
capital Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=capital)]

The initial capital.

 5.0
price Annotated[float, ParameterSpec(domain=open(0, oo))]

The price of the resource, used without a price table.

 3.0
cost Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The operating cost per unit of capital.

 0.1
growth_goal Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The largest investment per unit of capital.

 0.1
lifetime Annotated[float, ParameterSpec(domain=open(0, oo))]

The average lifetime of the capital.

 20.0
yield_table Sequence[float]

The yield per unit of capital at the resource levels 0, 100, ..., 1000.

 OIL_YIELD
price_table Sequence[float] | None

The price at the yields 0, 0.1, 0.2, 0.4, 0.6, 0.8, and 1, or None for a constant price.

 None

Examples:

>>> from skcomplex.systems.economics.resources import OilEconomyElement
>>> OilEconomyElement('oil', price=4.0).price
4.0
Source code in src/skcomplex/systems/economics/resources/_extraction.py 
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    resource: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='oil')] = 1000.0,
    capital: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='capital')] = 5.0,
    price: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 3.0,
    cost: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.1,
    growth_goal: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.1,
    lifetime: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 20.0,
    yield_table: Sequence[float] = OIL_YIELD,
    price_table: Sequence[float] | None = None,
) -> None:
    super().__init__(label, visual=visual)
    self.resource = resource
    self.capital = capital
    self.price = price
    self.cost = cost
    self.growth_goal = growth_goal
    self.lifetime = lifetime
    self.yield_table = yield_table
    self.price_table = price_table

PastureElement(label, visual=VisualSpec('agents', {'color_by': 'grass', 'color_range': (0.0, 2.0)}), *, grass=2.0, capacity=2.0, regrowth=0.2, seed=0.05)

Bases: Element

Cell of the meadow whose grass grows back logistically, from a seed bank when it is grazed bare.

Parameters:

Name Type Description Default
label str

The label of the agent or group.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 VisualSpec('agents', {'color_by': 'grass', 'color_range': (0.0, 2.0)})
grass Annotated[float, StateSpec(domain=closed_open(0, oo))]

The grass on the cell.

 2.0
capacity Annotated[float, StateSpec(domain=open(0, oo))]

The most grass the cell holds.

 2.0
regrowth Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The logistic growth rate of the grass.

 0.2
seed Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The share of the capacity that grows back as if it stood on a bare cell.

 0.05

Examples:

>>> from skcomplex.core.components.elements import GroupElement
>>> from skcomplex.systems.economics.resources import PastureElement
>>> GroupElement('meadow', element=PastureElement, size=4, values={'capacity': 2.0}).size
4
Source code in src/skcomplex/systems/economics/resources/_commons.py 
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = VisualSpec('agents', {'color_by': 'grass', 'color_range': (0.0, 2.0)}),
    *,
    grass: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo))] = 2.0,
    capacity: Annotated[float, StateSpec(domain=RealSet.open(0, oo))] = 2.0,
    regrowth: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.2,
    seed: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.05,
) -> None:
    super().__init__(label, visual=visual)
    self.grass = grass
    self.capacity = capacity
    self.regrowth = regrowth
    self.seed = seed

grow(agent, system)

Grow the grass logistically up to the capacity.

Parameters:

Name Type Description Default
agent PastureView

The pasture.

 required
system SystemView

The system.

 required
Source code in src/skcomplex/systems/economics/resources/_commons.py 
251
252
253
254
255
256
257
258
259
260
261
262
263
def grow(self, agent: PastureView, system: SystemView) -> None:
    """Grow the grass logistically up to the capacity.

    Args:
        agent:
            The pasture.

        system:
            The system.
    """
    stand = max(agent.grass, system.parameter('seed') * agent.capacity)
    growth = system.parameter('regrowth') * stand * (1 - stand / agent.capacity)
    agent.grass = min(agent.capacity, agent.grass + growth)

PlantationElement(label, visual=None, *, forest=490.0, area=10.0, abandoned=0.0, shade_removal=5.0, insects=1.0, yield_normal=5.0, price=40.0, cost=100.0, thinning_cost=20.0, adjustment_time=3.0, abandon_time=4.0, conversion_time=3.0, palm_margin=0.4, thinning_time=8.0, insect_growth=0.6, insect_control=0.3, subsidy=0.0)

Bases: Element

Cocoa land in forest, planted, and abandoned stocks, with the shade thinned and the insects it lets in.

Farmers plant forest towards a desired area that grows with the profitability of cocoa, abandon plantations whose yield and profit fall, and leave abandoned land to the forest or convert it to oil palm when cocoa pays less than palm. Removing shade raises the yield and lets the insects grow logistically, and the subsidy keeps the shade and controls the insects. The land flows are transfers within the plantation of the system.

Parameters:

Name Type Description Default
label str

The label of the plantation.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
forest Annotated[object, StateSpec(domain=closed_open(0, oo), quantity=land)]

The initial forest land.

 490.0
area Annotated[object, StateSpec(domain=closed_open(0, oo), quantity=land)]

The initial cocoa area.

 10.0
abandoned Annotated[object, StateSpec(domain=closed_open(0, oo), quantity=land)]

The initial abandoned land.

 0.0
shade_removal Annotated[object, StateSpec(domain=closed_open(0, oo))]

The initial index of shade removal, from 0 to 100.

 5.0
insects Annotated[object, StateSpec(domain=closed_open(0, oo))]

The initial index of insect attack, from 0 to 100.

 1.0
yield_normal Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The yield per area without insects or thinning.

 5.0
price Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The farm price of cocoa.

 40.0
cost Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The operating cost per area.

 100.0
thinning_cost Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The cost per area of removing all shade.

 20.0
adjustment_time Annotated[object, ParameterSpec(domain=open(0, oo))]

The time to plant towards the desired area.

 3.0
abandon_time Annotated[object, ParameterSpec(domain=open(0, oo))]

The average time before a plantation is abandoned.

 4.0
conversion_time Annotated[object, ParameterSpec(domain=open(0, oo))]

The time abandoned land stays before it returns to forest or turns to oil palm.

 3.0
palm_margin Annotated[object, ParameterSpec(domain=open(0, oo))]

The profitability of oil palm, against which abandoned land converts.

 0.4
thinning_time Annotated[object, ParameterSpec(domain=open(0, oo))]

The time to remove the shade.

 8.0
insect_growth Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The largest relative growth rate of the insects, reached with all shade removed.

 0.6
insect_control Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The rate at which the subsidy controls the insects.

 0.3
subsidy Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The coverage of the subsidy and extension programme, from 0 to 1.

 0.0

Examples:

>>> from skcomplex.systems.economics.resources import PlantationElement
>>> PlantationElement('cocoa', subsidy=0.5).subsidy
0.5
Source code in src/skcomplex/systems/economics/resources/_plantations.py 
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    forest: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo), quantity='land')] = 490.0,
    area: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo), quantity='land')] = 10.0,
    abandoned: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo), quantity='land')] = 0.0,
    shade_removal: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 5.0,
    insects: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    yield_normal: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 5.0,
    price: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 40.0,
    cost: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 100.0,
    thinning_cost: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 20.0,
    adjustment_time: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 3.0,
    abandon_time: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 4.0,
    conversion_time: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 3.0,
    palm_margin: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 0.4,
    thinning_time: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 8.0,
    insect_growth: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.6,
    insect_control: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.3,
    subsidy: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
) -> None:
    super().__init__(label, visual=visual)
    self.forest = forest
    self.area = area
    self.abandoned = abandoned
    self.shade_removal = shade_removal
    self.insects = insects
    self.yield_normal = yield_normal
    self.price = price
    self.cost = cost
    self.thinning_cost = thinning_cost
    self.adjustment_time = adjustment_time
    self.abandon_time = abandon_time
    self.conversion_time = conversion_time
    self.palm_margin = palm_margin
    self.thinning_time = thinning_time
    self.insect_growth = insect_growth
    self.insect_control = insect_control
    self.subsidy = subsidy

QuotaRegulatorInteraction(label, *, rule=None, phase=None, regulated=0.0, low=0.5, high=0.8)

Bases: FeedbackInteraction[SystemView]

Regulator that halves the quota of cows per herder when the grass runs short and raises it when it recovers.

The quota is the adaptive parameter quota of every herder. It halves, down to one cow, when the grass falls below the share low of the capacity of the meadow, and grows by one cow when the grass is above the share high. Without regulation it stays as it is.

Parameters:

Name Type Description Default
label str

The label of the regulator.

 required
rule Callable[[SystemView], None] | None

Unused, since the regulator overrides act.

 None
phase str | None

The phase the regulator acts in.

 None
regulated Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

One when the regulator changes the quota, zero otherwise.

 0.0
low Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The share of the capacity of the meadow below which the quota halves.

 0.5
high Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The share of the capacity of the meadow above which the quota rises by one cow.

 0.8

Examples:

>>> from skcomplex.systems.economics.resources import QuotaRegulatorInteraction
>>> QuotaRegulatorInteraction('regulator', regulated=1.0).regulated
1.0
Source code in src/skcomplex/systems/economics/resources/_commons.py 
421
422
423
424
425
426
427
428
429
430
431
432
433
434
def __init__(
    self,
    label: str,
    *,
    rule: Callable[[SystemView], None] | None = None,
    phase: str | None = None,
    regulated: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    low: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.5,
    high: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.8,
) -> None:
    super().__init__(label, rule=rule, phase=phase)
    self.regulated = regulated
    self.low = low
    self.high = high

act(system)

Change the quota with the share of grass left on the meadow.

Parameters:

Name Type Description Default
system SystemView

The system view of the regulator.

 required
Source code in src/skcomplex/systems/economics/resources/_commons.py 
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
def act(self, system: SystemView) -> None:
    """Change the quota with the share of grass left on the meadow.

    Args:
        system:
            The system view of the regulator.
    """
    if not system.parameter('regulated'):
        return
    pastures = system.agents('meadow', PastureView)
    share = sum(pasture.grass for pasture in pastures) / sum(pasture.capacity for pasture in pastures)
    for herder in system.agents('herders', HerderView):
        if share < system.parameter('low'):
            herder.quota = max(1.0, float(np.floor(herder.quota / 2)))
        elif share > system.parameter('high'):
            herder.quota += 1

RiceBalanceElement(label, visual=None, *, area_cultivated=68000.0, population=2800000.0, total_land_available=120000.0, planning_time=15.0, land_fraction_lost=0.00085, crop_yield=3.2, birth_fraction=0.025, life_expectancy=65.0, food_per_capita=0.18)

Bases: Element

Rice land and population of a region, with the land available for rice and the rice each person needs.

The area cultivated grows towards the land available over a planning time and loses a fraction to housing, roads, and industry, and the population grows by births and falls by deaths, through transfers of the system.

Parameters:

Name Type Description Default
label str

The label of the region.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
area_cultivated Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=land)]

The area under rice, in hectares.

 68000.0
population Annotated[float, StateSpec(domain=closed_open(0, oo), quantity=people)]

The population.

 2800000.0
total_land_available Annotated[float, ParameterSpec(domain=open(0, oo))]

The land suitable for rice, in hectares.

 120000.0
planning_time Annotated[float, ParameterSpec(domain=open(0, oo))]

The years over which the land suitable for rice is to be covered.

 15.0
land_fraction_lost Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The fraction of the area cultivated lost every year.

 0.00085
crop_yield Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The yield of rice, in tonnes per hectare.

 3.2
birth_fraction Annotated[float, ParameterSpec(domain=closed_open(0, oo))]

The births per person and year.

 0.025
life_expectancy Annotated[float, ParameterSpec(domain=open(0, oo))]

The life expectancy, in years.

 65.0
food_per_capita Annotated[float, ParameterSpec(domain=open(0, oo))]

The rice each person needs, in tonnes per year.

 0.18

Examples:

>>> from skcomplex.systems.economics.resources import RiceBalanceElement
>>> RiceBalanceElement('region', crop_yield=4.0).crop_yield
4.0
Source code in src/skcomplex/systems/economics/resources/_food_balance.py 
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    area_cultivated: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='land')] = 68000.0,
    population: Annotated[float, StateSpec(domain=RealSet.closed_open(0, oo), quantity='people')] = 2800000.0,
    total_land_available: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 120000.0,
    planning_time: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 15.0,
    land_fraction_lost: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.00085,
    crop_yield: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 3.2,
    birth_fraction: Annotated[float, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.025,
    life_expectancy: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 65.0,
    food_per_capita: Annotated[float, ParameterSpec(domain=RealSet.open(0, oo))] = 0.18,
) -> None:
    super().__init__(label, visual=visual)
    self.area_cultivated = area_cultivated
    self.population = population
    self.total_land_available = total_land_available
    self.planning_time = planning_time
    self.land_fraction_lost = land_fraction_lost
    self.crop_yield = crop_yield
    self.birth_fraction = birth_fraction
    self.life_expectancy = life_expectancy
    self.food_per_capita = food_per_capita

RiceSectorElement(label, visual=None, *, available_land=0.088, rice_area=0.680647, population=18.1024, potential=6.0, soil_quality=0.99, practice=0.61, training=0.0, bio_fraction=0.0, cropping_intensity=1.0, conversion_time=8.0, discard_rate=0.0085, growth_rate=0.021, consumption=80.0, milling_rate=0.65, subsidy=0.67, farmer_inputs=0.3, research=0.0, potential_limit=10.0, research_time=20.0, regeneration_time=10.0, degradation=0.002, learning_time=5.0, training_target=0.0, extension_time=5.0, bio_target=0.0, transition_time=10.0, intensity_target=1.0, implementation_time=10.0)

Bases: Element

Rice sector of a country, its land, population, and the factors of the productivity of its rice land.

The suitable land is developed into rice area and the rice area is discarded, and the population grows exponentially, through transfers within the sector of the system. Research raises the potential yield towards a limit, chemical fertiliser degrades the soil and fallow regenerates it, and training improves the farming practice through a learning table. The training, the share of bio-fertiliser, and the cropping intensity relax towards their targets through relaxation interactions of the system, which read the targets and times of the sector.

Parameters:

Name Type Description Default
label str

The label of the sector.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
available_land Annotated[object, StateSpec(domain=closed_open(0, oo), quantity=land)]

The initial land suitable for rice and not yet developed.

 0.088
rice_area Annotated[object, StateSpec(domain=closed_open(0, oo), quantity=land)]

The initial rice area.

 0.680647
population Annotated[object, StateSpec(domain=closed_open(0, oo), quantity=people)]

The initial population.

 18.1024
potential Annotated[object, StateSpec(domain=closed_open(0, oo))]

The initial potential yield.

 6.0
soil_quality Annotated[object, StateSpec(domain=closed_open(0, oo))]

The initial soil quality, from 0 to 1.

 0.99
practice Annotated[object, StateSpec(domain=closed_open(0, oo))]

The initial quality of the farming practice, from 0 to 1.

 0.61
training Annotated[object, StateSpec(domain=closed_open(0, oo))]

The initial coverage of the farmers by training and extension, from 0 to 1.

 0.0
bio_fraction Annotated[object, StateSpec(domain=closed_open(0, oo))]

The initial share of bio-fertiliser in the inputs.

 0.0
cropping_intensity Annotated[object, StateSpec(domain=closed_open(0, oo))]

The initial number of crops per year on the rice area.

 1.0
conversion_time Annotated[object, ParameterSpec(domain=open(0, oo))]

The time to develop the suitable land.

 8.0
discard_rate Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The fraction of the rice area discarded per year.

 0.0085
growth_rate Annotated[object, ParameterSpec()]

The growth rate of the population.

 0.021
consumption Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The rice consumption per capita, in kilograms per year.

 80.0
milling_rate Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The share of paddy that milling turns into rice.

 0.65
subsidy Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The share of the recommended fertiliser that the subsidy pays for.

 0.67
farmer_inputs Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The share of the unsubsidised fertiliser that the farmers buy.

 0.3
research Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The funding of research for high-yielding varieties, relative to its normal level.

 0.0
potential_limit Annotated[object, ParameterSpec(domain=open(0, oo))]

The potential yield that research approaches.

 10.0
research_time Annotated[object, ParameterSpec(domain=open(0, oo))]

The time research takes to reach the limit at its normal funding.

 20.0
regeneration_time Annotated[object, ParameterSpec(domain=open(0, oo))]

The time fallow takes to regenerate the soil.

 10.0
degradation Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The rate at which chemical fertiliser degrades the soil.

 0.002
learning_time Annotated[object, ParameterSpec(domain=open(0, oo))]

The time training takes to improve the practice.

 5.0
training_target Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The target coverage of training and extension.

 0.0
extension_time Annotated[object, ParameterSpec(domain=open(0, oo))]

The time the training takes to reach its target.

 5.0
bio_target Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The target share of bio-fertiliser.

 0.0
transition_time Annotated[object, ParameterSpec(domain=open(0, oo))]

The time the share of bio-fertiliser takes to reach its target.

 10.0
intensity_target Annotated[object, ParameterSpec(domain=open(0, oo))]

The target cropping intensity.

 1.0
implementation_time Annotated[object, ParameterSpec(domain=open(0, oo))]

The time the cropping intensity takes to reach its target.

 10.0

Examples:

>>> from skcomplex.systems.economics.resources import RiceSectorElement
>>> RiceSectorElement('rice', subsidy=0.5).subsidy
0.5
Source code in src/skcomplex/systems/economics/resources/_food.py 
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    available_land: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo), quantity='land')] = 0.088,
    rice_area: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo), quantity='land')] = 0.680647,
    population: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo), quantity='people')] = 18.1024,
    potential: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 6.0,
    soil_quality: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.99,
    practice: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.61,
    training: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    bio_fraction: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    cropping_intensity: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    conversion_time: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 8.0,
    discard_rate: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0085,
    growth_rate: Annotated[object, ParameterSpec()] = 0.021,
    consumption: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 80.0,
    milling_rate: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.65,
    subsidy: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.67,
    farmer_inputs: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.3,
    research: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    potential_limit: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 10.0,
    research_time: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 20.0,
    regeneration_time: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 10.0,
    degradation: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.002,
    learning_time: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 5.0,
    training_target: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    extension_time: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 5.0,
    bio_target: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 0.0,
    transition_time: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 10.0,
    intensity_target: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 1.0,
    implementation_time: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 10.0,
) -> None:
    super().__init__(label, visual=visual)
    self.available_land = available_land
    self.rice_area = rice_area
    self.population = population
    self.potential = potential
    self.soil_quality = soil_quality
    self.practice = practice
    self.training = training
    self.bio_fraction = bio_fraction
    self.cropping_intensity = cropping_intensity
    self.conversion_time = conversion_time
    self.discard_rate = discard_rate
    self.growth_rate = growth_rate
    self.consumption = consumption
    self.milling_rate = milling_rate
    self.subsidy = subsidy
    self.farmer_inputs = farmer_inputs
    self.research = research
    self.potential_limit = potential_limit
    self.research_time = research_time
    self.regeneration_time = regeneration_time
    self.degradation = degradation
    self.learning_time = learning_time
    self.training_target = training_target
    self.extension_time = extension_time
    self.bio_target = bio_target
    self.transition_time = transition_time
    self.intensity_target = intensity_target
    self.implementation_time = implementation_time

StockElement(label, visual=None, *, n=1000.0, r=1.0, K=1000.0)

Bases: Element

Renewable stock that grows logistically, n' = r n (1 - n / K).

Parameters:

Name Type Description Default
label str

The label of the stock.

 required
visual VisualSpec | None

How the element is drawn, or None for default_visual_.

 None
n Annotated[object, StateSpec(domain=closed_open(0, oo))]

The initial stock.

 1000.0
r Annotated[object, ParameterSpec(domain=closed_open(0, oo))]

The intrinsic growth rate.

 1.0
K Annotated[object, ParameterSpec(domain=open(0, oo))]

The carrying capacity.

 1000.0

Examples:

>>> from skcomplex.systems.economics.resources import StockElement
>>> StockElement('stock', n=500.0).n
500.0
Source code in src/skcomplex/systems/economics/resources/_harvesting.py 
49
50
51
52
53
54
55
56
57
58
59
60
61
def __init__(
    self,
    label: str,
    visual: VisualSpec | None = None,
    *,
    n: Annotated[object, StateSpec(domain=RealSet.closed_open(0, oo))] = 1000.0,
    r: Annotated[object, ParameterSpec(domain=RealSet.closed_open(0, oo))] = 1.0,
    K: Annotated[object, ParameterSpec(domain=RealSet.open(0, oo))] = 1000.0,
) -> None:
    super().__init__(label, visual=visual)
    self.n = n
    self.r = r
    self.K = K

cocoa(area=10.0, *, price=40.0, cost=100.0, insect_growth=0.6, subsidy=0.0)

Return a cocoa production system, plantations that boom with their profit and bust with the insects they invite.

The planted area moves towards a desired area, the current area times a table function of the profit margin, so a profitable crop expands it. Farmers thin the shading trees, which raises the yield through an intensification table but lets the insects multiply. Insect attack lowers the yield through an ecological table, and the area is abandoned at a rate that falls with the yield and the profit through two more tables. Abandoned land is converted to oil palm. A subsidy for shade conservation and pest control slows the thinning and controls the insects. Land is conserved, so the area booms while the yield is high and busts once the insects take over, unless a subsidy keeps the shade. The structure and the five table functions follow the boom and bust of cocoa in Malaysia of Bala, Arshad and Noh (2017, Chapter 8), and the rates, the price, and the costs are illustrative, with the area in thousands of hectares, the yield in hundreds of kilograms per hectare, the money in ringgit per hundred kilograms and per hectare, the shade removal and the insect attack as indices from 0 to 100, and time in years.

Parameters:

Name Type Description Default
area float

The initial planted area.

 10.0
price float

The farm price of cocoa.

 40.0
cost float

The operating cost per hectare.

 100.0
insect_growth float

The largest relative growth rate of the insect attack, reached with all shade removed.

 0.6
subsidy float

The coverage of the subsidy and extension programme, from 0 to 1.

 0.0

Returns:

Name Type Description
system System

The system, with the land stocks cocoa.area and cocoa.abandoned, the indices cocoa.shade_removal and cocoa.insects, and the flows cocoa.planting, cocoa.abandonment, and cocoa.conversion per year, over years. The observables of the system are cocoa.cocoa_yield, cocoa.profit_per_area, and cocoa.profitability.

Examples:

>>> from skcomplex.systems.economics.resources import cocoa
>>> cocoa(subsidy=1.0).elements[0].subsidy
1.0
Source code in src/skcomplex/systems/economics/resources/_plantations.py 
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
@register_system(
    field='economics/resources',
    tags=('agriculture', 'boom and bust', 'stocks and flows', 'system dynamics', 'ode'),
    references=('Bala et al. 2017',),
    defaults={'until': 50.0, 'dt': 0.25},
    observables=lambda system: [
        ObservableSpec('cocoa_yield', _cocoa_yield, element='cocoa'),
        ObservableSpec('profit_per_area', _profit_per_area, element='cocoa'),
        ObservableSpec('profitability', _profitability, element='cocoa'),
    ],
)
def cocoa(
    area: float = 10.0,
    *,
    price: float = 40.0,
    cost: float = 100.0,
    insect_growth: float = 0.6,
    subsidy: float = 0.0,
) -> System:
    """Return a cocoa production system, plantations that boom with their profit and bust with the insects they invite.

    The planted area moves towards a desired area, the current area times a table function of the profit margin, so
    a profitable crop expands it. Farmers thin the shading trees, which raises the yield through an intensification
    table but lets the insects multiply. Insect attack lowers the yield through an ecological table, and the area is
    abandoned at a rate that falls with the yield and the profit through two more tables. Abandoned land is converted
    to oil palm. A subsidy for shade conservation and pest control slows the thinning and controls the insects. Land
    is conserved, so the area booms while the yield is high and busts once the insects take over, unless a subsidy
    keeps the shade. The structure and the five table functions follow the boom and bust of cocoa in Malaysia of
    Bala, Arshad and Noh (2017, Chapter 8), and the rates, the price, and the costs are illustrative, with the area in
    thousands of hectares, the yield in hundreds of kilograms per hectare, the money in ringgit per hundred
    kilograms and per hectare, the shade removal and the insect attack as indices from 0 to 100, and time in years.

    Args:
        area:
            The initial planted area.

        price:
            The farm price of cocoa.

        cost:
            The operating cost per hectare.

        insect_growth:
            The largest relative growth rate of the insect attack, reached with all shade removed.

        subsidy:
            The coverage of the subsidy and extension programme, from 0 to 1.

    Returns:
        system:
            The system, with the land stocks `cocoa.area` and `cocoa.abandoned`, the indices `cocoa.shade_removal` and
            `cocoa.insects`, and the flows `cocoa.planting`, `cocoa.abandonment`, and `cocoa.conversion` per year, over
            years. The observables of the system are `cocoa.cocoa_yield`, `cocoa.profit_per_area`, and
            `cocoa.profitability`.

    Examples:
        >>> from skcomplex.systems.economics.resources import cocoa
        >>> cocoa(subsidy=1.0).elements[0].subsidy
        1.0
    """
    plantation = PlantationElement(
        'cocoa',
        area=area,
        price=price,
        cost=cost,
        insect_growth=insect_growth,
        subsidy=subsidy,
    )
    return System(elements=[plantation], interactions=[_land_use()])

crop_livestock_household(wealth=10000.0, livestock=4.0, *, crop_area=0.5, yield_normal=3.2, price=50000.0, unit_price=35000.0, purchase_price=15000.0, household_consumption=75000.0, max_livestock=8.0, sale_fraction=0.2)

Return Bala's crop livestock model, a farming household that adds livestock rearing to its crop income.

A household with a fixed crop area and a grant or loan to start rearing livestock earns the crop production times the price and the sales of animals, and spends on its consumption and on buying animals. Every year it sells the integer part of a fraction of its herd and buys as many animals as its wealth affords when the herd has room for them, and the animals it buys join the herd after three years. The equations and the defaults are those of the STELLA model of Bala et al. (2017, Section 4.11.6), whose DELAY(purchase_of_livestock, 3) is a pipeline of three years and whose INT truncates, so the model is a yearly map. The effects of the cropping intensity and the regeneration on the yield are zero. Livestock raises the income of the household considerably, but only after the maturation delay.

Parameters:

Name Type Description Default
wealth float

The initial wealth of the household.

 10000.0
livestock float

The initial herd.

 4.0
crop_area float

The crop area, in hectares.

 0.5
yield_normal float

The normal crop yield, in tonnes per hectare.

 3.2
price float

The price of a tonne of crop.

 50000.0
unit_price float

The price an animal sells for.

 35000.0
purchase_price float

The price of an animal bought.

 15000.0
household_consumption float

The consumption of the household per year.

 75000.0
max_livestock float

The largest herd the household can rear.

 8.0
sale_fraction float

The fraction of the herd sold every year.

 0.2

Returns:

Name Type Description
system System

The system, with the stocks household.wealth, household.livestock, and household.yield_multiplier, and the purchases of the previous year household.purchases, over years. The observables of the system are household.crop_production, household.income_from_crop, household.income_from_livestock, household.sale, and household.purchase.

Examples:

>>> from skcomplex.systems.economics.resources import crop_livestock_household
>>> crop_livestock_household(wealth=20000.0).elements[0].wealth
20000.0
Source code in src/skcomplex/systems/economics/resources/_crop_livestock.py 
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
@register_system(
    field='economics/resources',
    tags=('agriculture', 'livestock', 'household', 'livelihood', 'stocks and flows', 'system dynamics', 'discrete map'),
    references=('Bala et al. 2017',),
    defaults={'until': 12},
    observables=lambda system: [
        ObservableSpec(name, function, element='household')
        for name, function in (
            ('crop_production', CropLivestockElement.get_crop_production),
            ('income_from_crop', CropLivestockElement.get_income_from_crop),
            ('income_from_livestock', CropLivestockElement.get_income_from_livestock),
            ('sale', CropLivestockElement.get_sale),
            ('purchase', CropLivestockElement.get_purchase),
        )
    ],
)
def crop_livestock_household(
    wealth: float = 10000.0,
    livestock: float = 4.0,
    *,
    crop_area: float = 0.5,
    yield_normal: float = 3.2,
    price: float = 50000.0,
    unit_price: float = 35000.0,
    purchase_price: float = 15000.0,
    household_consumption: float = 75000.0,
    max_livestock: float = 8.0,
    sale_fraction: float = 0.2,
) -> System:
    """Return Bala's crop livestock model, a farming household that adds livestock rearing to its crop income.

    A household with a fixed crop area and a grant or loan to start rearing livestock earns the crop production times
    the price and the sales of animals, and spends on its consumption and on buying animals. Every year it sells the
    integer part of a fraction of its herd and buys as many animals as its wealth affords when the herd has room for
    them, and the animals it buys join the herd after three years. The equations and the defaults are those of the
    STELLA model of Bala et al. (2017, Section 4.11.6), whose `DELAY(purchase_of_livestock, 3)` is a pipeline of
    three years and whose `INT` truncates, so the model is a yearly map. The effects of the cropping intensity and the
    regeneration on the yield are zero. Livestock raises the income of the household considerably, but only after the
    maturation delay.

    Args:
        wealth:
            The initial wealth of the household.

        livestock:
            The initial herd.

        crop_area:
            The crop area, in hectares.

        yield_normal:
            The normal crop yield, in tonnes per hectare.

        price:
            The price of a tonne of crop.

        unit_price:
            The price an animal sells for.

        purchase_price:
            The price of an animal bought.

        household_consumption:
            The consumption of the household per year.

        max_livestock:
            The largest herd the household can rear.

        sale_fraction:
            The fraction of the herd sold every year.

    Returns:
        system:
            The system, with the stocks `household.wealth`, `household.livestock`, and `household.yield_multiplier`,
            and the purchases of the previous year `household.purchases`, over years. The observables of the system are
            `household.crop_production`, `household.income_from_crop`, `household.income_from_livestock`,
            `household.sale`, and `household.purchase`.

    Examples:
        >>> from skcomplex.systems.economics.resources import crop_livestock_household
        >>> crop_livestock_household(wealth=20000.0).elements[0].wealth
        20000.0
    """
    sale = int(livestock * sale_fraction)
    affordable = int(wealth / purchase_price)
    household = CropLivestockElement(
        'household',
        wealth=wealth,
        livestock=livestock,
        purchases=float(affordable if affordable <= max_livestock + sale - livestock else 0),
        crop_area=crop_area,
        yield_normal=yield_normal,
        price=price,
        unit_price=unit_price,
        purchase_price=purchase_price,
        household_consumption=household_consumption,
        max_livestock=max_livestock,
        sale_fraction=sale_fraction,
    )
    return System(elements=[household])

fishery_capital(resource=1000.0, capital=5.0, *, cost=1.0, growth_goal=0.1, lifetime=20.0, yield_table=FISH_YIELD)

Return Meadows' fishing fleet, capital that grows on a renewable resource and can overshoot it.

The capital grows while the harvest pays, and the outcome depends on the yield per unit of capital. With the default yield, which falls with the square of the stock, the fleet and the stock settle at an equilibrium. A technology that keeps the yield high at low stocks lets the fleet overshoot, and the stock and then the fleet collapse.

Parameters:

Name Type Description Default
resource float

The initial resource stock.

 1000.0
capital float

The initial capital.

 5.0
cost float

The operating cost per unit of capital.

 1.0
growth_goal float

The largest investment per unit of capital.

 0.1
lifetime float

The average lifetime of the capital.

 20.0
yield_table Sequence[float]

The yield per unit of capital at the resource levels 0, 100, ..., 1000.

 FISH_YIELD

Returns:

Name Type Description
system System

The system, with the resource fishery.resource and the capital fishery.capital.

Examples:

>>> from skcomplex.systems.economics.resources import fishery_capital
>>> fishery_capital(lifetime=10.0).elements[0].lifetime
10.0
Source code in src/skcomplex/systems/economics/resources/_extraction.py 
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
@register_system(
    field='economics/resources',
    tags=('renewable resource', 'system dynamics', 'ode'),
    references=('Meadows 2008',),
    defaults={'until': 100.0, 'dt': 1.0},
)
def fishery_capital(
    resource: float = 1000.0,
    capital: float = 5.0,
    *,
    cost: float = 1.0,
    growth_goal: float = 0.1,
    lifetime: float = 20.0,
    yield_table: Sequence[float] = FISH_YIELD,
) -> System:
    """Return Meadows' fishing fleet, capital that grows on a renewable resource and can overshoot it.

    The capital grows while the harvest pays, and the outcome depends on the yield per unit of capital. With the default
    yield, which falls with the square of the stock, the fleet and the stock settle at an equilibrium. A technology that
    keeps the yield high at low stocks lets the fleet overshoot, and the stock and then the fleet collapse.

    Args:
        resource:
            The initial resource stock.

        capital:
            The initial capital.

        cost:
            The operating cost per unit of capital.

        growth_goal:
            The largest investment per unit of capital.

        lifetime:
            The average lifetime of the capital.

        yield_table:
            The yield per unit of capital at the resource levels 0, 100, ..., 1000.

    Returns:
        system:
            The system, with the resource `fishery.resource` and the capital `fishery.capital`.

    Examples:
        >>> from skcomplex.systems.economics.resources import fishery_capital
        >>> fishery_capital(lifetime=10.0).elements[0].lifetime
        10.0
    """
    fishery = FisheryElement(
        'fishery',
        resource=resource,
        capital=capital,
        cost=cost,
        growth_goal=growth_goal,
        lifetime=lifetime,
        yield_table=tuple(float(value) for value in yield_table),
    )
    yields, regenerations, prices = fishery.yield_table, fishery.regeneration_table, fishery.price_table
    fish = TransferInteraction(
        'fish',
        source='fishery',
        target='fishery',
        state=Source('spawning'),
        into='resource',
        amount=lambda s: s.source.resource * lookup(s.source.resource, _table(RESOURCE_LEVELS, regenerations)),
        flow='regeneration',
        legs=[('resource', Sink('market'), lambda s: _harvest(s.source, yields), 'harvest')],
    )
    investment = TransferInteraction(
        'investment',
        source='fishery',
        target='fishery',
        state=Source('investors'),
        into='capital',
        amount=lambda s: _investment(s.source, _fish_revenue(s.source, yields, prices)),
        flow='investment',
    )
    return System(elements=[fishery], interactions=[fish, investment, _capital('depreciation', 'fishery')])

fishery_measurement_errors(n_fisheries=200, *, x=0.5, r0=1.0, sigma_r=1.0, K=1.0, error=0.0, step=0.01, restocking=False)

Return independent fisheries whose quota is set from a measurement of the stock with a Gaussian error.

The fish stock grows logistically with a growth rate R0 + sigma_R W(t) that white noise W makes random, and the fishermen harvest the quota gamma(x~) = x~ - K / 2 from their measurement x~ = x + e(t), Problem 14.8 of Argun et al. (2021). The harvest of the deterministic system peaks at x = K / 2, at R0 K / 4, and the quota rule holds the stock at K / sqrt(2), where the growth R0 x (1 - x / K) equals the quota. The problem asks whether the extinction probability can fall as the measurement error grows, after Argun et al. (2016). A quota is a catch, so it is floored at zero, and restocking lets a negative quota release fish as the formula of the source does. Every member of the group fisheries is an independent replica, so the share of extinct stocks estimates the extinction probability, and a step is an Euler-Maruyama step of length step.

Parameters:

Name Type Description Default
n_fisheries int

The number of independent fisheries.

 200
x float

The initial stock.

 0.5
r0 float

The mean growth rate.

 1.0
sigma_r float

The standard deviation of the noise of the growth rate.

 1.0
K float

The carrying capacity.

 1.0
error float

The standard deviation of the measurement error.

 0.0
step float

The length of a step in units of time.

 0.01
restocking bool

Whether a negative quota releases fish.

 False

Returns:

Name Type Description
system System

The system, with the group fisheries of the stocks fisheries.x and the quotas fisheries.catch. The observables of the system are the share of extinct stocks extinct, the mean stock mean_stock, and the mean quota mean_catch.

Examples:

>>> from skcomplex.systems.economics.resources import fishery_measurement_errors
>>> fishery_measurement_errors(10).elements[0].prepare().size_
10
Source code in src/skcomplex/systems/economics/resources/_measurement_errors.py 
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
@register_system(
    field='economics/resources',
    tags=('fishery', 'harvesting', 'measurement error', 'sde', 'extinction', 'feedback control'),
    references=('Argun et al. 2021', 'Argun et al. 2016'),
    defaults={'until': 5000},
    observables=lambda system: [
        ObservableSpec('extinct', group='fisheries', variable='x', reduce=_extinct_share),
        ObservableSpec('mean_stock', group='fisheries', variable='x', reduce='mean'),
        ObservableSpec('mean_catch', group='fisheries', variable='catch', reduce='mean'),
    ],
)
def fishery_measurement_errors(
    n_fisheries: int = 200,
    *,
    x: float = 0.5,
    r0: float = 1.0,
    sigma_r: float = 1.0,
    K: float = 1.0,
    error: float = 0.0,
    step: float = 0.01,
    restocking: bool = False,
) -> System:
    """Return independent fisheries whose quota is set from a measurement of the stock with a Gaussian error.

    The fish stock grows logistically with a growth rate `R0 + sigma_R W(t)` that white noise `W` makes random, and the
    fishermen harvest the quota `gamma(x~) = x~ - K / 2` from their measurement `x~ = x + e(t)`, Problem 14.8 of
    Argun et al. (2021). The harvest of the deterministic system peaks at `x = K / 2`, at `R0 K / 4`, and the quota
    rule holds the stock at `K / sqrt(2)`, where the growth `R0 x (1 - x / K)` equals the quota. The problem asks
    whether the extinction probability can fall as the measurement error grows, after Argun et al. (2016). A quota is
    a catch, so it is floored at zero, and `restocking` lets a negative quota release fish as the formula of the source
    does. Every member of the group `fisheries` is an independent replica, so the share of extinct stocks estimates
    the extinction probability, and a step is an Euler-Maruyama step of length `step`.

    Args:
        n_fisheries:
            The number of independent fisheries.

        x:
            The initial stock.

        r0:
            The mean growth rate.

        sigma_r:
            The standard deviation of the noise of the growth rate.

        K:
            The carrying capacity.

        error:
            The standard deviation of the measurement error.

        step:
            The length of a step in units of time.

        restocking:
            Whether a negative quota releases fish.

    Returns:
        system:
            The system, with the group `fisheries` of the stocks `fisheries.x` and the quotas `fisheries.catch`. The
            observables of the system are the share of extinct stocks `extinct`, the mean stock `mean_stock`, and the
            mean quota `mean_catch`.

    Examples:
        >>> from skcomplex.systems.economics.resources import fishery_measurement_errors
        >>> fishery_measurement_errors(10).elements[0].prepare().size_
        10
    """
    fisheries = GroupElement(
        'fisheries',
        element=MeasuredFisheryElement,
        size=n_fisheries,
        values={
            'x': x,
            'r0': r0,
            'sigma_r': sigma_r,
            'K': K,
            'error': error,
            'step': step,
            'restocking': float(restocking),
        },
    )
    return System(elements=[fisheries])

food_security(*, subsidy=0.67, bio_target=0.0, research=0.0, training_target=0.0, intensity_target=1.0)

Return a food security system, the rice self-sufficiency of a country under subsidy, research, and extension.

The land suitable for rice is developed into rice area over eight years, and the rice area is discarded for housing, roads, and industry at a small fraction per year. The production is the milled share of the productivity times the area times the cropping intensity. The productivity is the potential yield, which research raises towards a limit, times a table of the input ratio, the soil quality, which chemical fertiliser degrades and fallow regenerates, and the farming practice, which training and extension improve through a learning table. The input ratio is the share of the recommended fertiliser that the farmers apply, which the subsidy raises, and a target share of bio-fertiliser replaces the chemical one without degrading the soil. The requirement is the per capita consumption of a population growing exponentially, and the self-sufficiency level is the production over the requirement. Land is conserved, so the rice area peaks once the suitable land is developed and then declines, and without research and extension the self-sufficiency falls as the population grows. The structure and the initial values follow the food security system of Malaysia of Bala, Arshad and Noh (2017, Chapter 10), and the table functions and the rates are illustrative, with the land in millions of hectares, the population in millions, the productivity in tonnes of paddy per hectare, the rice in millions of tonnes, and time in years.

Parameters:

Name Type Description Default
subsidy float

The share of the recommended fertiliser that the subsidy pays for.

 0.67
bio_target float

The target share of bio-fertiliser in the inputs.

 0.0
research float

The funding of research for high-yielding varieties, relative to its normal level.

 0.0
training_target float

The target coverage of the farmers by training and extension, from 0 to 1.

 0.0
intensity_target float

The target cropping intensity, the crops per year on the rice area.

 1.0

Returns:

Name Type Description
system System

The system, with the land stocks rice.available_land and rice.rice_area, the population rice.population, the factors rice.potential, rice.soil_quality, rice.practice, rice.training, rice.bio_fraction, and rice.cropping_intensity, and the flows rice.development, rice.discard, and rice.population_growth per year, over years. The observables of the system are rice.input_ratio, rice.productivity, rice.production, rice.requirement, and rice.self_sufficiency.

Examples:

>>> from skcomplex.systems.economics.resources import food_security
>>> food_security(subsidy=0.0).elements[0].subsidy
0.0
Source code in src/skcomplex/systems/economics/resources/_food.py 
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
@register_system(
    field='economics/resources',
    tags=('food security', 'agriculture', 'stocks and flows', 'system dynamics', 'ode'),
    references=('Bala et al. 2017',),
    defaults={'until': 50.0, 'dt': 0.25},
    observables=lambda system: [
        ObservableSpec(name, expression, element='rice')
        for name, expression in (
            ('input_ratio', _input_ratio),
            ('productivity', _productivity),
            ('production', _production),
            ('requirement', _requirement),
            ('self_sufficiency', _self_sufficiency),
        )
    ],
)
def food_security(
    *,
    subsidy: float = 0.67,
    bio_target: float = 0.0,
    research: float = 0.0,
    training_target: float = 0.0,
    intensity_target: float = 1.0,
) -> System:
    """Return a food security system, the rice self-sufficiency of a country under subsidy, research, and extension.

    The land suitable for rice is developed into rice area over eight years, and the rice area is discarded for
    housing, roads, and industry at a small fraction per year. The production is the milled share of the
    productivity times the area times the cropping intensity. The productivity is the potential yield, which research
    raises towards a limit, times a table of the input ratio, the soil quality, which chemical fertiliser degrades and
    fallow regenerates, and the farming practice, which training and extension improve through a learning table. The
    input ratio is the share of the recommended fertiliser that the farmers apply, which the subsidy raises, and a
    target share of bio-fertiliser replaces the chemical one without degrading the soil. The requirement is the per
    capita consumption of a population growing exponentially, and the self-sufficiency level is the production over
    the requirement. Land is conserved, so the rice area peaks once the suitable land is developed and then declines,
    and without research and extension the self-sufficiency falls as the population grows. The structure and the
    initial values follow the food security system of Malaysia of Bala, Arshad and Noh (2017, Chapter 10), and the
    table functions and the rates are illustrative, with the land in millions of hectares, the population in
    millions, the productivity in tonnes of paddy per hectare, the rice in millions of tonnes, and time in years.

    Args:
        subsidy:
            The share of the recommended fertiliser that the subsidy pays for.

        bio_target:
            The target share of bio-fertiliser in the inputs.

        research:
            The funding of research for high-yielding varieties, relative to its normal level.

        training_target:
            The target coverage of the farmers by training and extension, from 0 to 1.

        intensity_target:
            The target cropping intensity, the crops per year on the rice area.

    Returns:
        system:
            The system, with the land stocks `rice.available_land` and `rice.rice_area`, the population
            `rice.population`, the factors `rice.potential`, `rice.soil_quality`, `rice.practice`, `rice.training`,
            `rice.bio_fraction`, and `rice.cropping_intensity`, and the flows `rice.development`, `rice.discard`, and
            `rice.population_growth` per year, over years. The observables of the system are `rice.input_ratio`,
            `rice.productivity`, `rice.production`, `rice.requirement`, and `rice.self_sufficiency`.

    Examples:
        >>> from skcomplex.systems.economics.resources import food_security
        >>> food_security(subsidy=0.0).elements[0].subsidy
        0.0
    """
    sector = RiceSectorElement(
        'rice',
        subsidy=subsidy,
        bio_target=bio_target,
        research=research,
        training_target=training_target,
        intensity_target=intensity_target,
    )
    transfers = [
        TransferInteraction(
            'land_use',
            source='rice',
            target='rice',
            state='available_land',
            into='rice_area',
            amount=lambda s: s.source.available_land / s.source.conversion_time,
            flow='development',
            legs=[('rice_area', Sink('urban'), lambda s: s.source.discard_rate * s.source.rice_area, 'discard')],
        ),
        TransferInteraction(
            'births',
            source='rice',
            target='rice',
            state=Source('births'),
            into='population',
            amount=lambda s: s.source.growth_rate * s.source.population,
            flow='population_growth',
        ),
    ]
    relaxations = [
        RelaxationInteraction(
            'training',
            target='rice',
            state='training',
            goal=lambda s: s.target.training_target,
            time=lambda s: s.target.extension_time,
        ),
        RelaxationInteraction(
            'bio_fraction',
            target='rice',
            state='bio_fraction',
            goal=lambda s: s.target.bio_target,
            time=lambda s: s.target.transition_time,
        ),
        RelaxationInteraction(
            'cropping_intensity',
            target='rice',
            state='cropping_intensity',
            goal=lambda s: s.target.intensity_target,
            time=lambda s: s.target.implementation_time,
        ),
    ]
    return System(elements=[sector], interactions=[*transfers, *relaxations])

harvesting(farmers=10, *, effort=0.05, r=1.0, K=1000.0)

Return a socio-ecological system of farmer agents harvesting a logistically regrowing resource.

The resource settles at K * (1 - effort * farmers / r) when effort * farmers < r, and collapses otherwise.

Parameters:

Name Type Description Default
farmers int

The number of farmers.

 10
effort float

The harvest rate per farmer and unit of stock.

 0.05
r float

The growth rate of the resource.

 1.0
K float

The carrying capacity of the resource.

 1000.0

Returns:

Name Type Description
system System

The system, with the ODE subsystem land and the agent subsystem village.

Examples:

>>> from skcomplex.systems.economics.resources import harvesting
>>> [subsystem.label for subsystem in harvesting().systems]
['land', 'village']
Source code in src/skcomplex/systems/economics/resources/_harvesting.py 
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
@register_system(
    field='economics/resources',
    tags=('socio-ecological', 'agents', 'ode', 'co-simulation'),
    references=('Hamill and Gilbert 2016 ch. 10',),
    defaults={'until': 50},
)
def harvesting(farmers: int = 10, *, effort: float = 0.05, r: float = 1.0, K: float = 1000.0) -> System:
    """Return a socio-ecological system of farmer agents harvesting a logistically regrowing resource.

    The resource settles at `K * (1 - effort * farmers / r)` when `effort * farmers < r`, and collapses otherwise.

    Args:
        farmers:
            The number of farmers.

        effort:
            The harvest rate per farmer and unit of stock.

        r:
            The growth rate of the resource.

        K:
            The carrying capacity of the resource.

    Returns:
        system:
            The system, with the ODE subsystem `land` and the agent subsystem `village`.

    Examples:
        >>> from skcomplex.systems.economics.resources import harvesting
        >>> [subsystem.label for subsystem in harvesting().systems]
        ['land', 'village']
    """
    land = System('land', elements=[StockElement('stock', n=K, r=r, K=K)])
    village = System('village', elements=[GroupElement('farmers', element=FarmerElement, size=farmers)])
    harvest = HarvestInteraction('harvest', target='land/stock', harvesters='village/farmers', effort=effort)
    return System(interactions=[harvest], systems=[land, village])

hilsa_fishery(spawners=375.0, *, eggs_per_nest=200000.0, juvenile_harvest=0.48, adult_harvest=0.8, migration_loss=0.25)

Return a hilsa fishery, the life cycle of a migratory fish that the catch of juveniles and spawners depletes.

Spawning adults lay eggs in nests in the rivers, and the number of nests is limited by the spawning grounds. The eggs hatch into larvae within a month, the larvae become juveniles within two months, and the juveniles stay in the rivers for eight months before they enter the ocean. The fish mature in the ocean over two years, migrate back to the rivers, and spawn. Every stage drains over its duration, and a fixed fraction of its outflow is lost to natural mortality, to the catch of juveniles, or to the catch of spawning adults, while the rest enters the next stage. Fish are conserved, every change of a stage is a flow, and the population settles where the spawning grounds fill, unless the catch keeps the reproduction below replacement. The stages, the durations, and the loss fractions follow the hilsa system of Bala, Arshad and Noh (2017, Chapter 9), with the stocks in millions of fish and time in months.

Parameters:

Name Type Description Default
spawners float

The initial number of adults about to spawn.

 375.0
eggs_per_nest float

The number of eggs per nest.

 200000.0
juvenile_harvest float

The fraction of the juveniles leaving the rivers that the fishery catches.

 0.48
adult_harvest float

The fraction of the adults about to spawn that the fishery catches.

 0.8
migration_loss float

The fraction of the adults lost during their migration to the rivers.

 0.25

Returns:

Name Type Description
system System

The system, with the stages hilsa.eggs, hilsa.larvae, hilsa.juveniles, hilsa.yearlings, hilsa.adults, hilsa.migrants, and hilsa.spawners, and the flows between the stages, among them hilsa.egg_deposition, hilsa.young_entering_ocean_catch, and hilsa.adult_catch, per month, over months. The observables of the system are the nests hilsa.nests, and the weights hilsa.adult_weight and hilsa.juvenile_weight in tonnes.

Examples:

>>> from skcomplex.systems.economics.resources import hilsa_fishery
>>> hilsa_fishery(adult_harvest=0.5).elements[0].adult_harvest
0.5
Source code in src/skcomplex/systems/economics/resources/_fisheries.py 
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
@register_system(
    field='economics/resources',
    tags=('fishery', 'life cycle', 'stocks and flows', 'system dynamics', 'ode'),
    references=('Bala et al. 2017',),
    defaults={'until': 120.0, 'dt': 0.5},
    observables=lambda system: [
        ObservableSpec('nests', _nests, element='hilsa'),
        ObservableSpec('adult_weight', _adult_weight, element='hilsa'),
        ObservableSpec('juvenile_weight', _juvenile_weight, element='hilsa'),
    ],
)
def hilsa_fishery(
    spawners: float = 375.0,
    *,
    eggs_per_nest: float = 2e5,
    juvenile_harvest: float = 0.48,
    adult_harvest: float = 0.8,
    migration_loss: float = 0.25,
) -> System:
    """Return a hilsa fishery, the life cycle of a migratory fish that the catch of juveniles and spawners depletes.

    Spawning adults lay eggs in nests in the rivers, and the number of nests is limited by the spawning grounds. The
    eggs hatch into larvae within a month, the larvae become juveniles within two months, and the juveniles stay in
    the rivers for eight months before they enter the ocean. The fish mature in the ocean over two years, migrate back
    to the rivers, and spawn. Every stage drains over its duration, and a fixed fraction of its outflow is lost to
    natural mortality, to the catch of juveniles, or to the catch of spawning adults, while the rest enters the next
    stage. Fish are conserved, every change of a stage is a flow, and the population settles where the spawning
    grounds fill, unless the catch keeps the reproduction below replacement. The stages, the durations, and the loss
    fractions follow the hilsa system of Bala, Arshad and Noh (2017, Chapter 9), with the stocks in millions of fish
    and time in months.

    Args:
        spawners:
            The initial number of adults about to spawn.

        eggs_per_nest:
            The number of eggs per nest.

        juvenile_harvest:
            The fraction of the juveniles leaving the rivers that the fishery catches.

        adult_harvest:
            The fraction of the adults about to spawn that the fishery catches.

        migration_loss:
            The fraction of the adults lost during their migration to the rivers.

    Returns:
        system:
            The system, with the stages `hilsa.eggs`, `hilsa.larvae`, `hilsa.juveniles`, `hilsa.yearlings`,
            `hilsa.adults`, `hilsa.migrants`, and `hilsa.spawners`, and the flows between the stages, among them
            `hilsa.egg_deposition`, `hilsa.young_entering_ocean_catch`, and `hilsa.adult_catch`, per month, over
            months. The observables of the system are the nests `hilsa.nests`, and the weights `hilsa.adult_weight` and
            `hilsa.juvenile_weight` in tonnes.

    Examples:
        >>> from skcomplex.systems.economics.resources import hilsa_fishery
        >>> hilsa_fishery(adult_harvest=0.5).elements[0].adult_harvest
        0.5
    """
    hilsa = HilsaElement(
        'hilsa',
        eggs_per_nest=eggs_per_nest,
        juvenile_harvest=juvenile_harvest,
        adult_harvest=adult_harvest,
        migration_loss=migration_loss,
    )
    hilsa.set_params(**_filled_stages(spawners, eggs_per_nest, juvenile_harvest, adult_harvest, migration_loss))
    return System(elements=[hilsa], interactions=_life_cycle())

oil_economy(resource=1000.0, capital=5.0, *, price=3.0, cost=0.1, growth_goal=0.1, lifetime=20.0, price_table=None)

Return Meadows' oil economy, capital that grows on a nonrenewable resource and collapses as it runs out.

The capital grows exponentially while extraction is cheap, peaks as falling yields cut the profit, and declines with depreciation, leaving part of the resource in the ground.

Parameters:

Name Type Description Default
resource float

The initial resource stock.

 1000.0
capital float

The initial capital.

 5.0
price float

The price of the resource, used without a price table.

 3.0
cost float

The operating cost per unit of capital.

 0.1
growth_goal float

The largest investment per unit of capital.

 0.1
lifetime float

The average lifetime of the capital.

 20.0
price_table Sequence[float] | None

The price at the yields 0, 0.1, 0.2, 0.4, 0.6, 0.8, and 1, or None for a constant price.

 None

Returns:

Name Type Description
system System

The system, with the resource oil.resource and the capital oil.capital.

Examples:

>>> from skcomplex.systems.economics.resources import oil_economy
>>> oil_economy(resource=2000.0).elements[0].resource
2000.0
Source code in src/skcomplex/systems/economics/resources/_extraction.py 
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
@register_system(
    field='economics/resources',
    tags=('nonrenewable resource', 'system dynamics', 'ode'),
    references=('Meadows 2008',),
    defaults={'until': 100.0, 'dt': 1.0},
)
def oil_economy(
    resource: float = 1000.0,
    capital: float = 5.0,
    *,
    price: float = 3.0,
    cost: float = 0.1,
    growth_goal: float = 0.1,
    lifetime: float = 20.0,
    price_table: Sequence[float] | None = None,
) -> System:
    """Return Meadows' oil economy, capital that grows on a nonrenewable resource and collapses as it runs out.

    The capital grows exponentially while extraction is cheap, peaks as falling yields cut the profit, and declines
    with depreciation, leaving part of the resource in the ground.

    Args:
        resource:
            The initial resource stock.

        capital:
            The initial capital.

        price:
            The price of the resource, used without a price table.

        cost:
            The operating cost per unit of capital.

        growth_goal:
            The largest investment per unit of capital.

        lifetime:
            The average lifetime of the capital.

        price_table:
            The price at the yields 0, 0.1, 0.2, 0.4, 0.6, 0.8, and 1, or `None` for a constant price.

    Returns:
        system:
            The system, with the resource `oil.resource` and the capital `oil.capital`.

    Examples:
        >>> from skcomplex.systems.economics.resources import oil_economy
        >>> oil_economy(resource=2000.0).elements[0].resource
        2000.0
    """
    economy = OilEconomyElement(
        'oil',
        resource=resource,
        capital=capital,
        price=price,
        cost=cost,
        growth_goal=growth_goal,
        lifetime=lifetime,
        price_table=None if price_table is None else tuple(float(value) for value in price_table),
    )
    yields, prices = economy.yield_table, economy.price_table
    extraction = TransferInteraction(
        'extraction',
        source='oil',
        target='oil',
        state='resource',
        into=Sink('market'),
        amount=lambda s: _harvest(s.source, yields),
        flow='extraction',
    )
    investment = TransferInteraction(
        'investment',
        source='oil',
        target='oil',
        state=Source('investors'),
        into='capital',
        amount=lambda s: _investment(s.source, _oil_price(s.source, yields, prices) * _harvest(s.source, yields)),
        flow='investment',
    )
    return System(elements=[economy], interactions=[extraction, investment, _capital('depreciation', 'oil')])

optimal_harvesting(x=1.0, *, r=1.0, K=1.0, q=1.0, p=1.0, c=0.2, delta=0.1)

Return a logistic resource harvested with the effort that maximises its discounted profit.

Run with an optimal control solver, the effort starts at a bound, drives the stock to the level x* where r (1 - 2 x* / K) + c r (1 - x* / K) / (p q x* - c) = delta, holds it there with the effort r (1 - x* / K) / q, and rises to its largest value at the end of the horizon, when the stock left has no value.

Parameters:

Name Type Description Default
x float

The initial stock.

 1.0
r float

The intrinsic growth rate.

 1.0
K float

The carrying capacity.

 1.0
q float

The catchability.

 1.0
p float

The price per unit of catch.

 1.0
c float

The cost per unit of effort.

 0.2
delta float

The discount rate.

 0.1

Returns:

Name Type Description
system System

The system, with the stock resource.x, the effort resource.effort, and the observable catch.

Examples:

>>> from skcomplex.systems.economics.resources import optimal_harvesting
>>> optimal_harvesting(delta=0.05).elements[0].delta
0.05
Source code in src/skcomplex/systems/economics/resources/_optimal_harvesting.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
@register_system(
    field='economics/resources',
    tags=('optimal control', 'harvesting', 'bang-bang', 'singular arc', 'ode'),
    references=('Clark 1990',),
    defaults={
        'until': 20.0,
        'dt': 0.2,
        'solver': CollocationSolver(objective=_profit, sense='max', nodes=101, scheme='trapezoidal'),
    },
    observables=lambda system: [ObservableSpec('catch', _catch)],
)
def optimal_harvesting(
    x: float = 1.0,
    *,
    r: float = 1.0,
    K: float = 1.0,
    q: float = 1.0,
    p: float = 1.0,
    c: float = 0.2,
    delta: float = 0.1,
) -> System:
    """Return a logistic resource harvested with the effort that maximises its discounted profit.

    Run with an optimal control solver, the effort starts at a bound, drives the stock to the level `x*` where
    `r (1 - 2 x* / K) + c r (1 - x* / K) / (p q x* - c) = delta`, holds it there with the effort `r (1 - x* / K) / q`,
    and rises to its largest value at the end of the horizon, when the stock left has no value.

    Args:
        x:
            The initial stock.

        r:
            The intrinsic growth rate.

        K:
            The carrying capacity.

        q:
            The catchability.

        p:
            The price per unit of catch.

        c:
            The cost per unit of effort.

        delta:
            The discount rate.

    Returns:
        system:
            The system, with the stock `resource.x`, the effort `resource.effort`, and the observable `catch`.

    Examples:
        >>> from skcomplex.systems.economics.resources import optimal_harvesting
        >>> optimal_harvesting(delta=0.05).elements[0].delta
        0.05
    """
    resource = HarvestedResourceElement('resource', x=x, r=r, K=K, q=q, p=p, c=c, delta=delta)
    return System(elements=[resource])

rice_food_balance(area_cultivated=68000.0, population=2800000.0, *, total_land_available=120000.0, planning_time=15.0, land_fraction_lost=0.00085, crop_yield=3.2, birth_fraction=0.025, life_expectancy=65.0, food_per_capita=0.18)

Return Bala's food security model, rice land that grows towards the land available against a growing population.

The area cultivated grows at MAX((total_land_available - area_cultivated) / planning_time, 0) and loses land_fraction_lost of itself every year to housing, roads, and industry. The population grows by birth_fraction per person and falls by one over the life expectancy. The food security level is the rice available, the area times the yield, over the rice required, the population times the rice per capita, and below 1 the region is short of rice. The structure, the equations, and the defaults are those of the STELLA model of Bala et al. (2017, Section 4.11.3), in hectares, people, tonnes, and years. The area rises for about fifty years towards the land available, and the food security rises for about twenty-five years and then falls as the population grows.

Parameters:

Name Type Description Default
area_cultivated float

The initial area under rice, in hectares.

 68000.0
population float

The initial population.

 2800000.0
total_land_available float

The land suitable for rice, in hectares.

 120000.0
planning_time float

The years over which the land suitable for rice is to be covered.

 15.0
land_fraction_lost float

The fraction of the area cultivated lost every year.

 0.00085
crop_yield float

The yield of rice, in tonnes per hectare.

 3.2
birth_fraction float

The births per person and year.

 0.025
life_expectancy float

The life expectancy, in years.

 65.0
food_per_capita float

The rice each person needs, in tonnes per year.

 0.18

Returns:

Name Type Description
system System

The system, with the stocks region.area_cultivated and region.population, and the flows region.area_increase_rate, region.land_lost, region.birth_rate, and region.death_rate per year. The observables of the system are region.food_available, region.food_required, and region.food_security.

Examples:

>>> from skcomplex.systems.economics.resources import rice_food_balance
>>> rice_food_balance(planning_time=10.0).elements[0].planning_time
10.0
Source code in src/skcomplex/systems/economics/resources/_food_balance.py 
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
@register_system(
    field='economics/resources',
    tags=('food security', 'agriculture', 'land use', 'stocks and flows', 'system dynamics', 'ode'),
    references=('Bala et al. 2017',),
    defaults={'until': 100.0, 'dt': 0.25},
    observables=lambda system: [
        ObservableSpec(name, expression, element='region')
        for name, expression in (
            ('food_available', _food_available),
            ('food_required', _food_required),
            ('food_security', _food_security),
        )
    ],
)
def rice_food_balance(
    area_cultivated: float = 68000.0,
    population: float = 2800000.0,
    *,
    total_land_available: float = 120000.0,
    planning_time: float = 15.0,
    land_fraction_lost: float = 0.00085,
    crop_yield: float = 3.2,
    birth_fraction: float = 0.025,
    life_expectancy: float = 65.0,
    food_per_capita: float = 0.18,
) -> System:
    """Return Bala's food security model, rice land that grows towards the land available against a growing population.

    The area cultivated grows at `MAX((total_land_available - area_cultivated) / planning_time, 0)` and loses
    `land_fraction_lost` of itself every year to housing, roads, and industry. The population grows by
    `birth_fraction` per person and falls by one over the life expectancy. The food security level is the rice
    available, the area times the yield, over the rice required, the population times the rice per capita, and below 1
    the region is short of rice. The structure, the equations, and the defaults are those of the STELLA model of Bala
    et al. (2017, Section 4.11.3), in hectares, people, tonnes, and years. The area rises for about fifty years
    towards the land available, and the food security rises for about twenty-five years and then falls as the
    population grows.

    Args:
        area_cultivated:
            The initial area under rice, in hectares.

        population:
            The initial population.

        total_land_available:
            The land suitable for rice, in hectares.

        planning_time:
            The years over which the land suitable for rice is to be covered.

        land_fraction_lost:
            The fraction of the area cultivated lost every year.

        crop_yield:
            The yield of rice, in tonnes per hectare.

        birth_fraction:
            The births per person and year.

        life_expectancy:
            The life expectancy, in years.

        food_per_capita:
            The rice each person needs, in tonnes per year.

    Returns:
        system:
            The system, with the stocks `region.area_cultivated` and `region.population`, and the flows
            `region.area_increase_rate`, `region.land_lost`, `region.birth_rate`, and `region.death_rate` per year. The
            observables of the system are `region.food_available`, `region.food_required`, and `region.food_security`.

    Examples:
        >>> from skcomplex.systems.economics.resources import rice_food_balance
        >>> rice_food_balance(planning_time=10.0).elements[0].planning_time
        10.0
    """
    region = RiceBalanceElement(
        'region',
        area_cultivated=area_cultivated,
        population=population,
        total_land_available=total_land_available,
        planning_time=planning_time,
        land_fraction_lost=land_fraction_lost,
        crop_yield=crop_yield,
        birth_fraction=birth_fraction,
        life_expectancy=life_expectancy,
        food_per_capita=food_per_capita,
    )
    land = TransferInteraction(
        'land',
        source='region',
        target='region',
        state=Source('suitable_land'),
        into='area_cultivated',
        amount=_area_increase,
        flow='area_increase_rate',
        legs=[
            (
                'area_cultivated',
                Sink('urban_land'),
                lambda s: s.source.area_cultivated * s.source.land_fraction_lost,
                'land_lost',
            ),
        ],
    )
    people = TransferInteraction(
        'people',
        source='region',
        target='region',
        state=Source('births'),
        into='population',
        amount=lambda s: s.source.population * s.source.birth_fraction,
        flow='birth_rate',
        legs=[('population', Sink('deaths'), lambda s: s.source.population / s.source.life_expectancy, 'death_rate')],
    )
    return System(elements=[region], interactions=[land, people])

tragedy_of_the_commons(n_herders=20, *, width=20, height=20, cows=1, quota=None, regrowth=0.2, capacity=2.0, upkeep=0.3, random_state=0)

Return herders whose cows graze a shared meadow, each adding cows while a cow pays, until the grass collapses.

Every step every cow moves to the richest pasture it can reach, eats, and earns its herder milk, and the grass grows back logistically. Every herder adds a cow whenever a cow earned more than its upkeep, since the gain of a cow goes to its herder while the cost of the grass it eats falls on all. With more herders than the meadow carries, the herd grows past what the grass sustains, the grass collapses below a tenth of its capacity, and the cows starve, so the herd shrinks after it. A regulator with an adaptive quota of cows per herder, lowered when the grass runs short and raised when it recovers, keeps the meadow from collapse (Hamill and Gilbert 2016 sec. 10.2).

Parameters:

Name Type Description Default
n_herders int

The number of herders.

 20
width int

The number of columns of the meadow.

 20
height int

The number of rows of the meadow.

 20
cows int

The initial number of cows of every herder.

 1
quota float | None

The initial quota of cows per herder of a regulator that adapts it, or None for no regulation.

 None
regrowth float

The logistic growth rate of the grass.

 0.2
capacity float

The most grass a cell holds.

 2.0
upkeep float

The cost of keeping a cow for a step.

 0.3
random_state int | Generator | None

The seed or generator of the cells of the cows.

 0

Returns:

Name Type Description
system System

The system, with the groups meadow, cows, and herders, whose adaptive parameter quota the regulator regulator changes, and the grazing grazing.

Examples:

>>> from skcomplex.systems.economics.resources import tragedy_of_the_commons
>>> [group.size for group in tragedy_of_the_commons(4, width=5, height=5).elements]
[25, 4, 4]
Source code in src/skcomplex/systems/economics/resources/_commons.py 
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
@register_system(
    field='economics/resources',
    tags=('commons', 'agents', 'overgrazing', 'regulation', 'grid'),
    references=('Hamill and Gilbert 2016 sec. 10.2', 'Hardin 1968'),
    defaults={'until': 100},
    observables=_commons_observables,
)
def tragedy_of_the_commons(
    n_herders: int = 20,
    *,
    width: int = 20,
    height: int = 20,
    cows: int = 1,
    quota: float | None = None,
    regrowth: float = 0.2,
    capacity: float = 2.0,
    upkeep: float = 0.3,
    random_state: int | np.random.Generator | None = 0,
) -> System:
    """Return herders whose cows graze a shared meadow, each adding cows while a cow pays, until the grass collapses.

    Every step every cow moves to the richest pasture it can reach, eats, and earns its herder milk, and the grass
    grows back logistically. Every herder adds a cow whenever a cow earned more than its upkeep, since the gain of a
    cow goes to its herder while the cost of the grass it eats falls on all. With more herders than the meadow
    carries, the herd grows past what the grass sustains, the grass collapses below a tenth of its capacity, and the
    cows starve, so the herd shrinks after it. A regulator with an adaptive quota of cows per herder, lowered when the
    grass runs short and raised when it recovers, keeps the meadow from collapse (Hamill and Gilbert 2016 sec. 10.2).

    Args:
        n_herders:
            The number of herders.

        width:
            The number of columns of the meadow.

        height:
            The number of rows of the meadow.

        cows:
            The initial number of cows of every herder.

        quota:
            The initial quota of cows per herder of a regulator that adapts it, or `None` for no regulation.

        regrowth:
            The logistic growth rate of the grass.

        capacity:
            The most grass a cell holds.

        upkeep:
            The cost of keeping a cow for a step.

        random_state:
            The seed or generator of the cells of the cows.

    Returns:
        system:
            The system, with the groups `meadow`, `cows`, and `herders`, whose adaptive parameter `quota` the regulator
            `regulator` changes, and the grazing `grazing`.

    Examples:
        >>> from skcomplex.systems.economics.resources import tragedy_of_the_commons
        >>> [group.size for group in tragedy_of_the_commons(4, width=5, height=5).elements]
        [25, 4, 4]
    """
    rng = np.random.default_rng(random_state)
    cells = [(x, y) for x in range(width) for y in range(height)]
    meadow = GroupElement(
        'meadow',
        element=PastureElement,
        size=len(cells),
        values={'grass': capacity, 'capacity': capacity, 'regrowth': regrowth},
        location=cells,
    )
    herders = GroupElement(
        'herders',
        element=HerderElement,
        size=n_herders,
        values={
            'upkeep': upkeep,
            'quota': UNLIMITED if quota is None else quota,
        },
        location=[cells[0]] * n_herders,
    )
    n_cows = n_herders * cows
    herd = GroupElement(
        'cows',
        element=CowElement,
        size=n_cows,
        values={'owner': np.repeat(np.arange(n_herders, dtype=float), cows)},
        variable=True,
        location=[cells[index] for index in rng.integers(len(cells), size=n_cows)],
    )
    regulator = QuotaRegulatorInteraction('regulator', phase='herding', regulated=float(quota is not None))
    grazing = GrazingInteraction(
        'grazing',
        requesters='cows',
        providers='meadow',
        rule=PartnerSpec('local', 'score', score=GrazingInteraction.score, clearing='provider'),
        herders='herders',
    )
    return System(
        elements=[meadow, herd, herders],
        interactions=[grazing, *_get_investment(), regulator],
        space=LatticeSpace((width, height), boundary='periodic', neighborhood='moore'),
        time=DiscreteTime(
            schedule=PhasesScheduleSpec([PhaseSpec('grazing'), PhaseSpec('growth'), PhaseSpec('herding')]),
        ),
    )

von_thunen(size=41, *, yields=(4.0, 2.0, 1.0), prices=(3.0, 3.0, 3.5), costs=(1.0, 0.5, 0.5), rates=(0.2, 0.2, 0.2))

Return a square plain around one market at its centre, whose every cell grows the crop of highest bid rent.

A crop of a high yield per cell bids most near the market, and its bid falls fastest with distance, so the land use forms concentric rings whose boundaries lie where the bids of neighbouring crops are equal (Giordano 2024 §7).

Parameters:

Name Type Description Default
size int

The side of the plain in cells, one unit of distance each.

 41
yields Sequence[float]

The yield of every crop per cell.

 (4.0, 2.0, 1.0)
prices Sequence[float]

The price of every crop at the market.

 (3.0, 3.0, 3.5)
costs Sequence[float]

The cost of every crop per unit of yield.

 (1.0, 0.5, 0.5)
rates Sequence[float]

The transport rate of every crop per unit of yield and of distance.

 (0.2, 0.2, 0.2)

Returns:

Name Type Description
system System

The system, with the states plain.crop and plain.distance.

Examples:

>>> from skcomplex.core.engine.runtime import Simulation
>>> from skcomplex.systems.economics.resources import von_thunen
>>> trajectory = Simulation(von_thunen()).prepare().run(1.0).trajectory_
>>> sorted(set(trajectory.values('plain.crop')[0].ravel().tolist()))
[0.0, 1.0, 2.0, 3.0]
Source code in src/skcomplex/systems/economics/resources/_land_use.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
@register_system(
    field='economics/resources',
    tags=('land use', 'bid rent', 'static', 'lattice'),
    references=('Giordano 2024, arXiv 2407.02181', 'von Thünen 1826'),
)
def von_thunen(
    size: int = 41,
    *,
    yields: Sequence[float] = (4.0, 2.0, 1.0),
    prices: Sequence[float] = (3.0, 3.0, 3.5),
    costs: Sequence[float] = (1.0, 0.5, 0.5),
    rates: Sequence[float] = (0.2, 0.2, 0.2),
) -> System:
    """Return a square plain around one market at its centre, whose every cell grows the crop of highest bid rent.

    A crop of a high yield per cell bids most near the market, and its bid falls fastest with distance, so the land use
    forms concentric rings whose boundaries lie where the bids of neighbouring crops are equal (Giordano 2024 §7).

    Args:
        size:
            The side of the plain in cells, one unit of distance each.

        yields:
            The yield of every crop per cell.

        prices:
            The price of every crop at the market.

        costs:
            The cost of every crop per unit of yield.

        rates:
            The transport rate of every crop per unit of yield and of distance.

    Returns:
        system:
            The system, with the states `plain.crop` and `plain.distance`.

    Examples:
        >>> from skcomplex.core.engine.runtime import Simulation
        >>> from skcomplex.systems.economics.resources import von_thunen
        >>> trajectory = Simulation(von_thunen()).prepare().run(1.0).trajectory_
        >>> sorted(set(trajectory.values('plain.crop')[0].ravel().tolist()))
        [0.0, 1.0, 2.0, 3.0]
    """
    centre = (size - 1) / 2
    rows, columns = np.indices((size, size))
    distance = np.hypot(rows - centre, columns - centre)
    plain = FieldElement(
        'plain',
        element=LandCellElement,
        space=LatticeSpace((size, size)),
        values={'distance': distance},
    )
    bid = BidRentInteraction('bid', target='plain', yields=yields, prices=prices, costs=costs, rates=rates)
    return System(elements=[plain], interactions=[bid], time=StaticTime())