nqs_sdk.core.simulation module

class nqs_sdk.core.simulation.Simulation(protocols, config, namespace=None)

Bases: object

Main orchestrator for running simulations.

This class serves as the primary interface for users to configure, build, and execute simulations involving multiple DeFi protocols. It handles the coordination between protocol factories, configuration loading, and simulation execution.

Protocols and configuration are provided during initialization, and the simulation can be run multiple times with different parameters.

protocols

List of protocol factories or protocol factory adapters that define the DeFi protocols to simulate

config

Configuration data (file path, dict, or YAML/JSON content)

simulator

Internal rust-based simulator instance (built lazily)

__init__(protocols, config, namespace=None)

Initialize a new simulation with specified protocols and configuration.

Parameters:

• protocols (Union[ProtocolFactory, ProtocolFactoryAdapter, List[ProtocolFactory | ProtocolFactoryAdapter]]) – Single ProtocolFactory or ProtocolFactoryAdapter, or list of ProtocolFactorys or ProtocolFactoryAdapters defining the protocols to include in the simulation

• config (Union[str, dict, Path]) – Configuration for the simulation. Can be: - Path to a YAML/JSON configuration file - Dictionary containing configuration parameters - String containing YAML/JSON configuration content

Example

>>> from nqs_sdk import Simulation
>>> from nqs_sdk.protocols import UniswapV3Factory
>>> from nqs_sdk_extension.protocols import CompoundV2Factory
>>> uniswap = UniswapV3Factory()
>>> compound = CompoundV2Factory()
>>> sim = Simulation([uniswap, compound], "config.yaml")

get_protocol(protocol_id)

Retrieve a protocol instance by its identifier.

Parameters:

protocol_id (str) – Unique identifier for the protocol (e.g., “uniswap_v3”)

Return type:

Any

Returns:

The protocol instance corresponding to the given ID

Raises:

• RuntimeError – If simulation hasn’t been built yet

• KeyError – If protocol_id doesn’t exist in the simulation

Example

>>> uniswap_protocol = sim.get_protocol("uniswap_v3")
>>> current_price = uniswap_protocol.get_current_price()

run()

Execute the simulation and return results.

This method runs the entire simulation from start to end block/timestamp, processing all transactions and collecting metrics along the way.

Returns:

Object containing all simulation data including:

• Protocol states at each block

• Agent portfolio values over time

• Transaction logs and fees

• Observable metrics and KPIs

Return type:

SimulationResults

Raises:

RuntimeError – If simulation hasn’t been built yet

Example

>>> results = sim.run()
>>> portfolio_value = results.get_agent_metric("alice", "total_holding")