Developer guides – How to add...

On this page, short introductions and guides aim at helping developers when adding new features to the framework.

• Marketplace
• Vendor
• CLI argument
• Default file

Marketplace

After adding the new marketplace class, please remember to update this list accordingly.

To add a new marketplace class, you first need to determine the general category it will belong to:

• Linear economy
• Circular economy
• Circular economy with rebuy prices
• A new economy type

If you choose to add a completely new economy type, the task will be a lot more complex, so we will not cover this scenario in this guide.

In the following, we will cover how to add a new circular economy class, but the general idea is the same for all marketplaces.

First, you need to navigate to the market/linear/linear_sim_market.py file. In here, you can already see all of the current market classes for circular economies, so simply add your new class to the bottom. Please make sure to conform to our naming scheme for marketplace classes:

<FullMarketType><FullMarketEnvironment><AdditionalInfo>

Currently, there are only two methods you need to implement for your new class:

• get_num_competitors(), a static method that defines how many competitors, other than the first agent can play on this market.
• _get_competitor_list(), a method that returns a list of pre-initialized vendors that should act as the default competitors on this market if no competitors are provided by the user.

Over time, it might of course be that more methods are required to be implemented, so if you find that on is missing from this list, kindly update it.

Aside from implementing the required methods, you can of course also overwrite existing methods defined in one of the parent classes. For this, take a look at the SimMarket class in market/sim_market.py. You might for example want to implement a custom behaviour for how and when customers arrive in your new market by overriding the _simulate_customers() method.

Vendor

There are two types of vendors in the framework, and the way they are implemented is radically different. Please refer to the correct section below when adding a new vendor class.

Reinforcement learning agent

After adding the new agent class, please remember to update this list accordingly.

There are two ways of adding a new reinforcement learning algorithm to the framework:

• Implementing a new algorithm "from scratch" - to be honest, when opting for this option, you will probably not need the guidance we could offer in this guide, so we will not concern ourselves with this scenario.
• Adding a pre-implemented algorithm, such as those from StableBaselines3.

For the second possibility, you can oriet yourself on how we imported our StableBaselinesAgents into the framework, see the files contained in the rl/stable_baselines folder.

When importing from a completely new library, take a look at stable_baselines_model.py and see which parts you might be able to reuse to adapt the new algorithm to our framework structure.

When importing a new algorithm from the StableBaselines family, simply take a look at one of the sb_<algorithm>.py files t see how easy it is to add the new algorithm. Simply make sure to initialize the agent correctly and to provide the correct parameters in the get_configurable_fields() method, which defines which parameters are accepted and required in the corresponding rl_config.json file.

Rule based vendor

After adding the new agent class, please remember to update this list accordingly.

When adding a new rule based vendor, similarly to the process when adding a new marketplace, you first need to decide on the the marketplace this vendor should operate on:

• Linear economy
• Circular economy
• Circular economy with rebuy prices

Let's assume you want to add a new vendor for the circular economy with rebuy prices. Go to market/circular/circular_vendors.py and add your new class at the bottom of the page. Please again conform to our naming scheme:

<RuleBasedType><MarketType(Short)>Agent<AdditionalInfo>

As you can see, this naming scheme is a bit more complex than the one for the marketplace classes. Simply take a look at the names of the already existing agents to understand better.

You will need to implement the following two methods for your new vendor class:

• __init__(), this is pretty straightforward and can be adapted from pre-existing classes.
• policy(), this is the core method of your new vendor class. It is responsible for calculating and returning the next action to be taken by the vendor, given a certain market state (observation).

That's it, your new rule based vendor can now be used as a competitor in the various tasks, or can be set as a default competitor for one of the marketplaces.

CLI argument

To add a new argument to our CLI, first navigate to the main.py file. All functions other than the main() are utility functions that are used by one or more of the existing CLI arguments.

Within the main() function, you can add your new argument adding it to the parser, using parser.add_argument(). Orient yourself on the existing commands for the parameters needed by the function, or refer to the argparse documentation.

After having defined the new argument, you need to define what happens when it is called by the user, which can be done anywhere after the line containing args = parser.parse_args().

Default file