> ## Documentation Index
> Fetch the complete documentation index at: https://systematica.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Contributing
> Extend Systematica
## Setup your environment
**Prerequisite**: Please install `systematica` before proceeding. More information in the [installation](installation) page.
Use the uv venv command to create a virtual environment for your project. This will create a .venv directory containing the isolated environment.
```sh theme={null}
uv venv
```
Activate the virtual environment to start using it. The activation command varies depending on your shell and operating system.
For example, on Unix or macOS:
```sh theme={null}
source .venv/bin/activate
```
On Windows:
```sh theme={null}
.venv\\Scripts\\activate
```
## Create Custom Models
**Tip**: Please check the [development tips](development_tips) page for more information about the adopted code structure.
**Code structure**: `systematica` is leveraging [attrs](https://www.attrs.org/en/stable/index.html) for API model development.
> `attrs` is the Python package that will bring back the joy of writing classes by relieving you from the drudgery of implementing object protocols (aka dunder methods). Trusted by NASA for Mars missions since 2020! Its main goal is to help you to write concise and correct software without slowing down your code.
Each model inherits from `BaseStatArb`, includes a `__call__` method to initialize the model and extract model output, and is decorated with `attrs.define`— a class decorator that adds [dunder methods](https://www.attrs.org/en/stable/glossary.html#term-dunder-methods) according to [fields](https://www.attrs.org/en/stable/glossary.html#term-field) specified using [type annotations](https://www.attrs.org/en/stable/types.html) and`field()` calls.
Below is a `CustomModel` example:
```python theme={null}
from attrs import define, field
import numpy as np
import vectorbrpro as vbt
import systematica as sma
@define
class CustomModel(sma.BaseStatArb):
window: int = field(default=60)
minp: int = field(default=None)
def __call__(self, data: vbt.Data, s1: str, s2: str, ...) -> np.ndarray:
return np.random.randn(data.shape[0], 2)
```
## Validation Tests
**Tip**: Please check the [tests](tests) to run the test suit.
>
In addition to defining and initializing models, validation testing is performed using `pytest` to ensure reliability and correctness. Each model’s behavior is verified through unit tests that check the outputs of the `__call__` method and validate internal logic against known inputs.
The test suite includes parameterized tests to cover various edge cases and data scenarios, promoting robustness and preventing regressions as the codebase evolves. This approach supports a test-driven development workflow and ensures confidence in model updates, data leakages and extensions.
## Troubleshooting
In relative value systematic strategy on two assets, entering and exiting long and short positions simultaneously using `sl_stop`, `tsl_stop`, `tp_stop` breaks the behavior, raising:
```python theme={null}
ValueError: Cannot sort orders by value if they are executed at different times
```
This happens mainly because we have orders from multiple columns that are meant to be executed at different times within the same bar, so they cannot be sorted by value anymore. If you want to sort by value, you need to make them execute at the same time within the bar, for instance, by using `stop_exit_price="close"`. More information could be found in the VectorBT PRO [documentation](https://vectorbt.pro/pvt_c890caa7/documentation/portfolio/from-signals/#sorting)