Contribute#

Overall guidance on contributing to a PyAnsys library appears in Contributing in the PyAnsys Developer’s Guide. Ensure that you are thoroughly familiar with this guide before attempting to contribute to PyMechanical.

The following contribution information is specific to PyMechanical.

Install in developer mode#

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

Note

Before contributing to the project, ensure that you are thoroughly familiar with the PyAnsys Developer’s Guide.

To install PyMechanical in developer mode, perform these steps:

  1. Clone the pymechanical repository:

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

  2. Access the pymechanical directory where the repository has been cloned:

    cd pymechanical

  3. Create a clean Python virtual environment and activate it:

python -m venv .venv
.venv\Scripts\activate.bat

python -m venv .venv
.venv\Scripts\Activate.ps1

python -m venv .venv
source .venv/bin/activate

  1. Ensure that you have the latest required build system tools:

    python -m pip install -U pip tox flit twine

  2. Install the project in editable mode:

    # Install the minimum requirements
python -m pip install -e .

# Install the minimum + tests requirements
python -m pip install -e .[tests]

# Install the minimum + doc requirements
python -m pip install -e .[doc]

# Install all requirements
python -m pip install -e .[tests,doc]

  3. Verify your development installation:

    tox

Test PyMechanical#

PyMechanical uses PyTest and tox for unit testing.

Using tox#

This project takes advantage of tox. This tool automates common development tasks (similar to Makefile), but it is oriented towards Python development.

While Makefile has rules, tox has environments. In fact, tox creates its own virtual environment so that anything being tested is isolated from the project to guarantee the project’s integrity.

The following environment commands are provided:

  • tox -e style: Checks for coding style quality.

  • tox -e py: Checks for unit tests.

  • tox -e py-coverage: Checks for unit testing and code coverage.

  • tox -e doc: Checks for documentation-building process.

Without tox#

If required, from the command line, you can call style commands like black, isort, and flake8. You can also call unit testing commands like PyTest. However, running these commands do not guarantee that your project is being tested in an isolated environment, which is the reason why tools like tox exist.

Remote testing#

If you do not have a licensed copy of Mechanical installed locally but want to run PyMechanical unit tests on a remote instance, you must set up environment variables.

On Linux

export PYMECHANICAL_START_INSTANCE=False
export PYMECHANICAL_PORT=<MECHANICAL Port> (default 10000)
export PYMECHANICAL_IP=<MECHANICAL IP> (default 127.0.0.1)

On Windows

SET PYMECHANICAL_START_INSTANCE=False
SET PYMECHANICAL_PORT=<MECHANICAL Port> (default 10000)
SET PYMECHANICAL_IP=<MECHANICAL IP> (default 127.0.0.1)

The environment variables for your operating system tell PyMechanical to attempt to connect to the existing Mechanical service by default when you use the launch_mechanical() method.

Documentation#

For building documentation, you can run the usual rules provided in the Sphinx make file. Here is an example:

#  build and view the doc from the POSIX system
make -C doc/ html && your_browser_name doc/html/index.html

# build and view the doc from a Windows environment
.\doc\make.bat clean
.\doc\make.bat html
start .\doc\_build\html\index.html

However, the recommended way of checking documentation integrity is to use tox:

tox -e doc && your_browser_name .tox/doc_out/index.html

Distributing#

If you would like to create either source or wheel files, start by installing the building requirements and then executing the build module:

python -m pip install -U pip
python -m flit build
python -m twine check dist/*

Post issues#

Use the PyMechanical Issues page to submit questions, report bugs, and request new features. When possible, use these templates:

  • Bug report

  • Feature request

If your issue does not fit into one of these template categories, create your own issue.

To reach the project support team, email pyansys.core@ansys.com.

View documentation#

Documentation for the latest stable release of PyMechanical is hosted at PyMechanical Documentation.

In the upper right corner of the documentation’s title bar, there is an option for switching from viewing the documentation for the latest stable release to viewing the documentation for the development version or previously released versions.

Code style#

As indicated in Coding style in the PyAnsys Developer’s Guide, PyMechanical follows PEP8 guidelines. PyMechanical implements pre-commit for style checking.

To ensure your code meets minimum code styling standards, run these commands:

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

You can also install this as a pre-commit hook by running this command:

pre-commit install

This way, it’s not possible for you to push code that fails the style checks:

$ pre-commit install
$ git commit -am "added my cool feature"
black....................................................................Passed
isort....................................................................Passed
flake8...................................................................Passed
codespell................................................................Passed