Contributing

PyLumerical follows the PyAnsys contribution guidelines. Ensure that you are familiar with the contents of this guide before contributing to PyLumerical.

The following section provides information for contributing to PyLumerical.

Installing PyLumerical in developer mode

Installing PyLumerical in developer mode allows you to modify the source and enhance it.

1. Start by cloning this repository:

   git clone https://github.com/ansys/pylumerical
   

2. Create a clean Python virtual environment:

   # Create a virtual environment
   python -m venv .venv
   

3. Activate the virtual environment:

   Linux

   source .venv/bin/activate
   

   Windows Command Prompt

   .venv\\Scripts\\activate.bat
   

   Windows Powershell

   .venv\\Scripts\\Activate.ps1
   

4. Install PyLumerical in editable mode:

   python -m pip install -U pip
   python -m pip install -e .
   

5. Install additional requirements as needed for documentation and tests:

   python -m pip install .[tests]
   python -m pip install .[doc]
   

Code style

Use pre-commit to ensure that your code meets the style requirements for PyLumerical prior to filing a pull request. The automatic CI/CD procedures uses the same checks as pre-commit, hence, it’s preferable to first run pre-commit locally.

To install pre-commit and check over all your files, run the following commands:

pip install pre-commit
pre-commit run --all-files

You can also set up pre-commit as a hook to automatically run before committing changes.

pre-commit install

Testing

PyLumerical uses pytest for testing.

To run tests, first install the test requirements seen in the previous section, and then run the following command in the root directory of the repository:

pytest --cov="<path_to_virtual_environment>\Lib\site-packages\ansys\api\lumerical" --cov="<pylumerical_repository>\tests\unit" --cov-report=html:coverage_report --verbose

Replace <path_to_virtual_environment> with the path to your virtual environment, and <pylumerical_repository> with the path to your local PyLumerical repository.

Documentation

PyLumerical uses reStructuredText and Sphinx for documentation.

Before building the documentation locally, first install the documentation requirements seen in the previous section. You don’t need additional dependencies unless you want to build the examples and cheatsheet locally.

By default, PyLumerical disables local builds of the examples and cheatsheet.

To enable them, first install the following dependencies:

• Examples: PyLumerical requires Pandoc to build the examples locally.

• Cheatsheet: PyLumerical requires Quarto and a LaTeX distribution, such as MiKTeX, to build the cheatsheet locally.

After installing the dependencies, enable local builds of the examples and cheatsheet by setting the following environment variables in your operating system:

• Examples: Set BUILD_PYLUMERICAL_EXAMPLES=TRUE to enable local builds of the examples.

• Cheatsheet: Set BUILD_PYLUMERICAL_CHEATSHEET=TRUE to enable local builds of the cheatsheet.

To build the documentation, navigate to the /doc directory and run:

Windows

.\\make.bat html

Linux

make html

The documentation is under the doc/_build/html directory.

You can also clean the documentation build directory by running:

Windows

.\\make.bat clean

Linux

make clean