Using the Development Flow#

Developing tidy3d with poetry#

poetry is an incredibly powerful tool for reproducible package development environments and dependency management. TODO add link.

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

cd tidy3d/
poetry install -E 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 poetry there is a guarantee of using the reproducible locked environment.

poetry with an external virtual environment#

It is recommended to use poetry 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 poetry managed environment with the freedom of a standard virtual environment. There are a few more instructions and explanations in the poetry env docs . F See the following example:

mamba create -n tidy3denv python==3.10 # create venv with mamba
mamba activate tidy3denv # activate the venv
poetry env use python # using the mamba venv python now
poetry env info # verify the venvs used by poetry and mamba
cd anywhere
# you can use the python activated venv anywhere.

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.

poetry run tidy3d develop benchmark-timing-operations -c <timing_command>

Build documentation on reproducible environment

poetry run tidy3d develop build-docs

Build documentation with latest remote notebooks

It is defaulted to the develop branch of the tidy3d-notebooks repository.

poetry run tidy3d develop build-docs-remote-notebooks

Complete notebooks + base testing of the tidy3d

Make sure you have the notebooks downloaded.

poetry 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)

poetry run tidy3d develop convert-all-markdown-to-rst

Running pytest commands inside the poetry environment.

Make sure you have already installed tidy3d in poetry and you are in the root directory.

poetry run pytest

Run coverage testing from the poetry environment.

poetry run coverage run -m pytest

Standard testing of the tidy3d frontend

Make sure you have already installed tidy3d in poetry and you are in the root directory.

poetry run tidy3d develop test-base

Using tidy3d develop commands inside the poetry environment.

Make sure you have already installed tidy3d in poetry

poetry run tidy3d develop <your command>

Update lockfile after updating a dependency in pyproject.toml

Remember to install after this command.

poetry lock

Update and replace all the docstrings in the codebase between versions

poetry run tidy3d develop replace-in-files