Getting started

If you already have Python and Jupyter installed, you can launch a Jupyter instance in the root directory of the project by running jupyter notebook and then opening the notebook CarbonSim-Example.ipynb, or any of the other notebooks in that directory.

You may run into missing modules that need to be installed via pip. In this case, either install them manually based on the list in requirements.txt and requirements_ui.txt or refer to the instructions below. We also recommend to install JupyText.

Project setup

The project should be able to run in any Python3 environment with the correct dependencies installed via pip. If you start from a Conda installation, most dependencies should already be available. Nevertheless we recommend setting up a virtual environment to ensure libraries installed for this project do not collide with other Python modules installed on the system.

Whilst this simulation is designed to run in any Python environment, we strongly recommend running it in Jupyter Notebooks for the convenience they provide.

Method 1. Quick setup

Navigate to the top level project directory and start the Jupyter server:

$ jupyter notebook

Then run the notebook CarbonSim-Example.ipynb or any of the other notebooks. If you are getting import errors, make sure all modules from requirements.txt and requirements_ui.txt are installed, eg by running

$ pip install -r requirements.txt
$ pip install -r requirements_ui.txt

or by installing the required modules manually.

The upside of this method is that you get started quickly and easily, and -- more importantly -- you have access to all the bleeding feautures in the beta branch should you choose to check out beta instead of main. It also allows you to easily make changes to the library code. The downside is that the carbon library may only work for notebooks and scripts located in the root directory of this project.

Method 2. Pip install

We are publishing this repo to pypi:carbon-simulator so you can install it with the usual

$ pip install carbon-simulator

This installs the latest version published on the main branch of the repo, as well as all dependencies. We also recommend installing JupyText for easier management of the notebooks. In the unexpected case of conflicts with your local installation, consider using a virtual environment.

When installing this way there will not be any example workbooks provided. We recommend downloading the workbooks from here to get started, starting with CarbonSim-Example.ipynb. Note that you will only have access to the features in the main branch of the repo in this case.

Method 3. Installation via setup

This method will install the carbon package as well as all its dependencies on your system. We highly recommend to do this in a virtual environment, in which case no permanent changes will be made. To install the simulator, navigate to the top level project directory, and run the installation process via

$ python setup.py install

Then again you launch a Jupyter session running the following command

$ jupyter notebook

As the carbon library is now installed on your system, you can run the simulation code from anywhere whilst the virtual environment is active. Note that outside the project directory, you only have access the branch of the repo that was checked out at the time you ran setup. Inside the project director it should pick up whatever branch you have checked out, but this may depend on your system configuration.

Usage

There are numerous usage examples in the Jupyter notebooks in the root directory of this project, and we refer to those for more elaborate examples. A very basic example for a simulation is the one from CarbonSim-Example.ipynb:

from carbon import CarbonSimulatorUI

# Set up a simulator instance, with default pair ETHUSDC
Sim = CarbonSimulatorUI(pair="ETHUSDC")

# Add a strategy. This strategy is initially seeded with 10 ETH
# and 10000 USDC. It will selling ETH between 2000-2500 USDC per ETH,
# making the received USDC available for sale. It will also be buying ETH 
# between 1000-750 USDC per ETH.
Sim.add_strategy("ETH", 10, 2000, 2500, 10000, 1000, 750)

# We can look at this order by examining the simulator state
Sim.state()["orders"]

# Someone is now trading against the pool, BUYING 1 ETH.
# The price will be driven by the 2000-2500 range.
Sim.trader_buys("ETH", 1)

# We see that that 1 ETH disappeared from the ETH curve,
# and reappeared as USDC on the other curve
Sim.state()["orders"]

# Someone is trading against the pool, SELLING 1 ETH.
# The price will be driven by the 1000-750 range
Sim.trader_sells("ETH", 1)

# Now the ETH curve is at 10 ETH, where it was initially.
# We have however taken profits of about USD 2021 on the 
# USDC account.
Sim.state()["orders"]

Branches and versioning

Branches

This repo contains two key branches, main, and beta. Their respective properties are as follows:

• main. The main branch is the main release branch of this project, and this is the only branch that is available on PyPi. It is currently updated from beta every 1-2 weeks. The main branch will never be rewritten.

• beta. The beta branch contains the latest features of the project. It will have usually passed the test suite, so should not be broken in obvious ways. The beta branch will usually be rewritten before it is merged into main, which happens every 1-2 weeks.

Versioning

We use semantic versioning (major.minor.patch), so the major number is changed on backward incompatible API changes, the minor number on compatible changes, and the patch number for patches and incremental changes that do not merit an increase in the minor version number.

The API in this respect is defined as "all public methods in the SimulationUI" object, as well as those in the objects it returns (currently CarbonPair and CarbonOrderUI).

Note that all modules contained in carbon.helpers are not part of the public API, and breaking changes can occur in those at any point in time. If you are using them in your own code, we recomend copying the module(s) you are using into your own codebase.

The in-library location of those objects is not part of the API, they need to be imported from the top level. There may be additional objects in the top-level of the library that are not currently considered part of the API. As of version 1.0, those objects are ExactRouterX0Y0N and analytics which we do not currently consider in a state suitable for semantic versioning.

Modules may have version numbers of their own. Those are mostly for use of the dev team and they do not follow any specific policies.

Change log

• 2.5 arbbot-related code [in tools; optimizer, cpc, univ3helper, arbgraphs]; benchmark
• v2.4.1 added resources/routing area; cleaned up resources; SDK encode, decode; CarbonOrderUI yzABS; removed deprecated notebooks; CPC serialization, constructors and plots; benchmark bugfix
• v2.4 README; CarbonOrderUI prettification; precision analysis; BaseRouter parameters as dict; benchmarks; SDK; HOURLY data set; SharedVar; ConstantProductCurve with reference NB063; additional parameters for CarbonOrderUI and as_cpc and reference book NB062; iseq; matching method test; CPCContainer
• v2.3.2 CarbonPair display, decimals; strategy from_dct improvements; sim-related helpers including soltest, floatint; CarbonOrderUI yzABS
• v2.3.1 cryptocompare; run_shift parameter fix; sim: colors and local use; ubuy/sell; various sim improvements; cryprocompare aggregate query; routing and benchmarking