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:

   POSIX

   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, first install the documentation requirements seen in the previous section.

You can build the documentation locally by navigating to the /doc directory and running the following commands:

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