World and Settings

World

class sfctools.core.world.World(*args, **kwargs)

Bases: sfctools.core.singleton.Singleton

This is the world where agents live in. There can only be one world at a time.

The world constructor.

find_agent(name)

search for agent by name and alias

Returns

agent instance

get_agent_types()

Constructs a list of all agent types registered so far (i.e. keys of agent registry dict).

Return list

list of agents

get_agents_of_type(agent_type)

gets all agents belonging to a certain tpe

Parameters

agent_type – key to search for in self.agent_registry

Returns

list of instances or empty list

Example

from sfctools import Agent,World

class MyAgent(Agent):
    def __init__(self):
        super().init()
        # ...

[MyAgent() for i in range(10)] # create 10 agents

mylist = World().get_agents_of_type("MyAgent")
print(mylist)

link(verbose=False)

Calls the ‘link’ fun in all the agents to inter-link them in the world

read_global(key)

reads global variable by key

register_agent(agent, verbose=False)

inserts a new agent under the tag of its class

Parameters

agent – an agent object to be registered

register_helper(object)

inserts a new helper object under the tag of its class

Parameters

object – instance to store

remove_agent(agent, verbose=False)

removes an agent from the tag of its class (i.e. from the world)

Parameters

agent – instance to be removed

remove_helper(agent)

removes an agent from the tag of its class (i.e. from the world)

Parameters

agent – instance to be removed

reset(verbose=False)

resets the registry

Parameters

verbose – boolean (default False), triggers a reset warning if True

write_global(key, data)

write globally accessible data here

Parameters

• key – key for the data (generic)

• data – value of the data (generic)

Settings (yaml)

class sfctools.core.settings.Settings(*args, **kwargs)

Bases: sfctools.core.singleton.Singleton

This is a settings class that serves as a central data structure to store hyperparameters, commodity names, depreciation rates etc. It also includes a section with metadata on author etc…

constructor for settings

get_depr_info()

EXPERIMENTAL return info about assets and their depreciation rates

Returns

df, pandas dataframe with information about allowed assets

Example

from sfctools import Settings
dfinfo = Settings().get_info()
print(dfinfo)

get_hyperparameter(name)

get the value of a hyperparameter by its name.

Parameters

name – the name of the hyper-parameter to filter for

get_hyperparams_info()

return info about hyperparameters

Returns

df, pandas dataframe with information about allowed assets

Example

from sfctools import Settings
dfinfo = Settings().get_hyperparams_info()
print(dfinfo)

get_info()

read(data, isfile=True)

read the settings from a yaml file. The settings of a simulation can be stored in form of a yaml file. The first block metainfo stores the author, date and other meta data. The params block stores information on the assets allowed in balance sheets and their respective depreciation rates (0 means no depreciation, 1 means that the good is fully perishable). hyperparams contains parameters of agents stored centrally (for better overview). It also helps to avoid hardcoding of parameters directly in the code of the agents.

Parameters

• data – either str, i.e. a string containing the data, or path/str, i.e. file name to read from

• isfile – boolean switch. If False, a string has to be passed.

** Example **

“filename.yml” File:

metainfo :
    author: Hans Dampf
    date: Agust 1964
    info: some more info

params:
    - name: Cash
      depreciation: 0.0
      price: p
      value: 1.0
      unit: Euro
      description: my description

    - name: Energy
      ...

hyperparams:
    - name: epsilon
      value: 0.05
      description: my description

    - name:
      ...

Python code:

from sfctools import Settings
my_settings = Settings().read_from_yaml("filename.yml")

read_from_yaml(data, isfile=True)

reset()

reset settings

set_hyperparameter(name, value)

get the value of a hyperparameter by its name.

Parameters

• name – str, name of the parameter

• value – new value (any type but ideally same as before)

setup_stock_manager()

set up the stock manager from the data stored in the current settings. For more information on the stock manager, see StockManager class. This should not be called manually by the user. It is automatically called within ‘read_from_yaml()’.

write(fname)

Writes the settings to a filename as yaml file

Clock

class sfctools.core.clock.Clock(*args, **kwargs)

Bases: sfctools.core.singleton.Singleton

The clock of the simulation.

Init a world clock.

Parameters

• t0 – optional, starting date of the clock

• dt – optional, datetime.timedelta describing the real time step. Default is one month.

Example

from sfctools import Clock

for i in range(500):
    # simulation steps

    Clock().tick()
    print(Clock().get_time(), Clock().get_real_time())

get_real_time()

Get the real time (the actual time on the ‘non-simulation’ timeline) as datetime

get_time()

Gets the current simulation time as int

reset(verbose=False)

Resets the clock

Parameters

verbose – bool (default False), triggers a reset warning if True

property t0

tick()

Increases the clock tick by one

Stock Manager

class sfctools.bottomup.stock_manager.StockManager(*args, **kwargs)

Bases: sfctools.core.singleton.Singleton

The stock manager keeps track of all price trends. Beta feature…

constructor of stock manager.

get_index(name_of_commodity: str) → str

retrieve stock index by name of commodity

Parameters

name_of_commodity – name of the commodity

get_info() → pandas.core.frame.DataFrame

get stock information in a table

Returns

df, pandas dataframe

get_most_recent(name)

get the most recent value of a price index if there are no values, return None

Returns

t, v (time stamp and value of most recent update)

get_price(name, human=False)

see request_price

register(name: str, price_name: str, price_value: float) → None

run setup routine of stock manager for a new commodity

Parameters

• name – name of the commodity (eg. ‘coal’)

• price_name – name of the price (e.g. ‘P_c’)

• price_value – actual value of the price, this can also point to a method

request_price(name: str, human: bool = False) → float

Retrieve a price by the name of the index.

Parameters

• name – the name of the commodity, e.g. ‘coal’

• human – get price by the name of the commodity instead

Returns

P, value of the price at the stock

request_price_history(name: str, which: str = 'all', convert_df: bool = False, convert_dict: bool = False, human: bool = False)

get historical trace of a stock index

Parameters

• name – name of the commodity

• which – passing ‘all’ (default) will return all past values, passing ‘last’ will only return the two latest values. BETA works only in convert_dict mode

• convert_df – convert to dataframe? if False, a numpy array is returned instead (which is faster)

• convert_dict – convert to dictionary, where keys are time periods and values are the data values; the numpy array will be of shape [2,n] where [0,0…n-1] is the time stamp and [1,0….n-1] is the price data belonging to this time stamp

• human – get price history by the name of the commodity instead

Returns

df or dict

Example

from sfctools import Clock, StockManager
import numpy as np

for i in range(10):
    StockManagre().set_price("P_K",10.0 + np.random.rand())
    Clock().tick()

times, values = StockManager().request_price_history("P_K")
print(times)
print(values)

set_price(name: str, value: float, human: bool = False) → None

set a new price by name of the index commodity

Parameters

• name – name of the index to be set

• value – new value

• human – get price by the name of the commodity instead