Actor - agent representing an economic actor.

Fields

• id::Int - the id of the agent.
• types::Set{Symbol} - the types of the actor. Types are meant to be used in data collection and/or behavior functions.
• modelbehaviors::Vector{Function} - the list of functions which are called by economodelstep!, which is the default modelstep! function.
• behaviors::Vector{Function} - the list of behavior functions which is called when the actor is activated.
• balance::Balance - the balance sheet of the agent.
• posessions::Entities - the entities in personal posession of the agent.
• stock::Stock - the stock held by the agent. The stock is considered to be used for business purposes.
• producers::Set{Producer} - the production facilities of the agent.
• prices::D where D <: Dict{<:Blueprint, Price} - the prices of the products sold by the actor.
• properties::Dict{Symbol, Any} - for internal use.

After creation, ant field can be set on the actor, even those which are not part of the structure. This can come in handy when when specific state needs to be stored with the actor.

Actor - creation function for a generic actor.

Parameters

• id::Int = ID_COUNTER - the id of the agent. When no id is given, the standard sequence of id's is used. Mixing the standard sequence and user defined id's is not advised.
• type::Union{Symbol, Nothing} = nothing - the types of the actor. Types are meant to be used in data collection and/or behavior functions.
• modelbehavior::Union{Function, Nothing} = nothing - the default function to be called by economodelstep!, which is the default modelstep! function.
• behavior::Union{Function, Nothing} = nothing - the default behavior function which is called when the actor is activated.
• balance::Balance = Balance() - the balance sheet of the agent.
• posessions::Entities = Entities() - the entities in personal posession of the agent.
• stock::Stock = Stock() - the stock held by the agent. The stock is considered to be used for business purposes.
• producers::Union{AbstractVector{Producer}, AbstractSet{Producer}} = Set{Producer}() - the production facilities of the agent.

AtomicTransaction

An atomic transaction.

• type: asset or liability.
• entry: balance entry.
• amount: amount of the transaction.
• result: result of the transaction. The new balance amount of the entry.
• comment

struct Balance

A balance sheet, including a history of transactions which led to the current state of the balance sheet.

Properties

• assets: the asset side of the balance sheet.
• defminasset: the default lower bound for asset balance entries.
• minassets: minimum asset values. Used to validate transactions. Entries override defmin_asset.
• liabilities: the liability side of the balance sheet.
• defminliability: the default lower bound for liability balance entries.
• minliabilities: minimum liability values. Used to validate transactions. Entries override defmin_liability.
• log_transactions: flag indicating whether transactions are logged. Not logging transactions improves performance.
• transactions: a chronological list of transaction tuples. Each tuple is constructed as follows: timestamp, entry type (asset or liability), balance entry, amount, new balance value, comment.
• properties: a dict with user defined properties. If the key of the dict is a Symbol, the value can be retrieved/set by balance.symbol.

Currency

Convenience type for working with currencies.

mutable struct Debt

A transferable debt contract between two balance sheets.

• id: The unique id of the contract
• creditor: the balance sheet which receives debt payments.
• debtor: the balance sheet from which payments are deducted.
• installments: a list of installments to be paid.
• interest_rate: the interest rate on the debt.
• bank_debt: indicates whether the debt is to a bank. This has an impact on how the initial transfer of money and the downpayments are booked to the creditor's balance sheet.
• money_entry: the entry to be used to book the borrowed money.
• debt_entry: the entry to be used to book the debt.
• creation: the timestamp of the creation of the debt.
• interval: the interval between installments. This can be 0.

Debt(creditor::Balance,
    debtor::Balance,
    amount::Real,
    interest_rate::Real,
    installments::Integer;
    bank_debt::Bool = true,
    money_entry::BalanceEntry = DEPOSIT,
    debt_entry::BalanceEntry = DEBT,
    creation::Int64 = 0,
    interval::Int64 = 0)

Create a debt contract between two balances with a number of equal installments.

• creditor: the balance sheet receiving the installments.
• debtor: the balance sheet from which the installments will be subtracted.
• interest_rate: the interest rate on the debt.
• installments: the number of installments.
• bank_debt: whether or not the creditor is a bank.
• money_entry: the balance sheet entry to be used to book the borrowed money.
• debt_entry: the balance sheet entry to be used to book the debt.

Entity

All implementations of Entity must have the following fields:

• id::UUID
• blueprint::Blueprint
• health::Health

Health

Mutable struct holding health, expressed in percentages between 0% and 100%.

Marginality - a progressive marginal use structure.

• marginality::Vector{Tuple{Int64, Percentage}} - a sorted list of tuples consisting of a number of units and a probability resulting in an extra unit if the number of available units is below the indicated number.

Needs - indicates the needs of an Actor.

• usage_priorities::Set{Int64} - the set of usage priorities. If this contains less than 2 elements, usage is randomised.
• wants_priorities::Set{Int64} - the set of wants priorities. If this contains less than 2 elements, purchasing wants is randomised.
• use::Dict{Tuple{Int64, Blueprint}, Marginality} - indicates what the actor will use each cycle. The Int64 in the key tuple indicates priority.
• wants::Dict{Tuple{Int64, Blueprint}, Marginality} - indicates what the actor will try to purchase each cycle.

Percentage

A float which remains between 0 and 1, representing 0% - 100%.

Price - a composite price consisting of one or more price components, each associated with a specific balance entry.

Producer

An Entity with the capability to produce other Entities.

Fields

• id: The id of the Producer.
• lifecycle: The lifecycle of the Producer.
• blueprint: The blueprint the producer is based on.

ProducerBlueprint

• type_id::UUID - the type id of the blueprint.
• name::String - blueprint name.
• lifecycle::Restorable - blueprint lifecycle
• batch_res::Dict{<:Blueprint,Int64} - the necessary resources for a production batch. These are destroyed during production.
• batch_tools::Dict{<:Blueprint,Int64} - the necessary tools for a production batch. These are used during production.
• batch::Dict{<:Blueprint,Int64} - output per batch.

Restorable

Indicates a lifecycle with restorability, i.e. the entity can recover from damage. Thresholds determine the multiplier for health at and below the threshold.

Fields

• damage_thresholds: These are tuples, ordered by percentage, holding damage multipliers. The applied multiplier corresponds with the lowest threshold which is higher than the health of the entity.
• restoration_thresholds: These are tuples, ordered by percentage, holding restoration multipliers. The applied multiplier corresponds with the lowest threshold which is higher than the health of the entity.
• wear: damage which occurs from each use. Succeptable to multipliers.

Example

Restorable damage_thresholds = [(70.0%, 0.5), (100.0%, 0.2)] restoration_thresholds = [(40.0%, 0.0), (70.0%, 0.2), (100.0%, 0.3)] When 1 damage is done it results in 0.2 damage actually being applied. Should health drop to 70% or less, then 0.5 damage would be applied. This indicates the robustness at various levels of damage.

When 1 damage is restored it results in 0.3 damage actually being restored. Should health drop to 40% or below no damage is being restored. This indicates restorability. The last tier indicates a level of damage beyond which no restoration is possible anymore.

struct SuMSy

Representation of the parameters of a SuMSy implementation.

• id: a unique id.
• guaranteed_income: the periodical guaranteed income.
• demfreebuffer: the demurrage free buffer which is allocated to all accounts which have a right to a guaranteed income.
• dem_settings: the demurrage tiers. This is a list of tuples consisting of a lower bound and a demurrage percentage. The demurrage percentage is applied to the amounts above the lower bound up to the the next higher lower bound. If the demurrage free buffer of an account is larger than 0, all bounds are shifted up with this amount and no demurrage is applied to the amount up to the available demurrage free buffer.

The lower bound of the first tuple is always set to 0.

• interval: the size of the period after which the next demurrage is calculated and the next guaranteed income is issued.
• seed: the amount whith which new accounts start.

SuMSy(guaranteed_income::Real,
        dem_free::Real,
        dem_settings::DemSettings,
        interval::Integer;
        seed::Real = 0,
        seed_comment = "Seed",
        guaranteed_income_comment = "Guaranteed income",
        demurrage_comment = "Demurrage",
        dep_entry = SUMSY_DEP,
        dem_free_entry = nothing)

Create a SuMSy struct with a default id. The id is set to :sumsy-uuid where uuid is generated by uuid4().

SuMSyOverrides

SuMSy overrides to be used for individual balances.

Transaction

A timestamped list of atomic transactions which have been executed in batch.

Transaction(timestamp::Integer, type::EntryType, entry::BalanceEntry, amount::Real, result::Real, comment::String)

Creates a Transaction with 1 Atomictransaction.

Transfer

Used when working with transactions. All transfers in a transaction must succeed for the transaction to succeed.

• source: the source of the transfer.
• source_type: asset or liability.
• destination: the destination of the transfer.
• destination_type: asset or liability.
• amount: the amount that was transferred.
• entry: the BalanceEntry used in the transfer.
• comment

push!(needs::Needs,
        type::NeedType,
        bp::Blueprint,
        marginality::Marginality,
        priority::Integer = 0)

Adds a usage or want to the needs.

• type::NeedType - usage or want
• bp::B
• marginality::Marginality
• priority::Integer - default is 0.

Fixed

Convenience type for working with fixed point decimals.

book_amount!(entry::BalanceEntry,
            dict::Dict{BalanceEntry, Currency},
            amount::Real)

Books the amount. Checks on allowance of negative balances need to be made prior to this call.

book_asset!(balance::Balance,
            entry::BalanceEntry,
            amount::Real,
            timestamp::Integer = 0;
            comment::String = "")

# Returns
Whether or not the booking was succesful.

book_liability!(balance::Balance,
                entry::BalanceEntry,
                amount::Real,
                timestamp::Integer = 0;
                comment::String = "")

    # Returns
    Whether or not the booking was succesful.

borrow(creditor::Balance,
    debtor::Balance,
    amount::Real,
    interest_rate::Real,
    installments::Integer,
    timestamp::Int64 = 0;
    bank_loan::Bool = true,
    money_entry::BalanceEntry = DEPOSIT,
    debt_entry::BalanceEntry = DEBT,
    negative_allowed::Bool = true)

Create a debt contract between 2 balance sheets and adjust the balance sheets according to the parameters of the debt contract.

• creditor: the balance sheet receiving the installments.
• debtor: the balance sheet from which the installments will be subtracted.
• amount: the amount to be borrowed.
• interest_rate: the interest rate on the debt.
• installments: the number of installments.
• interval: the interval between the installments.
• timestamp: the current timestamp.
• bank_loan: indicates whether the creditor is a bank. If this is true new money is created to supply the money to the debtor. If this is false, money is transferred from the creditor to the debtor.
• negative_allowed: When this is true, a debtor can lend out money even when it would result in the creditor's money entry becoming negative. Otherwise only the amount available will be lent out. In case of bank loans this is ignored.
• money_entry: the balance sheet entry to be used to book the borrowed money.
• debt_entry: the balance sheet entry to be used to book the debt.

calculate_demurrage(balance::Balance, sumsy::SuMSy, step::Int)

Calculates the demurrage due at the current timestamp. This is not restricted to timestamps which correspond to multiples of the SuMSy interval.

check_booking(entry::BalanceEntry,
            dict::Dict{BalanceEntry, Currency},
            amount::Real)

Returns

True if the booking can be executed, false if it violates minimum value constrictions.

clear!(balance::Balance)

Sets all assets and liabilities to 0.

convert_thresholds

Converts threshold input into Threshold intervals. Intervals are created for each tuple in the input. All intervals are halfopen. When the direction is up they are closed on the lower bound and open on the upper bound. When the direction is down they are open on the lower bound and closed on the upper bound. The lowest bound is always 0 and the highest bound is always 1. The edges 0 and 1 are always closed.

damage(lifecycle::Union{Lifecycle, Nothing}, amount::Real)

Returns adjusted health.

entry_value(dict::Dict{BalanceEntry, Currency},
            entry::BalanceEntry)

get_initial_dem_free(balance::Balance, sumsy::SuMSy)

Returns the initial size of the demurrage free buffer.

get_maintenance_interval(lifecycle::Union{Lifecycle, Nothing})

Return the maintenance interval

get_production_output(actor::Actor)

Get the set of all blueprints produced by the actor.

maintain!(lifecycle::Union{Lifecycle, Nothing}, health::Health, resources::Entities)

Fields

• lifecycle
• health
• resources

Returns weather or not maintenance was succesful and waste products from used resources, if any.

maintenance_due(lifecycle::Union{Lifecycle, Nothing}, uses::Integer)

Fields

• lifecycle
• uses

Return whether is not maintenance is due based on the number of uses.

make_marginal(actor::Actor, needs::Needs)

Fields

• actor::Actor
• needs::Needs

make_tiers(dem_settings::Vector{T}) where  {T <: Tuple{Real, Real}}

Convert the vector of tuples into DemTiers. The first interval always starts with 0, the last interval always has an unbounded upper bound. Tiers are sorted from low to high.

num_entities(entities::Entities, bp::Blueprint)

pay!(buyer::Balance,
    seller::Balance,
    price::Price,
    timestamp::Integer;
    comment::String = "")

Returns

A boolean indicating whether the price was paid in full.

process(marginality::Marginality, units::Int64)

Determines the marginal number of units, given a current number of units. As long as the check for a supplementary unit returns true, another check will be executed for yet another unit.

Example:

Given a marginality: [(2, 1.0), (5, 0.5)]

Tuples denote a number of units and the probability an extra unit if the available number of units is less than the given number. In the example above the probability for the first unit is 100% if no units are available. A check for a second unit is executed and since the probability for this is also 100%, a check for a third unit is executed. The probability for a third unit is 50% (2 units are available thus the next tuple is used). If this check results in a third unit, a check for a fourth unit will be made and so on. Once 5 units are available the check will always return false in this example and therefor the maximum number of units is 5.

Returns

The number of marginal units.

process_needs(needs::Needs
            type::NeedType,
            posessions::Entities = Entities())

Get a vector of all the needs of the actor of the specified need type. The vector contains named tuples {blueprint::Blueprint, units::Int}. If the need type is prioritised the list is in order of priority, otherwise it is randomized.

process_ready(sumsy::SuMSy, step::Int)

Check whether processing needs to be done.

process_sumsy!(balance::Balance, sumsy::SuMSy, step::Int)

Processes demurrage and guaranteed income if the timestamp is a multiple of the SuMSy interval. Otherwise this function does nothing. Returns the deposited guaranteed income amount and the subtracted demurrage. When this function is called with timestamp == 0, the balance will be 'seeded'. The seed amount is added to the returned income.

• sumsy: the SuMSy implementation to use for calculations.
• balance: the balance on which to apply SuMSy.
• timestamp: the current timestamp. Used to determine whether action needs to be taken.

process_usage(needs::Needs)

Determine the items the actor wants to use. This in independant on the actual items in posession of the actor.

process_wants(needs::Needs, posessions = Entities())

Determine the items the actor wants, base on the items in posession of the actor.

produce!

Produces batch based on the producer and the provided resouces. The maximum possible batch is generated. The uses resources are removed from the resources Dict and produced Entities are added to the products Dict.

Returns

A named tuple {products::Entities, resources::Entities, batches::Int64} where

• products = produced entities
• resources = leftover resources
• batches = number of produced batches

produce_stock!(actor::Actor)

Resupply stocks as needed.

queue_transfer!(balance1::Balance,
            type1::EntryType,
            balance2::Balance,
            type2::EntryType,
            entry::BalanceEntry,
            amount::Real,
            timestamp::Integer = 0;
            comment::String = "")

Queues a transfer to be executed later. The transfer is queued in the source balance.

restorable(lifecycle::Union{Lifecycle, Nothing})

Indicates whether or not restoration is possible.

restore(lifecycle::Union{Lifecycle, Nothing}, resources::Entities)

Returns the adjusted health and the waste products from used resources, if any.

set_sumsy_active!(balance::Balance, sumsy::SuMSy, flag::Bool)

Indicate whether the balance participates in the specified SuMSy or not.

sumsy_transfer(source::Balance,
                destination::Balance,
                sumsy::SuMSy,
                amount::Real,
                timestamp::Int = 0;
                comment = "")

Transfer an amount of SuMSy money from one balance sheet to another. No more than the available amount of money can be transferred. Negative amounts result in a transfer from destination to source.

transfer!(balance1::Balance,
        type1::EntryType,
        balance2::Balance,
        type2::EntryType,
        entry::BalanceEntry,
        amount::Real,
        timestamp::Integer = 0;
        comment::String = "")

transfer!(balance1::Balance,
        type1::EntryType,
        entry1::BalanceEntry,
        balance2::Balance,
        type2::EntryType,
        entry2::BalanceEntry,
        amount::Real,
        timestamp::Integer = 0;
        comment::String = "")

transfer_asset!(balance1::Balance,
                balance2::Balance,
                entry::BalanceEntry,
                amount::Real,
                timestamp::Integer = 0;
                comment::String = "")

transfer_asset!(balance1::Balance,
                entry1::BalanceEntry,
                balance2::Balance,
                entry2::BalanceEntry,
                amount::Real,
                timestamp::Integer = 0;
                comment::String = "")

transfer_dem_free!(source::Balance, destination::Balance, amount::Real)

Transfer a part or all of the demurrage free buffer from one balance to another. No more than the available demurrage free buffer can be transferred.

• source::Balance - the balance from which the demurrage free amount is taken.
• destination::Balance - the balance to which the demurrage free buffer is transferred.
• amount::Real - the amount to be transferred.
• return - whether or not the transaction was succesful.

transfer_liability!(balance1::Balance,
                    balance2::Balance,
                    entry::BalanceEntry,
                    amount::Real,
                    timestamp::Integer = 0;
                    comment::String = "")

transfer_liability!(balance1::Balance,
                    entry1::BalanceEntry,
                    balance2::Balance,
                    entry::BalanceEntry,
                    amount::Real,
                    timestamp::Integer = 0;
                    comment::String = "")