Logs

Log Base Class

class econsimulacra.logs.base.Log

Bases: object

Base class for simulation event logs.

A Log instance represents a single event that occurred during the simulation (e.g., agent generation, movement, consumption, orders, proposals, etc.).

In typical usage, agents or the environment create a log object and record it via read_and_write(). The logger stores logs in Logger.pending_logs until Logger.process_logs() is called, which dispatches each pending log to a handler and then clears the pending list.

read_and_write(logger)

Append this log to the logger’s pending logs.

Parameters:

logger (Logger) – The logger that stores pending logs.

Return type:

None

to_dict()

Convert this log object into a dictionary.

Returns:

The dictionary representation of the log.

Return type:

dict[str, object]

class econsimulacra.logs.base.AgentGenerationLog(time, time_step, agent_id, agent_type, agent_name, wealth, inventory_dic, persona_dic)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• agent_id (int)

• agent_type (str)

• agent_name (str)

• wealth (float)

• inventory_dic (dict[str, float | int])

• persona_dic (dict[str, Any] | None)

to_dict()

Convert this log object into a dictionary.

Overrides the base method to include inventory abd persona details.

Returns:

The dictionary representation of the log,

including inventory and persona details.

Return type:

dict[str, object]

class econsimulacra.logs.base.SpaceAssignLog(agent_id, pos)

Bases: Log

Parameters:

• agent_id (int)

• pos (tuple[int, ...])

class econsimulacra.logs.base.MoveLog(time, time_step, agent_id, old_pos, new_pos, init_pos)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• agent_id (int)

• old_pos (tuple[int, ...])

• new_pos (tuple[int, ...])

• init_pos (tuple[int, ...])

class econsimulacra.logs.base.ConsumptionLog(time, time_step, agent_id, item_name, item_amount)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• agent_id (int)

• item_name (str)

• item_amount (float | int)

class econsimulacra.logs.base.OrderLog(time, time_step, agent_id, counterparty_id, item_name, item_amount, price, order_id)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• agent_id (int)

• counterparty_id (int)

• item_name (str)

• item_amount (float | int)

• price (float | None)

• order_id (int | None)

class econsimulacra.logs.base.ProposalLog(time, time_step, proposal_id, proposer_agent_id, responder_agent_id, give_item_name, give_item_amount, get_item_name, get_item_amount)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• proposal_id (int)

• proposer_agent_id (int)

• responder_agent_id (int)

• give_item_name (str)

• give_item_amount (float | int)

• get_item_name (str)

• get_item_amount (float | int)

class econsimulacra.logs.base.OrderReactionLog(time, time_step, agent_id, counterparty_id, item_name, item_amount, price, order_id, accept_amount)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• agent_id (int)

• counterparty_id (int)

• item_name (str)

• item_amount (float | int)

• price (float)

• order_id (int | None)

• accept_amount (float | int)

class econsimulacra.logs.base.OrderExpirationLog(time, time_step, order_id)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• order_id (int)

class econsimulacra.logs.base.ProposalReactionLog(time, time_step, proposal_id, proposer_agent_id, responder_agent_id, give_item_name, give_item_amount, get_item_name, get_item_amount, accept)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• proposal_id (int)

• proposer_agent_id (int)

• responder_agent_id (int)

• give_item_name (str)

• give_item_amount (float | int)

• get_item_name (str)

• get_item_amount (float | int)

• accept (bool)

class econsimulacra.logs.base.ProposalExpirationLog(time, time_step, proposal_id)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• proposal_id (int)

class econsimulacra.logs.base.ChangePriceLog(time, time_step, agent_id, item_name, old_price, new_price)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• agent_id (int)

• item_name (str)

• old_price (float)

• new_price (float)

class econsimulacra.logs.base.TweetLog(time, time_step, agent_id, message, num_follows, num_followers)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• agent_id (int)

• message (str)

• num_follows (int)

• num_followers (int)

class econsimulacra.logs.base.FollowLog(time, time_step, agent_id, target_agent_id, num_follows, num_followers)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• agent_id (int)

• target_agent_id (int)

• num_follows (int)

• num_followers (int)

class econsimulacra.logs.base.UnfollowLog(time, time_step, agent_id, target_agent_id, num_follows, num_followers)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• agent_id (int)

• target_agent_id (int)

• num_follows (int)

• num_followers (int)

class econsimulacra.logs.base.StateEvaluationLog(time, time_step, agent_id, wealth, relative_wealth, buying_power, inventory_dic, persona_dic)

Bases: Log

Parameters:

• time (int | str)

• time_step (int)

• agent_id (int)

• wealth (float)

• relative_wealth (float | None)

• buying_power (float | None)

• inventory_dic (dict[str, float | int])

• persona_dic (dict[str, Any] | None)

to_dict()

Convert this log object into a dictionary. Overrides the base method to include inventory details.

Returns:

The dictionary representation of the log,

including inventory and persona details.

Return type:

dict[str, object]

class econsimulacra.logs.base.Logger

Bases: object

Store pending logs and process them.

The logger collects logs in pending_logs via write_log() (or Log.read_and_write()). When process_logs() is called, each log is dispatched to a handler selected from _dispatch_table by its class; otherwise _process_log_default() is used.

Subclasses can override handlers (e.g., _process_log_default) to implement custom behavior.

clear()

Clear all pending logs.

Return type:

None

write_log(log)

Append a log to the pending logs list.

Parameters:

log (Log)

Return type:

None

process_logs()

Process all pending logs.

Each log is dispatched to a handler selected from _dispatch_table by its class. If no handler is registered, _process_log_default() is used. After processing, pending_logs is cleared.

Return type:

None

save()

Return type:

None

Dictionary Logger

class econsimulacra.logs.dict_logger.DictLogger(txt_save_path=None)

Bases: Logger

Logger implementation that records processed logs in memory and optionally saves them.

Processed logs are serialized to dictionaries via Log.to_dict() and stored in self.logs. If txt_save_path is provided, save() writes the records in JSON Lines format to the specified path.

Parameters:

txt_save_path (Path | None)

save()

Save collected logs to txt_save_path in JSON Lines format.

Notes

• The parent directory is created if it does not exist.

Return type:

None