Using the Development Flow

Developing tidy3d with uv

uv is an incredibly powerful tool for reproducible package development environments and dependency management.

If you are developing tidy3d, we recommend you work within the configured uv environment defined by uv.lock. The way to install this environment is simple:

cd tidy3d/
uv sync --frozen --extra dev

This function will install the package with all the development dependencies automatically. This means you should be able to run any functionality that is possible with tidy3d reproducibly.

It is important to note the function above is equivalent to pip install tidy3d[dev], but by using uv there is a guarantee of using the reproducible locked environment.

uv with an external virtual environment

It is recommended to use uv for package development. However, there are some cases where you might need to use an external virtual environment for some operations. There are a few workarounds where you can leverage the reproducibility of the uv managed environment with the freedom of a standard virtual environment. For more details, see the uv documentation. See the following example:

mamba create -n tidy3denv python==3.10 # create venv with mamba
mamba activate tidy3denv # activate the venv
cd tidy3d
uv sync --active --frozen --extra dev # sync to the currently active venv
uv run python -V # confirm commands run in that environment

There are also other methodologies of implementing common dependencies management.

Common Utilities

There are a range of handy development functions that you might want to use to streamline your development experience.

Use Cases

Description	Caveats	Command
Benchmark timing import of tidy3d	Verify the available timing tests by running the command without any arguments.	uv run tidy3d develop benchmark-timing-operations -c <timing_command>
Build documentation on reproducible environment		uv run tidy3d develop build-docs
Build documentation with latest remote notebooks	It is defaulted to the develop branch of the tidy3d-notebooks repository.	uv run tidy3d develop build-docs-remote-notebooks
Complete notebooks + base testing of the tidy3d	Make sure you have the notebooks downloaded.	uv run tidy3d develop test-all
Dual snapshot between the tidy3d and notebooks source and submodule repository.	Make sure you are on the correct git branches you wish to commit to on both repositories, and all non-git-ignored files will be added to the commit.	tidy3d develop commit <your message>
Interactively convert all markdown files to rst (replacement for m2r2)		uv run tidy3d develop convert-all-markdown-to-rst
Running pytest commands inside the uv environment.	Make sure you have already installed tidy3d in uv and you are in the root directory.	uv run pytest
Analyze slow pytest runs with durations / cProfile / debug subset helpers.	Use --debug to run only the first N collected tests or --profile to capture call stacks.	python scripts/profile_pytest.py [options]
Track pytest RAM usage over time and per test.	Defaults to pytest’s configured parallelism; use --single-process to disable xdist.	uv run python scripts/pytest_ram_profile.py [options]
Run coverage testing from the uv environment.		uv run coverage run -m pytest
Standard testing of the tidy3d frontend	Make sure you have already installed tidy3d in uv and you are in the root directory.	uv run tidy3d develop test-base
Using tidy3d develop commands inside the uv environment.	Make sure you have already installed tidy3d in uv	uv run tidy3d develop <your command>
Update lockfile after updating a dependency in pyproject.toml	Remember to install after this command.	uv lock
Update and replace all the docstrings in the codebase between versions		uv run tidy3d develop replace-in-files