fractal.core.base package

Subpackages

Submodules

fractal.core.base.action module

class fractal.core.base.action.Action(action: str, args: ~typing.Dict = <factory>)[source]

Bases: object

Action to be executed by the simulation engine. It contains the action name and arguments that matching for method name and it’s argumetns.

action: str - action name to execute (method name) args: Dict - action arguments (method arguments)

Example:

` action = Action("buy", {"price": 100, "quantity": 10}) some_entity.execute(action) # it will call some_entity.action_buy(price=100, quantity=10) `

action: str
args: Dict

fractal.core.base.entity module

class fractal.core.base.entity.BaseEntity[source]

Bases: ABC

Base class for entities. Entities are responsible for managing their internal state and executing actions. Each entity has a global state and internal state. The global state is the state of the environment, and the internal state is the state of the entity.

Each entity is a representation of DeFi object. For instance, a pool, a landing, a vault, etc.

Important Note: Each method that starts with ‘action_’ is considered as an action that can be executed by the simulation engine.

Abstract Methods: - update_state(state: GlobalState, *args, **kwargs) -> None - Update the Global State of the entity. Here it can be calculated changes in the entity’s internal state based on the global state. For example, while the price of the asset changes, the value of the entity’s assets changes. - action_deposit(amount_in_notional: float) -> None - Deposit the specified amount in notional value into the entity. This is not mandatory for all entities but it can be useful for most of them. - action_withdraw(amount_in_notional: float) -> None - Withdraw the specified amount from the entity’s account. - balance - Property that returns the balance of the entity.

action_deposit(amount_in_notional: float) → None[source]

Deposits the specified amount in notional value into the entity. Most entities can store the cash balance in notional value.

Parameters:

  • amount_in_notional (float) – The amount to be

  • value. (deposited in notional)

action_withdraw(amount_in_notional: float) → None[source]

Withdraws the specified amount from the entity’s account. Most entities can store the cash balance in notional value.

Parameters:

  • amount_in_notional (float) – The amount to withdraw

  • value. (in notional)

abstract property balance: float
execute(action: Action) → Any[source]

Execute action on the entity.

get_available_actions() → List[str][source]

Get available actions for the entity.

Returns:

List of available actions.

Return type:

List[str]

property global_state: GlobalState
property internal_state: InternalState
abstract update_state(state: GlobalState, *args, **kwargs) → None[source]
exception fractal.core.base.entity.EntityException[source]

Bases: Exception

Exception raised for errors in the entity.

class fractal.core.base.entity.GlobalState[source]

Bases: object

Global state of the entity. It includes the state of the environment. For example, price, time, etc.

class fractal.core.base.entity.InternalState[source]

Bases: object

Internal state of the entity. It includes the internal state of the entity. For example, cash balance, positions, etc.

Module contents

class fractal.core.base.Action(action: str, args: ~typing.Dict = <factory>)[source]

Bases: object

Action to be executed by the simulation engine. It contains the action name and arguments that matching for method name and it’s argumetns.

action: str - action name to execute (method name) args: Dict - action arguments (method arguments)

Example:

` action = Action("buy", {"price": 100, "quantity": 10}) some_entity.execute(action) # it will call some_entity.action_buy(price=100, quantity=10) `

action: str
args: Dict
class fractal.core.base.ActionToTake(entity_name, action)

Bases: NamedTuple

action: Action

Alias for field number 1

entity_name: str

Alias for field number 0

class fractal.core.base.BaseEntity[source]

Bases: ABC

Base class for entities. Entities are responsible for managing their internal state and executing actions. Each entity has a global state and internal state. The global state is the state of the environment, and the internal state is the state of the entity.

Each entity is a representation of DeFi object. For instance, a pool, a landing, a vault, etc.

Important Note: Each method that starts with ‘action_’ is considered as an action that can be executed by the simulation engine.

Abstract Methods: - update_state(state: GlobalState, *args, **kwargs) -> None - Update the Global State of the entity. Here it can be calculated changes in the entity’s internal state based on the global state. For example, while the price of the asset changes, the value of the entity’s assets changes. - action_deposit(amount_in_notional: float) -> None - Deposit the specified amount in notional value into the entity. This is not mandatory for all entities but it can be useful for most of them. - action_withdraw(amount_in_notional: float) -> None - Withdraw the specified amount from the entity’s account. - balance - Property that returns the balance of the entity.

action_deposit(amount_in_notional: float) → None[source]

Deposits the specified amount in notional value into the entity. Most entities can store the cash balance in notional value.

Parameters:

  • amount_in_notional (float) – The amount to be

  • value. (deposited in notional)

action_withdraw(amount_in_notional: float) → None[source]

Withdraws the specified amount from the entity’s account. Most entities can store the cash balance in notional value.

Parameters:

  • amount_in_notional (float) – The amount to withdraw

  • value. (in notional)

abstract property balance: float
execute(action: Action) → Any[source]

Execute action on the entity.

get_available_actions() → List[str][source]

Get available actions for the entity.

Returns:

List of available actions.

Return type:

List[str]

property global_state: GlobalState
property internal_state: InternalState
abstract update_state(state: GlobalState, *args, **kwargs) → None[source]
class fractal.core.base.BaseStrategy(*args, params: BaseStrategyParams | Dict | None = None, debug: bool = False, **kwargs)[source]

Bases: ABC

Base class for strategies.

Strategies are responsible for predicting the next action to take based on the current state of the entities.

Abstract Methods:

set_up(*args, **kwargs): Register entities, load models, execute some initial actions. Important Note: This method is called while initializing the strategy. In child classes, if implemented, also should be called parent’s set_up. predict(*args, **kwargs) -> List[Action]: Predict the next action to take.

get_all_available_entities() → Dict[str, Type[BaseEntity]][source]

Get all available entities.

get_entity(entity_name: str) → BaseEntity[source]

Get an entity by name.

property logger: BaseLogger
property params: Dict
abstract predict(*args, **kwargs) → List[ActionToTake][source]

Predict the next action to take based on the current state of the entities.

Returns:

List of actions to take.

Return type:

List[Action]

register_entity(entity: NamedEntity) → None[source]

Register an entity for the strategy. It is used to keep track of the entities in the strategy. Each entity should have a unique name in entities registry of the strategy.

run(observations: List[Observation]) → StrategyResult[source]

Run the strategy on a sequence of observations. Execute self.step for each observation.

set_params(params: BaseStrategyParams | Dict) → None[source]

Set parameters for the strategy.

Parameters:

  • params (BaseStrategyParams | Dict) – Parameters for the strategy.

  • passed (If dict is)

  • BaseStrategyParams (it will be converted to)

  • values. (with the fields of the dictionary keys and)

abstract set_up(*args, **kwargs)[source]

Set up the strategy. Register entities, load models, etc.

step(observation: Observation)[source]

Take a step in the simulation by observations.

class fractal.core.base.BaseStrategyParams(data: Dict | None = None)[source]

Bases: object

Base class for strategy parameters. It is used to store hyperparameters of the strategy. It can be initialized by a dictionary.

exception fractal.core.base.EntityException[source]

Bases: Exception

Exception raised for errors in the entity.

class fractal.core.base.GlobalState[source]

Bases: object

Global state of the entity. It includes the state of the environment. For example, price, time, etc.

class fractal.core.base.InternalState[source]

Bases: object

Internal state of the entity. It includes the internal state of the entity. For example, cash balance, positions, etc.

class fractal.core.base.NamedEntity(entity_name, entity)

Bases: NamedTuple

entity: BaseEntity

Alias for field number 1

entity_name: str

Alias for field number 0

class fractal.core.base.Observation(timestamp: datetime, states: Dict[str, GlobalState])[source]

Bases: object

Observation is a snapshot of the entities states at a given timestamp.