コードを開発する#
バグを修正したり、新しい機能を開発したりすることで PyMAPDL の改善に貢献できます。どちらの場合も、以下のセクションの説明に従ってローカルマシンにリポジトリをセットアップする必要があります。
PyMAPDLリポジトリをクローンする#
PyMAPDLリポジトリをクローンする前に、Gitのようなバージョン管理システムをインストールする必要があります。次のコードを実行すると、PyMAPDLの最新の開発バージョンをクローンすることができます:。
git clone https://github.com/ansys/pymapdl
cd pymapdl
Pythonの仮想環境を作成する#
To avoid dependency conflicts and more easily manage upgrades, you should install PyMAPDL in its own virtual environment. For detailed information on how to install Python and create a virtual environment, see Setting up your development environment.
開発モードでPyMAPDLをインストールする#
以下のコマンドを使用して、最新バージョンのPyMAPDLを開発モードでインストールします:
cd pymapdl
pip install pip -U
pip install -e .
もしテストを行うのであれば、以下のコマンドでテスト用の依存関係をインストールする必要があります:
pip install -e '.[tests]'
PyMAPDL を開発する#
今こそPyMAPDLを開発する時です!
リポジトリでコードを開発する場合、特に Git のようなバージョン管理システムを使う場合は、効率的な共同作業、コード管理、変更の追跡を確実にするために、一連の重要なガイドラインが必要になります。以下は、リポジトリでコードを開発するための主なガイドラインです:
Use branches: Create branches for different features, bug fixes, or experiments. This keeps changes isolated and facilitates parallel development. The CI/CD checks that the branch name is compliant. For example, the branch name must start with a lower case prefix and a backslash. The allowed prefixes are:
build/ - Changes that affect the build system or external dependencies (such as to
pip
ormake
).ci/ - Changes to the CI/CD configuration files and scripts.
dependabot/ - Created by Dependabot.
docs/ - Improves documentation and examples.
feat/ - Changes that introduce a new feature or significant addition.
fix/ - Bug fixes.
junk/ - Other purposes. It should not be used for branches that are going to be merged to
main
.maint/ - General maintenance of the repository.
no-ci/ - (Not applicable to PyMAPDL) In some repositories, branches with this prefix do not trigger CI/CD.
perf/ - A code change that improves performance.
refactor/ - A code change that neither fixes a bug nor adds a feature.
release/ - Contains the released versions changes.
revert/ - Reverts a previous commit.
testing/ - For testing and debugging. It can be used to add new tests.
Note: For more information, see Table of allowed prefix.
説明的なコミットメッセージを書く: 変更の目的と背景を説明する、明確で簡潔なコミットメッセージを書きましょう。 一貫したスタイルに従ってください。
build: - Changes that affect the build system or external dependencies (such as to
pip
ormake
).chore: - Other changes that don't modify the code. It can be used as a fall back general branch name.
ci: - Changes to the CI/CD configuration files and scripts.
docs: - Improves documentation and examples.
feat: - Changes that introduce a new feature or significant addition.
fix: - Bug fixes.
maint: - General maintenance of the repository.
no-ci: - (Not applicable to PyMAPDL) In some repositories, branches with this prefix do not trigger CI/CD.
perf: - A code change that improves performance.
refactor: - A code change that neither fixes a bug nor adds a feature.
release: - Contains the released versions changes.
revert: - Reverts a previous commit.
style: - Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc).
testing: - For testing and debugging. It can be used to add new tests.
Note: For more information, see Table of allowed prefix.
頻繁にコミットする: 小さくて意味のあるコミットを頻繁に行う。1回のコミットで無関係な変更を大量に行うことは避けましょう。
プッシュする前にプルしてください: 競合を避けるため、自分の変更をプッシュする前に、常にリモートリポジトリの最新の変更でローカルブランチを更新してください。
Use pull requests (PRs): Use PRs to submit your changes for review. This allows for discussion and validation before merging into the main branch. Pull requests must follow the same convention as the commit messages. The following prefixes are allowed in the pull request names:
build: - Changes that affect the build system or external dependencies (such as to
pip
ormake
).ci: - Changes to the CI/CD configuration files and scripts.
docs: - Improves documentation and examples.
feat: - Changes that introduce a new feature or significant addition.
fix: - Bug fixes.
maint: - General maintenance of the repository.
no-ci: - (Not applicable to PyMAPDL) In some repositories, branches with this prefix do not trigger CI/CD.
perf: - A code change that improves performance.
refactor: - A code change that neither fixes a bug nor adds a feature.
revert: - Reverts a previous commit.
testing: - For testing and debugging. It can be used to add new tests.
Note: For more information, see Table of allowed prefix.
The pull requests can also be labeled for easier repository maintenance. The CI/CD automatically labels each pull request based on the pull requests prefix and the modified files, but you can also add extra labels as long as they are already defined in the repository.
Write good documentation: Maintain clear and up-to-date documentation for your contribution or changes, including comments in code, and relevant project documentation in rST or Markdown files. If you implement a new feature or change the behaviour of the library in any way, remember to mention it somewhere in the documentation (rST files in
docsource
directory) Follow the numpydoc convention for documenting code.変更をテストしてください: 変更が期待通りに動作するよう、徹底的にテストする。該当する場合は、継続的インテグレーション/継続的デプロイメント(CI/CD)パイプラインで実行されるユニットテストを作成または更新して、問題を早期に発見し、信頼性の高いデプロイメントを保証します。詳細については、 Unit testing を参照してください。
Respect code style and standards: Follow code style guidelines and adhere to coding standards specific to your language or framework.
Collaborate and communicate: Communicate with team members, provide updates on your progress, and resolve any conflicts promptly.
Ask for help: To ensure code quality, identify issues, and share knowledge, ask PyMAPDL developers to assist you and review your code. If you need help or guidance, mention
@ansys/pymapdl-maintainers
in a comment so they they are notified.
By following these guidelines, you can ensure smooth and organized code development within a repository, fostering collaboration, code quality, and feature enhancement.
Table of allowed prefix
Prefix |
Commit ( |
Branch ( |
Pull-request ( |
---|---|---|---|
build |
✅ |
✅ |
✅ |
dependabot |
❌ |
✅ |
❌ |
chore |
✅ |
❌ |
❌ |
ci |
✅ |
✅ |
✅ |
docs |
✅ |
✅ |
✅ |
feat |
✅ |
✅ |
✅ |
fix |
✅ |
✅ |
✅ |
junk |
❌ |
✅ |
❌ |
maint |
✅ |
✅ |
✅ |
no-ci |
✅ |
✅ |
✅ |
perf |
✅ |
✅ |
✅ |
refactor |
✅ |
✅ |
✅ |
release |
✅ |
✅ |
✅ |
revert |
✅ |
✅ |
❌ |
style |
✅ |
❌ |
❌ |
testing |
✅ |
✅ |
❌ |
Where:
✅ means that the prefix is allowed.
❌ means that the prefix is not allowed.
ユニットテスト#
Unit tests validate the software by testing that the logic implemented inside a certain method, class, or module is working as expected. They should be as atomic and independent as possible.
Unit testing is highly important. The tests verify that code changes are consistent with other parts of the code and verify that these changes are implemented properly.
In the PyMAPDL repository, pytest is used to run tests and the unit tests are in the tests directory in this repository, along with integration tests. The difference between a unit test and an integration test is that the latter tests several units of the code to ensure that they all work together.
To run all the unit tests use the following command:
(.venv) mapdl@machine:~/pymapdl$ pytest
If you are running on a Linux machine without display, you must install xvfb
OS
library and run the preceding command with the xvfb-run
command as prefix.
(.venv) mapdl@machine:~/pymapdl$ xvfb-run pytest
In case you want to run only a certain subset of tests, you can use the -k
argument
to filter the tests using booleans:
(.venv) mapdl@machine:~/pymapdl$ pytest -k "test_nlist_to_array or test_string_with_literal"
==================================================== test session starts ====================================================
platform darwin -- Python 3.10.13, pytest-7.4.3, pluggy-1.3.0
rootdir: /Users/german.ayuso/pymapdl
configfile: pyproject.toml
testpaths: tests
plugins: timeout-2.2.0, cov-4.1.0, sphinx-0.5.0, rerunfailures-13.0, anyio-4.1.0, pytest_pyvista-0.1.9
collected 1468 items / 1466 deselected / 4 skipped / 2 selected
tests/test_commands.py .. [100%]
=============================================== PyMAPDL Pytest short summary ================================================
======================================= 2 passed, 4 skipped, 1466 deselected in 2.27s =======================================
Creation of a unit test#
The name of a pytest
file must be in the form test_XXX.py
, where XXX
is either the function, method, or class that you are testing or some other explicative
name. In the command line, you can use the -k
argument to filter the tests to run.
For more information, see pytest usage.
Here are some guidelines for creating good unit tests:
テストに長くて分かりやすい名前を付ける。
Use the Codecov tool to ensure that all implemented code is tested.
Check that tests return the same results each time.
テストが独立していることを確認する。
Write tests that verify only one part of the code at a time.
Make tests as short and fast as possible.
What makes a good unit test? is an exhaustive list of tips for creating good unit tests.
Most PyMAPDL tests require a connection to a running instance of MAPDL, which makes them integration tests. If your test requires a running MAPDL instance, you can use the PyMAPDL mapdl method in your function signature. It is executed upstream of each test and not within all tests.
def test_my_new_feature(mapdl, cleared): # pass the 'mapdl' fixture as an argument.
mapdl.prep7()
# .... more code
return True # if everything goes ok until here
Passing the cleared
fixture is also useful since it clears up the MAPDL database
and configuration before performing the test.
If you do not have MAPDL installed locally but still want to run the
unit testing, you must set up the following environment variables.
SET PYMAPDL_START_INSTANCE=False
SET PYMAPDL_PORT=<MAPDL Port> (default 50052)
SET PYMAPDL_IP=<MAPDL IP> (default 127.0.0.1)
export PYMAPDL_START_INSTANCE=False
export PYMAPDL_PORT=<MAPDL Port> (default 50052)
export PYMAPDL_IP=<MAPDL IP> (default 127.0.0.1)
These environment variables tell PyMAPDL to attempt to connect to the existing
MAPDL service by default when the launch_mapdl
function is used.
Additionally, you can use the PYMAPDL_MAPDL_EXEC
and PYMAPDL_MAPDL_VERSION
environment variables to specify the MAPDL executable path and the version to launch (if
multiple versions of MAPDL are installed).
Continuous integration and continuous deployment#
Unit tests and integration tests are part of continuous integration (CI). The automation of testing, monitoring, and deployment of newly added code allows continuous deployment (CD) throughout the app lifecycle, providing a comprehensive CI/CD approach.


例#
The test_component.py file contains
the unit tests and integration tests for the
ComponentManager
class.
These tests are just some of the many in the test directory.
Here are some examples of how you use pytest
:
import pytest
# 'cube_geom_and_mesh' is another fixture defined in 'conftest.py'
@pytest.fixture(scope="function")
def basic_components(mapdl, cube_geom_and_mesh):
"""Given a model in 'cube_geom_and_mesh', define some components to work with later."""
mapdl.components["mycomp1"] = "NODE", [1, 2, 3]
mapdl.components["mycomp2"] = "KP", [1, 3]
mapdl.cmsel("s", "mycomp1")
mapdl.cmsel("a", "mycomp2")
def test_dunder_methods_keys(mapdl, basic_components):
assert ["MYCOMP1", "MYCOMP2"] == list(mapdl.components.names())
def test_dunder_methods_types(mapdl, basic_components):
assert ["NODE", "KP"] == list(mapdl.components.types())
def test_dunder_methods_items(mapdl, basic_components):
assert [("MYCOMP1", "NODE"), ("MYCOMP2", "KP")] == list(mapdl.components.items())
For further pytest
configuration details, see the pytest documentation.
Code coverage#
To verify that all code is properly tested, you must ensure that every piece of code is used (covered) in at least one unit test. In this repository, the Codecov tool generates a coverage report of the committed code. It indicates how merging a pull request would impact coverage. The generation of this report is one of the checks that must run successfully to merge code changes.

Coverage example#
To show how the coverage works, assume that you have this library:
Awesome library
def get_report_colors(theme):
if theme == "weather":
colors = ["blue", "lightblue", "grey"]
elif theme == "traffic":
colors = ["red", "orange", "yellow"]
else:
colors = ["red", "blue", "green"]
return colors
テスト
You can opt to run the tests with this configuration:
def test_get_report_colors():
assert get_report_colors("weather") == ["blue", "lightblue", "grey"]
assert get_report_colors("traffic") == ["red", "orange", "yellow"]
assert get_report_colors("other") == ["red", "blue", "green"]
Or, if a method is a bit more complex, you can split the case in different tests:
def test_get_report_colors_weather():
assert get_report_colors("weather") == ["blue", "lightblue", "grey"]
def test_get_report_colors_traffic():
assert get_report_colors("traffic") == ["red", "orange", "yellow"]
def test_get_report_colors_other():
assert get_report_colors("other") == ["red", "blue", "green"]
While the code coverage in either case is 100% for the function, the second case is more useful for debugging the function.
You can also use parametrize (pytest.mark.parametrize) to make the code more readable, and easier to reuse.
@pytest.mark.parametrize(
"theme,output",
[
["weather", "traffic", "other"],
[
["blue", "lightblue", "grey"]["red", "orange", "yellow"][
"red", "blue", "green"
]
],
],
)
def test_get_report_color(theme, output):
assert get_report_colors(theme) == output
For further explanations, see the pytest documentation .
Code style#
PyMAPDL follows the PEP8 standard as outlined in the PyAnsys Development Guide and implements style checking using pre-commit.
To ensure your code meets minimum code styling standards, run these commands:
(.venv) mapdl@machine:~/pymapdl$ pip install pre-commit
(.venv) mapdl@machine:~/pymapdl$ pre-commit run --all-files
You can also install this as a pre-commit hook by running this command:
(.venv) mapdl@machine:~/pymapdl$ pre-commit install
Since you have installed pre-commit
as a hook, git
automatically
runs these hooks before committing, failing if it find any
format issues and making or proposing the necessary changes
to the commit.
If this happens, you might need to run commit and edit these
changes several times before commit successfully.
(.venv) mapdl@machine:~/pymapdl$ git commit -m "my commit"
[INFO] Stashing unstaged files to /home/mapdl/.cache/pre-commit/patch1704703895-16914.
Add License Headers......................................................Passed
isort....................................................................Passed
numpydoc-validation......................................................Passed
black....................................................................Passed
blacken-docs.............................................................Failed
- hook id: blacken-docs
- exit code: 1
- files were modified by this hook
doc/source/getting_started/develop_pymapdl.rst: Rewriting...
This way, it's not possible for you to push code that fails the style checks. For example:
(.venv) mapdl@machine:~/pymapdl$ git commit -m "my commit"
[WARNING] Unstaged files detected.
[INFO] Stashing unstaged files to /home/mapdl/.cache/pre-commit/patch1704703895-16914.
Add License Headers..................................(no files to check)Skipped
isort................................................(no files to check)Skipped
numpydoc-validation..................................(no files to check)Skipped
black................................................(no files to check)Skipped
blacken-docs.............................................................Passed
flake8...............................................(no files to check)Skipped
codespell................................................................Passed
check for merge conflicts................................................Passed
debug statements (python)............................(no files to check)Skipped
Validate GitHub Workflows............................(no files to check)Skipped
[INFO] Restored changes from /home/mapdl/.cache/pre-commit/patch1704703895-16914.
[ci/mybranch cXXXXXXX] my commit
1 file changed, 25 insertions(+)
(.venv) mapdl@machine:~/pymapdl$
First time you run pre-commit
(using git commit
or pre-commit
), the command
might take a bit of time (2-3 minutes) to download the specified hooks and install them.
After that first time, analysing your commits should take seconds.
pre-commit
hooks can also be updated, added or removed. For more information, visit
pre-commit website.