Contributing

How to set up your development environment, run tests, and contribute to tsim.

Please see Installation for instructions on how to set up your development environment.

Pre-commit hooks

We use pre-commit to run formatting, linter and type checks before you commit your changes. The pre-commit hooks are installed as part of the development dependencies. You can set up pre-commit using the following command:

pre-commit install

If the checks fail, the commit will be rejected.

Running the tests

We use pytest for testing. To run the tests, simply run:

uv run pytest

Code style

We use black for code formatting. Besides the linter requirements, we also require the following good-to-have practices.

Naming

• try not to use abbreviation as names, unless it’s a common abbreviation like idx for index
• try not create a lot of duplicated name prefix unless the extra information is necessary when accessing the class object.
• use snake_case for naming variables and functions, and CamelCase for classes.

Comments

• try not to write comments, unless it’s really necessary. The code should be self-explanatory.
• if you have to write comments, try to use NOTE:, TODO: FIXME: tags to make it easier to search for them.

Documentation

We use just for managing command-line tools and scripts. It should be installed when you run uv sync. The documentation site is built with Mintlify; the local Mintlify CLI is installed separately via npm:

npm i -g mint

Once you have mint installed, run:

uv run just doc

This regenerates the API reference and tutorial MDX files via docs/build.py, then launches a local Mintlify preview. Use uv run just doc-quick to skip re-executing notebooks during iteration.