From 90f9283c1fc190360fb3b03596982db00800b9da Mon Sep 17 00:00:00 2001 From: Thomas Helfer Date: Fri, 6 Nov 2026 09:37:26 +0100 Subject: [PATCH 01/14] cmake: options to mandate TFEL and to install the python modules elsewhere Two changes required by the pip package (issue #254): - MGIS_PYTHON_MODULES_INSTALL_DIRECTORY can now be set by the user (the wheel passes 'site-packages'), as TFEL does with TFEL_PYTHON_SITE_PACKAGES_DIR. - require-tfel makes the configuration fail when TFEL is not found, when it provides no MFront support, when the python bindings of TFEL are missing while those of MGIS are enabled, or when the TFEL version differs from MGIS_REQUIRED_TFEL_VERSION. The wheel build passes both so that it can never be produced against another TFEL than the one it depends on. --- CMakeLists.txt | 66 +++++++++++++++++++++++++++++++++++++------------- 1 file changed, 49 insertions(+), 17 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index fbb4fa1fa..5fbf5bace 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -97,23 +97,27 @@ if(enable-python-bindings) "Contains the python bindings for MGIS") set(CPACK_COMPONENT_PYTHON_BINDINGS_DEPENDS mgis) # store the location of the python modules in the MGIS_PYTHON_MODULES_INSTALL_DIRECTORY variable - if(MGIS_APPEND_SUFFIX) - if(WIN32) - set(MGIS_PYTHON_MODULES_INSTALL_DIRECTORY - bin/python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages/mgis_${MGIS_SUFFIX_FOR_PYTHON_MODULES}) - else(WIN32) - set(MGIS_PYTHON_MODULES_INSTALL_DIRECTORY - "lib${LIB_SUFFIX}/python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages/mgis_${MGIS_SUFFIX_FOR_PYTHON_MODULES}") - endif(WIN32) - else(MGIS_APPEND_SUFFIX) - if(WIN32) - set(MGIS_PYTHON_MODULES_INSTALL_DIRECTORY - "bin/python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages/mgis") - else(WIN32) - set(MGIS_PYTHON_MODULES_INSTALL_DIRECTORY - "lib${LIB_SUFFIX}/python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages/mgis") - endif(WIN32) - endif(MGIS_APPEND_SUFFIX) + # the variable can be set by the user, for instance to "site-packages" by + # the pip package, see bindings/python/pip + if(NOT MGIS_PYTHON_MODULES_INSTALL_DIRECTORY) + if(MGIS_APPEND_SUFFIX) + if(WIN32) + set(MGIS_PYTHON_MODULES_INSTALL_DIRECTORY + bin/python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages/mgis_${MGIS_SUFFIX_FOR_PYTHON_MODULES}) + else(WIN32) + set(MGIS_PYTHON_MODULES_INSTALL_DIRECTORY + "lib${LIB_SUFFIX}/python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages/mgis_${MGIS_SUFFIX_FOR_PYTHON_MODULES}") + endif(WIN32) + else(MGIS_APPEND_SUFFIX) + if(WIN32) + set(MGIS_PYTHON_MODULES_INSTALL_DIRECTORY + "bin/python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages/mgis") + else(WIN32) + set(MGIS_PYTHON_MODULES_INSTALL_DIRECTORY + "lib${LIB_SUFFIX}/python${Python_VERSION_MAJOR}.${Python_VERSION_MINOR}/site-packages/mgis") + endif(WIN32) + endif(MGIS_APPEND_SUFFIX) + endif(NOT MGIS_PYTHON_MODULES_INSTALL_DIRECTORY) endif(enable-python-bindings) # fenics-bindings (placed before compiler detection) @@ -223,6 +227,9 @@ endif(CMAKE_BUILD_TYPE STREQUAL "Coverage") #detecting TFEL and MFront option(disable-tfel "explicitly disable TFEL support. By default, MGIS tries to use TFEL for tests and MGIS/Function" OFF) +option(require-tfel "the configuration fails if TFEL is not found. It is used by the pip package, which requires TFEL with all the features MGIS can use: see bindings/python/pip" OFF) +set(MGIS_REQUIRED_TFEL_VERSION "" CACHE STRING + "if non-empty, the configuration fails if the version of the TFEL installation is not this one") if(NOT disable-tfel) list(APPEND CMAKE_MODULE_PATH ${CMAKE_CURRENT_SOURCE_DIR}/cmake/modules) find_package(TFEL) @@ -232,6 +239,31 @@ if(NOT disable-tfel) include(behaviours) endif(TFEL_FOUND) endif(NOT disable-tfel) +if(require-tfel) + if(disable-tfel) + message(FATAL_ERROR + "require-tfel and disable-tfel are mutually exclusive") + endif(disable-tfel) + if(NOT TFEL_FOUND) + message(FATAL_ERROR + "TFEL support is required (require-tfel is ON) but TFEL was not found. " + "Set TFELHOME or TFEL_DIR to help cmake find it") + endif(NOT TFEL_FOUND) + if(NOT MGIS_HAVE_MFRONT_SUPPORT) + message(FATAL_ERROR + "TFEL support is required (require-tfel is ON) but the TFEL installation provides no MFront support " + "(the TFEL libraries TFELMFrontDatabase or MTestFileGenerator were not found)") + endif(NOT MGIS_HAVE_MFRONT_SUPPORT) + if(enable-python-bindings AND NOT TFEL_PYTHON_BINDINGS) + message(FATAL_ERROR + "the python bindings of MGIS require the python bindings of TFEL " + "(the mfront.database module), which are not available in this TFEL installation") + endif(enable-python-bindings AND NOT TFEL_PYTHON_BINDINGS) + if(MGIS_REQUIRED_TFEL_VERSION AND NOT (TFEL_VERSION STREQUAL MGIS_REQUIRED_TFEL_VERSION)) + message(FATAL_ERROR + "MGIS_REQUIRED_TFEL_VERSION is '${MGIS_REQUIRED_TFEL_VERSION}' but TFEL version '${TFEL_VERSION}' was found") + endif(MGIS_REQUIRED_TFEL_VERSION AND NOT (TFEL_VERSION STREQUAL MGIS_REQUIRED_TFEL_VERSION)) +endif(require-tfel) #documentations option(enable-doxygen-doc "enable generation of the Doxygen documentation" OFF) From e6057277b90bbfbe404d518c187252d0ded4528f Mon Sep 17 00:00:00 2001 From: Thomas Helfer Date: Fri, 6 Nov 2026 10:39:15 +0100 Subject: [PATCH 02/14] cmake: generation of the stubs of the python modules with pybind11-stubgen The stubs (.pyi files) of the python modules are generated by pybind11-stubgen and installed next to the modules, when the tool is available for the python interpreter of the bindings. The enable-pybind11-stubgen option turns this off. An empty py.typed marker is installed in the package (PEP 561). This mirrors the design of TFEL (thelfer/tfel#1083, reviewed): - pybind11-stubgen is looked for and run with Python_EXECUTABLE, as it imports the modules it describes: the tool must be available for the interpreter the modules are built for. Nothing is generated, and nothing fails, when it is not available. - the modules of the package mgis are now built next to its __init__.py script in the build tree, which multi-configuration generators prevent by appending the configuration name to the output directory: it now holds a generator expression. The python tests, which assemble the package by symlinks, are unaffected. - on Windows, a sitecustomize script, only used when the stubs are generated, adds the directories of the dynamic link libraries of the build tree, given by the new MGIS_LIBRARIES global property, and the bin directory of TFELHOME to the search path of the dynamic loader. os.add_dll_directory is only called on directories which exist. cf. issue #254 --- CMakeLists.txt | 20 +++ bindings/python/mgis/CMakeLists.txt | 25 +++- bindings/python/mgis/py.typed | 0 bindings/python/src/CMakeLists.txt | 33 +---- cmake/modules/mgis-python-modules.cmake | 169 ++++++++++++++++++++++++ cmake/modules/mgis.cmake | 3 + 6 files changed, 212 insertions(+), 38 deletions(-) create mode 100644 bindings/python/mgis/py.typed create mode 100644 cmake/modules/mgis-python-modules.cmake diff --git a/CMakeLists.txt b/CMakeLists.txt index 5fbf5bace..0cf191b16 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -96,6 +96,19 @@ if(enable-python-bindings) set(CPACK_COMPONENT_PYTHON_BINDINGS_DESCRIPTION "Contains the python bindings for MGIS") set(CPACK_COMPONENT_PYTHON_BINDINGS_DEPENDS mgis) + option(enable-pybind11-stubgen "generates stubs for python extensions" ON) + if(enable-pybind11-stubgen) + # The modules are imported to generate their stubs: pybind11-stubgen + # shall be available for the python interpreter they are built for. + execute_process(COMMAND "${Python_EXECUTABLE}" -c "import pybind11_stubgen" + RESULT_VARIABLE pybind11_stubgen_import_status + OUTPUT_QUIET ERROR_QUIET) + if(pybind11_stubgen_import_status EQUAL 0) + set(pybind11_stubgen ON) + message(STATUS "Found pybind11-stubgen for ${Python_EXECUTABLE}") + endif() + endif() + include(cmake/modules/mgis-python-modules.cmake) # store the location of the python modules in the MGIS_PYTHON_MODULES_INSTALL_DIRECTORY variable # the variable can be set by the user, for instance to "site-packages" by # the pip package, see bindings/python/pip @@ -350,6 +363,13 @@ add_subdirectory(bindings) # shall be included after the other directories add_subdirectory(env) +# Generation of the stubs of the python modules using pybind11-stubgen. +# This call is placed at the end of the file as it requires that all the +# python modules and all the MGIS libraries have been declared. +if(enable-python-bindings) + generate_python_stubs() +endif(enable-python-bindings) + # Packaging if(MFrontGenericInterfaceSupportDevelopmentVersion) set(CPACK_PACKAGE_VERSION_PATCH "${CMAKE_PROJECT_VERSION_PATCH}-dev") diff --git a/bindings/python/mgis/CMakeLists.txt b/bindings/python/mgis/CMakeLists.txt index 5bfcf1e1c..401ed1694 100644 --- a/bindings/python/mgis/CMakeLists.txt +++ b/bindings/python/mgis/CMakeLists.txt @@ -1,12 +1,23 @@ add_subdirectory(fenics) if(MGIS_HAVE_TFEL AND TFEL_PYTHON_BINDINGS) - install(FILES __init__-have-tfel.py - DESTINATION ${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY} - COMPONENT python_bindings - RENAME __init__.py) + set(mgis_python_init_script __init__-have-tfel.py) else() - install(FILES __init__.py - DESTINATION ${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY} - COMPONENT python_bindings) + set(mgis_python_init_script __init__.py) endif() + +install(FILES ${mgis_python_init_script} + DESTINATION ${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY} + COMPONENT python_bindings + RENAME __init__.py) +# PEP 561 marker: the package installs the .pyi stubs of its pybind11 +# modules, which type checkers only use if this marker is present +install(FILES py.typed + DESTINATION ${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY} + COMPONENT python_bindings) +# In the build tree, the package directory where the modules are placed +# needs the __init__.py script so that the package can be imported, which +# pybind11-stubgen requires to generate the stubs. +configure_file(${mgis_python_init_script} + ${MGIS_PYTHON_MODULES_BUILD_DIR}/${MGIS_PYTHON_PACKAGE_NAME}/__init__.py + COPYONLY) diff --git a/bindings/python/mgis/py.typed b/bindings/python/mgis/py.typed new file mode 100644 index 000000000..e69de29bb diff --git a/bindings/python/src/CMakeLists.txt b/bindings/python/src/CMakeLists.txt index 51ff2fef4..2d8287d39 100644 --- a/bindings/python/src/CMakeLists.txt +++ b/bindings/python/src/CMakeLists.txt @@ -1,34 +1,5 @@ -function(mgis_python_module fullname name) - if(${ARGC} LESS 1) - message(FATAL_ERROR "mgis_python_module: no source specified") - endif(${ARGC} LESS 1) - add_library(py_${fullname} MODULE ${ARGN}) - target_include_directories(py_${fullname} PRIVATE - $) - if(TARGET pybind11::lto) - target_link_libraries(py_${fullname} PRIVATE - MFrontGenericInterface - pybind11::module pybind11::lto pybind11::windows_extras) - else(TARGET pybind11::lto) - target_link_libraries(py_${fullname} PRIVATE - MFrontGenericInterface - pybind11::module pybind11::windows_extras) - endif(TARGET pybind11::lto) - pybind11_extension(py_${fullname}) - if(NOT MSVC AND NOT ${CMAKE_BUILD_TYPE} MATCHES Debug|RelWithDebInfo) - # Strip unnecessary sections of the binary on Linux/macOS - pybind11_strip(py_${fullname}) - endif() - set_target_properties(py_${fullname} PROPERTIES PREFIX "") - set_target_properties(py_${fullname} PROPERTIES OUTPUT_NAME ${name}) - set_target_properties(py_${fullname} PROPERTIES - CXX_VISIBILITY_PRESET "hidden" - CUDA_VISIBILITY_PRESET "hidden") - # installation - install(TARGETS py_${fullname} - DESTINATION ${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY} - COMPONENT python_bindings) -endfunction(mgis_python_module) +# the mgis_python_module function is defined in +# cmake/modules/mgis-python-modules.cmake set(MGIS_MODULE_SOURCES) list(APPEND MGIS_MODULE_SOURCES diff --git a/cmake/modules/mgis-python-modules.cmake b/cmake/modules/mgis-python-modules.cmake new file mode 100644 index 000000000..1529e087d --- /dev/null +++ b/cmake/modules/mgis-python-modules.cmake @@ -0,0 +1,169 @@ +# Python modules of MGIS: definition of the modules and generation of +# their stubs using pybind11-stubgen, following the same design as TFEL +# (cf. cmake/modules/tfel-python-modules.cmake in thelfer/tfel). + +# Root directory of the python modules in the build tree +set(MGIS_PYTHON_MODULES_BUILD_DIR "${PROJECT_BINARY_DIR}/bindings/python") + +# Name of the python package in the build tree and in the installation: +# mgis or mgis_ when MGIS_APPEND_SUFFIX is ON. Only the name of the +# package carries the suffix, not the names of the modules. +if(MGIS_APPEND_SUFFIX) + set(MGIS_PYTHON_PACKAGE_NAME "mgis_${MGIS_SUFFIX_FOR_PYTHON_MODULES}") +else(MGIS_APPEND_SUFFIX) + set(MGIS_PYTHON_PACKAGE_NAME "mgis") +endif(MGIS_APPEND_SUFFIX) + +# Define a pybind11 module of the mgis package. +# +# \param fullname name of the cmake target, py_ +# \param name name of the module, as imported by python +# \param ARGN sources of the module +function(mgis_python_module fullname name) + if(${ARGC} LESS 3) + message(FATAL_ERROR "mgis_python_module: no source specified") + endif(${ARGC} LESS 3) + add_library(py_${fullname} MODULE ${ARGN}) + target_include_directories(py_${fullname} PRIVATE + $) + if(TARGET pybind11::lto) + target_link_libraries(py_${fullname} PRIVATE + MFrontGenericInterface + pybind11::module pybind11::lto pybind11::windows_extras) + else(TARGET pybind11::lto) + target_link_libraries(py_${fullname} PRIVATE + MFrontGenericInterface + pybind11::module pybind11::windows_extras) + endif(TARGET pybind11::lto) + pybind11_extension(py_${fullname}) + if(NOT MSVC AND NOT ${CMAKE_BUILD_TYPE} MATCHES Debug|RelWithDebInfo) + # Strip unnecessary sections of the binary on Linux/macOS + pybind11_strip(py_${fullname}) + endif() + set_target_properties(py_${fullname} PROPERTIES PREFIX "") + set_target_properties(py_${fullname} PROPERTIES OUTPUT_NAME ${name}) + set_target_properties(py_${fullname} PROPERTIES + CXX_VISIBILITY_PRESET "hidden" + CUDA_VISIBILITY_PRESET "hidden") + # The modules shall be next to the __init__.py script of their package, + # which imports them. Multi-configuration generators append the name of + # the configuration to the output directory, unless it holds a generator + # expression. + set_target_properties(py_${fullname} PROPERTIES + LIBRARY_OUTPUT_DIRECTORY + "$<1:${MGIS_PYTHON_MODULES_BUILD_DIR}/${MGIS_PYTHON_PACKAGE_NAME}>") + # installation + install(TARGETS py_${fullname} + DESTINATION ${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY} + COMPONENT python_bindings) + python_module_stubgen(py_${fullname} ${name}) +endfunction(mgis_python_module) + +# Register a python module so that a stub file is generated for it using +# pybind11-stubgen by the generate_python_stubs function. +# +# Nothing is done if the enable-pybind11-stubgen option is OFF or if +# pybind11-stubgen has not been found. +# +# \param target target associated with the python module +# \param name name of the module, as it is imported by python +function(python_module_stubgen target name) + if(NOT (enable-pybind11-stubgen AND pybind11_stubgen)) + return() + endif(NOT (enable-pybind11-stubgen AND pybind11_stubgen)) + set_property(GLOBAL APPEND PROPERTY MGIS_PYTHON_STUBGEN_MODULES + "${target}:${MGIS_PYTHON_PACKAGE_NAME}.${name}") +endfunction(python_module_stubgen) + +# Generate the stub files of all the python modules registered by the +# python_module_stubgen function using pybind11-stubgen and install them +# next to the modules they describe. +# +# The stubs are generated by the python-stubs target, which is built when +# the project is built. +# +# This function shall be called after all the calls to add_subdirectory as +# it requires that all the python modules and all the MGIS libraries have +# been declared. +# +# Nothing is done if the enable-pybind11-stubgen option is OFF or if +# pybind11-stubgen has not been found. +function(generate_python_stubs) + if(NOT (enable-pybind11-stubgen AND pybind11_stubgen)) + return() + endif(NOT (enable-pybind11-stubgen AND pybind11_stubgen)) + get_property(MGIS_PYTHON_STUBGEN_MODULES + GLOBAL PROPERTY MGIS_PYTHON_STUBGEN_MODULES) + if(NOT MGIS_PYTHON_STUBGEN_MODULES) + return() + endif(NOT MGIS_PYTHON_STUBGEN_MODULES) + # Importing a python module triggers the execution of the __init__.py + # script of the package, which imports the other modules of the package. + # Hence all the python modules must be built before a stub can be + # generated. + set(pybind11_stubgen_dependencies) + foreach(entry ${MGIS_PYTHON_STUBGEN_MODULES}) + string(REGEX REPLACE ":.*$" "" target "${entry}") + list(APPEND pybind11_stubgen_dependencies "${target}") + endforeach(entry ${MGIS_PYTHON_STUBGEN_MODULES}) + # the environment variables passed to pybind11-stubgen + set(mgis_stubgen_pythonpath "${MGIS_PYTHON_MODULES_BUILD_DIR}") + if(WIN32) + # On windows, the directories containing the dynamic link libraries of + # the build tree, which the python modules depend on, are neither those + # of the python interpreter nor those of the python modules. The python + # interpreter ignores the PATH variable when it imports an extension + # module, but the directories can be added to the search path of the + # dynamic loader with the os.add_dll_directory function. This is done by + # a sitecustomize script, which is placed in a directory added to the + # PYTHONPATH variable for the execution of pybind11-stubgen. + # + # The MGIS python modules depend on the MGIS libraries, given by the + # MGIS_LIBRARIES global property, and on the TFEL libraries, installed + # in the bin directory of TFELHOME. + get_property(mgis_stubgen_libraries GLOBAL PROPERTY MGIS_LIBRARIES) + set(mgis_stubgen_library_directories) + foreach(mgis_stubgen_library ${mgis_stubgen_libraries}) + list(APPEND mgis_stubgen_library_directories + "$") + endforeach(mgis_stubgen_library ${mgis_stubgen_libraries}) + if(TFEL_FOUND) + list(APPEND mgis_stubgen_library_directories "${TFELHOME}/bin") + endif(TFEL_FOUND) + string(JOIN "\", r\"" mgis_stubgen_library_directories + ${mgis_stubgen_library_directories}) + set(mgis_stubgen_sitecustomize_directory + "${PROJECT_BINARY_DIR}/bindings/stubgen/$") + file(GENERATE + OUTPUT "${mgis_stubgen_sitecustomize_directory}/sitecustomize.py" + CONTENT "import os + +for _directory in dict.fromkeys((r\"${mgis_stubgen_library_directories}\", )): + if os.path.isdir(_directory): + os.add_dll_directory(_directory) +") + # the two paths of the PYTHONPATH variable are separated by a semicolon + string(REPLACE ";" "$" mgis_stubgen_pythonpath + "${mgis_stubgen_sitecustomize_directory};${MGIS_PYTHON_MODULES_BUILD_DIR}") + endif(WIN32) + set(pybind11_stubgen_files) + foreach(entry ${MGIS_PYTHON_STUBGEN_MODULES}) + string(REGEX REPLACE "^[^:]*:" "" module "${entry}") + string(REPLACE "." "/" module_path "${module}") + set(stub_file "${MGIS_PYTHON_MODULES_BUILD_DIR}/${module_path}.pyi") + add_custom_command(OUTPUT "${stub_file}" + COMMAND "${CMAKE_COMMAND}" -E env + "PYTHONPATH=${mgis_stubgen_pythonpath}" + "${Python_EXECUTABLE}" -m pybind11_stubgen "${module}" + "--output-dir" "${MGIS_PYTHON_MODULES_BUILD_DIR}" + DEPENDS ${pybind11_stubgen_dependencies} + COMMENT "Generating stub for python module ${module}" + VERBATIM) + list(APPEND pybind11_stubgen_files "${stub_file}") + install(FILES "${stub_file}" + DESTINATION "${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY}" + COMPONENT python_bindings) + endforeach(entry ${MGIS_PYTHON_STUBGEN_MODULES}) + add_custom_target(python-stubs ALL + DEPENDS ${pybind11_stubgen_files}) +endfunction(generate_python_stubs) diff --git a/cmake/modules/mgis.cmake b/cmake/modules/mgis.cmake index cdbc438c3..77d05a2cd 100644 --- a/cmake/modules/mgis.cmake +++ b/cmake/modules/mgis.cmake @@ -23,6 +23,9 @@ function(mgis_library name) endif(${ARGC} LESS 2) add_library(${name} SHARED ${ARGN}) add_library(mgis::${name} ALIAS ${name}) + # reference to the library, used by generate_python_stubs to know the + # directories containing the dynamic link libraries of the build tree + set_property(GLOBAL APPEND PROPERTY MGIS_LIBRARIES "${name}") # the installed headers require C++20 target_compile_features(${name} PUBLIC cxx_std_20) if(MGIS_APPEND_SUFFIX) From ebd85a8e40faeba2f7937e6faa681280c5e17e20 Mon Sep 17 00:00:00 2001 From: Thomas Helfer Date: Fri, 6 Nov 2026 11:32:25 +0100 Subject: [PATCH 03/14] pip: packaging of the mgis wheel The mgis package (issue #254): setup.py configures, builds and installs MGIS with cmake, and lays the installation out as a python package, the mgis module being the MGISHOME directory (bin, lib, include and share) with the python modules at its root. The wheel depends on the tfel-mfront wheel, pinned both as a build and as a run dependency, the pin being written in three places which check_tfel_dependency verifies consistent: - cmake is passed require-tfel and MGIS_REQUIRED_TFEL_VERSION, so that the wheel can never be built against another TFEL than the pinned one, - the runtime paths of all the binaries of the wheel point to mgis/lib and to the tfel/lib directory of the sibling wheel, set as DT_RPATH so that LD_LIBRARY_PATH does not take precedence over them, - the version of the pinned tfel-mfront is recorded in the __init__.py script of the package, which refuses to import when the installed version differs, as the error of the dynamic loader would be cryptic, - auditwheel and delocate are prevented from vendoring the TFEL libraries into this wheel (pyproject.toml), which would make a behaviour loaded in python load two copies of TFEL. test_wheel.py checks that the wheel holds none of them. test_wheel.py, which cibuildwheel runs in a fresh virtual environment, compiles a behaviour with the mfront of the tfel-mfront wheel, integrates it through mgis.behaviour and builds a consumer project using find_package(MFrontGenericInterface) against the wheel. The first version only supports the python bindings, on linux x86_64, macOS arm64 and windows AMD64. --- bindings/python/pip/pyproject.toml | 87 +++++ bindings/python/pip/setup.py | 334 +++++++++++++++++++ bindings/python/pip/test_wheel.py | 133 ++++++++ pip-package.md | 519 +++++++++++++++++++++++++++++ 4 files changed, 1073 insertions(+) create mode 100644 bindings/python/pip/pyproject.toml create mode 100644 bindings/python/pip/setup.py create mode 100644 bindings/python/pip/test_wheel.py create mode 100644 pip-package.md diff --git a/bindings/python/pip/pyproject.toml b/bindings/python/pip/pyproject.toml new file mode 100644 index 000000000..24677e2e0 --- /dev/null +++ b/bindings/python/pip/pyproject.toml @@ -0,0 +1,87 @@ +# Build of the mgis pip package. +# +# setup.py configures, builds and installs MGIS with cmake, then lays out +# the installation as a python package. The wheels are built for each +# python version by cibuildwheel, see .github/workflows/python-pip.yml +# +# The TFEL dependency (tfel-mfront) is pinned below, both for the build +# and for the run. setup.py checks that the two pins and the constant +# TFEL_DEPENDENCY of setup.py agree: bump the three values together. + +[build-system] +requires = [ + "setuptools>=64", + "cmake>=3.20", + "pybind11>=2.12", + "pybind11-stubgen>=3.0", + "numpy>=2.0", + "tfel-mfront==5.2.0.dev0", + "patchelf; sys_platform == 'linux'", +] +build-backend = "setuptools.build_meta" + +[project] +name = "mgis" +dynamic = ["version"] +description = "MFrontGenericInterfaceSupport with Python bindings" +readme = { text = "MGIS provides a generic interface to integrate MFront generated material libraries in solvers. This package provides the MGIS library, headers and Python bindings. It depends on the tfel-mfront package, pinned to the version it was built against. A C++ compiler is required to build MFront implementations.", content-type = "text/plain" } +authors = [{ name = "Thomas Helfer", email = "thomas.helfer@cea.fr" }] +requires-python = ">=3.9" +dependencies = ["numpy", "tfel-mfront==5.2.0.dev0"] +classifiers = [ + "Development Status :: 5 - Production/Stable", + "Intended Audience :: Developers", + "Intended Audience :: Science/Research", + "License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)", + "License :: OSI Approved :: CEA CNRS Inria Logiciel Libre License - CECILL-C", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Programming Language :: Python :: 3.14", + "Programming Language :: Python :: 3.15", + "Topic :: Scientific/Engineering", +] + +[project.urls] +Homepage = "https://thelfer.github.io/mgis/web/index.html" +Source = "https://github.com/thelfer/MFrontGenericInterfaceSupport" + +# the content of the package is produced by setup.py +[tool.setuptools] +packages = [] +py-modules = [] + +[tool.cibuildwheel] +build-verbosity = 1 +skip = "*-musllinux_*" +test-command = "python {package}/test_wheel.py" + +[tool.cibuildwheel.linux] +archs = ["x86_64"] +# auditwheel shall not vendor the TFEL libraries: they are provided by the +# tfel-mfront wheel, installed next to this one. Vendoring them under +# mangled names would make a behaviour loaded in python load a second copy +# of TFEL. The rpath of the libraries of this wheel points to the sibling +# tfel/lib directory, see set_relative_runtime_paths in setup.py. +# The patterns are globs (auditwheel >= 6), which also behave correctly as +# regular expressions for older versions. They do not match +# libMFrontGenericInterface*, the library of MGIS itself. +repair-wheel-command = "auditwheel repair -w {dest_dir} {wheel} --exclude libTFEL* --exclude libMTest* --exclude libMFM* --exclude libMFrontQuery* --exclude libMFrontLogStream* --exclude libMFrontProfiling* --exclude libMFrontGenericParallelRuntime*" + +[tool.cibuildwheel.macos] +archs = ["arm64"] +environment = { MACOSX_DEPLOYMENT_TARGET = "11.0" } +# same reason as on linux: delocate shall not move the TFEL libraries, +# which are provided by the tfel-mfront wheel, into this wheel +repair-wheel-command = "delocate-wheel --require-archs {delocate_archs} -w {dest_dir} -v -x libTFEL.* -x libMTest.* -x libMFM.* -x libMFrontQuery.* -x libMFrontLogStream.* -x libMFrontProfiling.* -x libMFrontGenericParallelRuntime.* {wheel}" + +[tool.cibuildwheel.windows] +archs = ["AMD64"] +# The DLLs of MGIS are in mgis/bin, and those of TFEL in tfel/bin, where +# the python modules find them (os.add_dll_directory). delvewheel would +# copy these DLLs under other names, so a behaviour loaded in python would +# load a second copy of them. +repair-wheel-command = "" diff --git a/bindings/python/pip/setup.py b/bindings/python/pip/setup.py new file mode 100644 index 000000000..737bc630d --- /dev/null +++ b/bindings/python/pip/setup.py @@ -0,0 +1,334 @@ +"""Build of the mgis pip package. + +MGIS is configured, built and installed with cmake, then the installation +is laid out as follows: + +- the python modules (the mgis package) are placed at the root of the + package, +- the libraries, headers and data are placed in the bin, lib, include and + share directories of the mgis module, which is thus the MGISHOME + directory, as a regular installation of MGIS. + +MGIS is built against the tfel-mfront wheel declared in pyproject.toml, +which pip installs in the isolated build environment. This script locates +that installation, mandates it to cmake (require-tfel and +MGIS_REQUIRED_TFEL_VERSION), makes the binaries of the wheel look for the +TFEL libraries in the sibling tfel wheel at run time, and records the +version of tfel-mfront in the package, where importing it checks it. + +The TFEL libraries are never copied into this wheel: a behaviour loaded in +python would then load a second copy of TFEL (cf. pyproject.toml). +""" + +import importlib.metadata +import importlib.util +import os +import re +import shutil +import subprocess +import sys +from pathlib import Path + +from setuptools import setup +from setuptools.command.build_ext import build_ext +from setuptools.dist import Distribution + +pip_directory = Path(__file__).resolve().parent +mgis_sources = pip_directory.parents[2] + +# The tfel-mfront wheel this package is built against and depends on. +# pyproject.toml cannot compute the pin, so it is written twice there, and +# check_tfel_dependency verifies that the two pins and this constant agree. +# Bump the three values together. +TFEL_DEPENDENCY = "tfel-mfront==5.2.0.dev0" + +# python code prepended to the __init__.py script of the mgis package: +# MGISHOME, the DLL directories on windows, and the check of the version of +# tfel-mfront. The version of TFEL of the installation the wheel was built +# against is recorded at build time (@TFEL_MFRONT_VERSION@). +pip_setup = '''\ +# added by the mgis pip package +import os as _os + +_os.environ["MGISHOME"] = _os.path.dirname(_os.path.abspath(__file__)) +if _os.name == "nt": + # since Python 3.8, the directories listed in PATH are not searched for + # the DLLs needed by the extension modules: the bin directory of this + # package, where MFrontGenericInterface.dll is installed, and the bin + # directory of the tfel-mfront wheel, where the TFEL DLLs are, are + # registered. importing mgis does not necessarily run tfel/__init__.py. + import importlib.util as _importlib_util + + for _name in ("mgis", "tfel"): + _spec = _importlib_util.find_spec(_name) + for _directory in (_spec.submodule_search_locations if _spec else ()): + _directory = _os.path.join(_directory, "bin") + if _os.path.isdir(_directory): + _os.add_dll_directory(_directory) + +_TFEL_MFRONT_VERSION = "@TFEL_MFRONT_VERSION@" + +# The shared libraries of TFEL have a versioned soname, such as +# libTFELMath.so.5.2.0-dev, so importing a module of this wheel fails with +# a obscure 'libTFELXXX.so.5.2.0-dev: cannot open shared object file' error +# when the installed tfel-mfront does not have the version this wheel was +# built against. Check the version of the installed tfel-mfront package +# instead, which also covers the cases where the libraries are not the ones +# of a wheel (TFELHOME set externally), and which is what cmake verified at +# configuration time (require-tfel and MGIS_REQUIRED_TFEL_VERSION). +def _check_tfel_mfront(): + from importlib import metadata + + try: + _version = metadata.version("tfel-mfront") + except metadata.PackageNotFoundError: + _version = None + if _version != _TFEL_MFRONT_VERSION: + raise RuntimeError( + "this mgis wheel was built against tfel-mfront " + + _TFEL_MFRONT_VERSION + ", but version " + str(_version) + + " is installed") + + +_check_tfel_mfront() +''' + + +def get_mgis_version(): + """return the MGIS version, as defined in the main CMakeLists.txt""" + cmakelists = (mgis_sources / "CMakeLists.txt").read_text() + version = re.search( + r'project\("mfront-generic-interface"\s+VERSION\s+(\d+)\.(\d+)\.(\d+)', + cmakelists) + if version is None: + raise RuntimeError("MGIS version not found in CMakeLists.txt") + version = ".".join(version.groups()) + if re.search( + r"set\(MFrontGenericInterfaceSupportDevelopmentVersion\s+ON\)", + cmakelists): + return version + "-dev" + return version + + +def check_tfel_dependency(): + """check that the pins of pyproject.toml agree with TFEL_DEPENDENCY""" + pins = set(re.findall(r'"(tfel-mfront==[^"]+)"', + (pip_directory / "pyproject.toml").read_text())) + if pins != {TFEL_DEPENDENCY}: + raise RuntimeError( + "inconsistent TFEL dependency: pyproject.toml pins " + + str(sorted(pins)) + " while setup.py uses '" + + TFEL_DEPENDENCY + "'") + + +def get_tfelhome(): + """path of the tfel module installed in the build environment. The + package is not imported: find_spec does not load any library""" + spec = importlib.util.find_spec("tfel") + if spec is None or not spec.submodule_search_locations: + raise RuntimeError( + "the tfel-mfront package, declared in [build-system].requires " + "of pyproject.toml, is not installed in the build environment") + return Path(next(iter(spec.submodule_search_locations))) + + +def get_tfel_version(tfelhome): + """return the version of TFEL as reported by the tfel-config program of + the tfel-mfront installation, in the same way as cmake's FindTFEL""" + tfel_config = tfelhome / "bin" / ( + "tfel-config.exe" if os.name == "nt" else "tfel-config") + output = subprocess.run([str(tfel_config), "--version"], check=True, + stdout=subprocess.PIPE, text=True).stdout + return output.split()[1] + + +class BinaryDistribution(Distribution): + # compiled modules inside: platform-specific wheel, not py3-none-any + def has_ext_modules(self): + return True + + +def build_and_install_mgis(build_directory, install_directory, tfelhome, + tfel_version): + import pybind11 + + # copy of pybind11 at a fixed path: the isolated builds install it in a + # directory whose name changes at each build, which prevents ccache from + # reusing the compilations of the bindings + pybind11_directory = Path(build_directory).parent / "pybind11" + shutil.rmtree(pybind11_directory, ignore_errors=True) + shutil.copytree(Path(pybind11.__file__).parent, pybind11_directory) + + # every option is set explicitly: the content of the wheel shall not + # depend on what the build environment happens to provide (HDF5...) + cmake_options = [ + "-DCMAKE_BUILD_TYPE=Release", + "-DCMAKE_INSTALL_PREFIX=" + str(install_directory), + "-DMGIS_PYTHON_MODULES_INSTALL_DIRECTORY=site-packages/mgis", + "-DPython_EXECUTABLE=" + sys.executable, + "-Dpybind11_DIR=" + str(pybind11_directory / "share" / "cmake" / + "pybind11"), + "-Denable-python-bindings=ON", + "-Denable-pybind11-stubgen=ON", + "-Denable-portable-build=ON", + "-Denable-testing=OFF", + "-Denable-website=OFF", + "-Denable-doxygen-doc=OFF", + "-Denable-c-bindings=OFF", + "-Denable-fortran-bindings=OFF", + "-Denable-fenics-bindings=OFF", + "-Denable-julia-bindings=OFF", + "-Denable-cuda-algorithms=OFF", + "-Denable-openmp=OFF", + "-Denable-exceptions=OFF", + "-Denable-hdf5-support=OFF", + "-Denable-hdf5-automatic-support=OFF", + "-Ddisable-tfel=OFF", + # the wheel can never be built against another TFEL than the one it + # depends on: cmake checks TFEL_FOUND, MGIS_HAVE_MFRONT_SUPPORT, + # TFEL_PYTHON_BINDINGS and MGIS_REQUIRED_TFEL_VERSION + "-Drequire-tfel=ON", + "-DMGIS_REQUIRED_TFEL_VERSION=" + tfel_version, + "-DTFEL_DIR=" + str(tfelhome / "share" / "tfel" / "cmake"), + ] + if os.name == "nt": + cmake_options += ["-A", "x64"] + jobs = os.environ.get("CMAKE_BUILD_PARALLEL_LEVEL", str(os.cpu_count() or 1)) + environment = dict(os.environ, TFELHOME=str(tfelhome)) + subprocess.run(["cmake", "-S", str(mgis_sources), "-B", str(build_directory)] + + cmake_options, check=True, env=environment) + subprocess.run(["cmake", "--build", str(build_directory), "--config", + "Release", "--parallel", jobs], check=True, env=environment) + subprocess.run(["cmake", "--install", str(build_directory), "--config", + "Release"], check=True, env=environment) + + +def is_binary(path, magic_numbers): + with open(path, "rb") as f: + return f.read(4) in magic_numbers + + +def materialize_symlinks(package_directory): + """replace the symbolic links of the wheel by copies of the files they + point to: wheels do not store symbolic links (MGIS installs its library + unversioned, so there is none in practice)""" + for path in package_directory.rglob("*"): + if path.is_symlink(): + target = path.resolve() + path.unlink() + shutil.copy2(target, path) + + +def set_relative_runtime_paths(package_directory): + """make all the binaries of the wheel look for the libraries in + mgis/lib and in the lib directory of the tfel-mfront wheel. + + The tfel directory is not part of this wheel: it is the python package + of the tfel-mfront wheel, installed in site-packages next to this one. + The relative path of a binary to that directory is hence computed as if + the root of the wheel was a site-packages directory, which it is once + installed, whereas the build directory of the package is not. + + auditwheel and delocate keep the libraries already in the wheel, and + the TFEL ones are excluded from the repair, so that the runtime paths + below are used to find them: see pyproject.toml. + + On linux, DT_RPATH is used rather than DT_RUNPATH, since it is + searched before LD_LIBRARY_PATH: the binaries of the package use the + libraries of the package, even if LD_LIBRARY_PATH points to another + installation, whose libraries may have the same names.""" + fake_site_packages = package_directory.parent / "site-packages" + if sys.platform.startswith("linux"): + magic_numbers = (b"\x7fELF",) + elif sys.platform == "darwin": + magic_numbers = (b"\xcf\xfa\xed\xfe", b"\xca\xfe\xba\xbe") + else: + return + for path in sorted(package_directory.rglob("*")): + if path.is_symlink() or not path.is_file(): + continue + if not is_binary(path, magic_numbers): + continue + # where the directory of the binary will be once the wheel is + # installed, simulated in a site-packages directory + directory = fake_site_packages / path.parent.relative_to( + package_directory) + rpaths = [] + for library_directory in (fake_site_packages / "mgis" / "lib", + fake_site_packages / "tfel" / "lib"): + relative_path = os.path.relpath(library_directory, directory) + if sys.platform.startswith("linux"): + rpaths.append("$ORIGIN" if relative_path == "." + else "$ORIGIN/" + relative_path) + elif relative_path != ".": + rpaths.append("@loader_path/" + relative_path) + if sys.platform.startswith("linux"): + subprocess.run(["patchelf", "--force-rpath", "--set-rpath", + ":".join(dict.fromkeys(rpaths)), str(path)], + check=True) + else: + load_commands = subprocess.run(["otool", "-l", str(path)], + check=True, capture_output=True, + text=True).stdout.splitlines() + current_rpaths = [load_commands[i + 2].split()[1] + for i, line in enumerate(load_commands) + if line.strip() == "cmd LC_RPATH"] + options = [] + for rpath in current_rpaths: + options += ["-delete_rpath", rpath] + for rpath in rpaths: + options += ["-add_rpath", rpath] + subprocess.run(["install_name_tool"] + options + [str(path)], + check=True) + # install_name_tool invalidates the signature of the binary + subprocess.run(["codesign", "--force", "--sign", "-", str(path)], + check=True) + + +def layout_package(install_directory, package_directory, + tfel_mfront_version): + """lay out the MGIS installation as a python package""" + shutil.copytree(install_directory / "site-packages", package_directory, + dirs_exist_ok=True) + mgis_module = package_directory / "mgis" + for directory in ("bin", "lib", "include", "share"): + if (install_directory / directory).is_dir(): + shutil.copytree(install_directory / directory, + mgis_module / directory, dirs_exist_ok=True) + init_file = mgis_module / "__init__.py" + init_file.write_text( + pip_setup.replace("@TFEL_MFRONT_VERSION@", tfel_mfront_version) + + init_file.read_text()) + materialize_symlinks(package_directory) + set_relative_runtime_paths(package_directory) + + +class build_mgis(build_ext): + """build MGIS with cmake and fill the build directory of the package. + + build_ext is used since it is the only build command run for a + distribution without python packages declared to setuptools""" + + def run(self): + check_tfel_dependency() + tfelhome = get_tfelhome() + tfel_version = get_tfel_version(tfelhome) + tfel_mfront_version = importlib.metadata.version("tfel-mfront") + # with python 3.9 on Windows, resolve keeps relative the paths which + # do not exist yet + build_temp = Path(self.build_temp).absolute().resolve() + install_directory = build_temp / "install" + build_and_install_mgis(build_temp / "build", install_directory, + tfelhome, tfel_version) + layout_package(install_directory, Path(self.build_lib), + tfel_mfront_version) + + +mgis_version = get_mgis_version() + +setup( + # 3.1.0-dev is not a valid PEP 440 version, 3.1.0.dev0 is + version=mgis_version.replace("-dev", ".dev0"), + distclass=BinaryDistribution, + cmdclass={"build_ext": build_mgis}, +) diff --git a/bindings/python/pip/test_wheel.py b/bindings/python/pip/test_wheel.py new file mode 100644 index 000000000..c1470029c --- /dev/null +++ b/bindings/python/pip/test_wheel.py @@ -0,0 +1,133 @@ +"""Test of an installed mgis wheel, run by cibuildwheel. + +On Linux and macOS, a behaviour is compiled with the mfront program of the +tfel-mfront wheel, integrated from python through mgis.behaviour and loaded +through a project using find_package(MFrontGenericInterface) from the +wheel, which checks that the executables, the headers, the cmake package +and the libraries of the two wheels are found and are consistent. On +Windows, building behaviours requires Visual Studio and is not tested. +""" + +import os +import re +import shutil +import subprocess +import sys +import tempfile +from importlib import metadata + +import mgis +import mgis.behaviour as mgis_bv +import mgis.function as mgis_fct +import mgis.material_property as mgis_mp +import mgis.model as mgis_model +import tfel # sets TFELHOME_, used by MFrontGenericInterfaceConfig + +# the import of mgis checked that the tfel-mfront wheel this wheel was +# built against is the one installed; check it again explicitly +assert mgis._TFEL_MFRONT_VERSION == metadata.version("tfel-mfront") + +mgishome = os.path.dirname(os.path.abspath(mgis.__file__)) + +# the TFEL libraries must not have been vendored into the mgis wheel: +# they are provided by the tfel-mfront wheel, and a copy under a mangled +# name would make a behaviour load two copies of TFEL +vendored = re.compile( + r"(lib)?(TFEL|MTest|MFM|MFront(?!GenericInterface))" + r".*\.(so|dylib|dll)(\.|$)") +for directory, _, files in os.walk(mgishome): + for name in files: + if vendored.search(name): + sys.exit("the mgis wheel must not contain the library " + name) + +# the stubs of the python modules are installed next to them, as well as +# the py.typed marker +for stub in ("_mgis.pyi", "behaviour.pyi", "material_property.pyi", + "model.pyi", "function.pyi", "py.typed"): + if not os.path.isfile(os.path.join(mgishome, stub)): + sys.exit("missing " + stub) + +if os.name == "nt": + sys.exit(0) + +behaviour = """\ +@DSL Implicit; +@Behaviour Elasticity; +@Brick StandardElasticity; +@ElasticMaterialProperties {150e9, 0.3}; +""" + +library = "libBehaviour.dylib" if sys.platform == "darwin" else "libBehaviour.so" + +tfel_version = subprocess.run([shutil.which("tfel-config"), "--version"], + check=True, stdout=subprocess.PIPE, + text=True).stdout.split()[1] + +with tempfile.TemporaryDirectory() as directory: + os.chdir(directory) + with open("Elasticity.mfront", "w") as f: + f.write(behaviour) + subprocess.run([shutil.which("mfront"), "--obuild", "--interface=generic", + "Elasticity.mfront"], check=True) + + # integrate the behaviour from python: with the full strain tensor + # imposed ({EXX: 1e-3, the other components zero}), the stress is + # (lambda + 2 mu) EXX for E = 150 GPa and nu = 0.3 + b = mgis_bv.load(os.path.join("src", library), "Elasticity", + mgis_bv.Hypothesis.Tridimensional) + assert b.tfel_version == tfel_version, \ + "the behaviour was built with TFEL " + b.tfel_version + \ + ", not " + tfel_version + d = mgis_bv.BehaviourData(b) + d.dt = 1 + mgis_bv.setExternalStateVariable(d.s1, "Temperature", 293.15) + o = mgis_bv.getVariableOffset(b.gradients, "Strain", b.hypothesis) + mgis_bv.update(d) + d.s1.gradients[o] = 1e-3 + mgis_bv.integrate(d, b) + sxx = float(d.s1.thermodynamic_forces[o]) + e, nu = 150e9, 0.3 + expected = e * (1 - nu) / ((1 + nu) * (1 - 2 * nu)) * 1e-3 + print("SXX:", sxx, "expected:", expected) + if abs(sxx - expected) > 1e-3 * abs(expected): + sys.exit("unexpected stress value") + + # the cmake package exported by the wheel must be usable: MFrontGeneric + # InterfaceConfig.cmake finds TFEL through the TFELHOME_ + # variable set by the import of tfel above + with open("check.cxx", "w") as f: + f.write("""\ +#include +#include + +int main(int argc, char *argv[]) { + if (argc < 3) { + return 1; + } + const auto b = mgis::behaviour::load(argv[1], argv[2], + mgis::behaviour::Hypothesis::\ +TRIDIMENSIONAL); + std::cout << b.behaviour << std::endl; + return 0; +} +""") + with open("CMakeLists.txt", "w") as f: + f.write("""\ +cmake_minimum_required(VERSION 3.20) +project(mgis_wheel_check CXX) +find_package(MFrontGenericInterface REQUIRED) +add_executable(check check.cxx) +target_link_libraries(check PRIVATE mgis::MFrontGenericInterface) +""") + subprocess.run([shutil.which("cmake"), "-S", ".", "-B", "build", + "-DCMAKE_BUILD_TYPE=Release", + "-DCMAKE_PREFIX_PATH=" + mgishome], check=True) + subprocess.run([shutil.which("cmake"), "--build", "build"], check=True) + check = os.path.join("build", "check" + (".exe" if os.name == "nt" else "")) + out = subprocess.run([check, os.path.join(directory, "src", library), + "Elasticity"], check=True, stdout=subprocess.PIPE, + text=True).stdout.strip() + if out != "Elasticity": + sys.exit("unexpected output of the cmake check: " + out) + +print("the mgis wheel is consistent") diff --git a/pip-package.md b/pip-package.md new file mode 100644 index 000000000..73e116359 --- /dev/null +++ b/pip-package.md @@ -0,0 +1,519 @@ +# Proposal: a `pip` package for MGIS (issue #254) + +Status: proposal, to be discussed on the issue before implementation. + +Scope of the first version: **python bindings only** (no C / Fortran / FEniCS / +Julia bindings in the wheel), **portable build** +(`-Denable-portable-build=ON`), TFEL support **fully enabled** +(`MGIS_HAVE_TFEL`, `MGIS/Function` + precompiled operations, MFront +database, TFEL python bindings), **stubs generated with +`pybind11-stubgen`** as in TFEL (PR thelfer/tfel#1083). + +The wheels are built by a GitHub Actions workflow modeled on TFEL's +`.github/workflows/python-pip.yml`, with `pypa/cibuildwheel`. + +--- + +## 1. Reference: what TFEL already does + +- `bindings/python/pip/{pyproject.toml,setup.py,test_wheel.py}`: `setup.py` + configures, builds and installs TFEL with cmake, then lays the + installation out as a python package. The `tfel` module *is* TFELHOME: + `bin`, `lib`, `include` and `share` are placed inside it, and a short + preamble inserted into the `__init__.py` scripts sets the + `TFELHOME_` environment variable, which TFEL's + `GetInstallPath.cxx` honours with priority over `TFELHOME`. +- `set_relative_runtime_paths()` rewrites the runtime path of every binary + of the wheel to be relative to `tfel/lib` (`patchelf --force-rpath`, + hence `DT_RPATH`, on purpose: it is searched before `LD_LIBRARY_PATH`; + `install_name_tool` + `codesign --force --sign -` on macOS; nothing on + Windows, where `__init__.py` calls `os.add_dll_directory`). +- Windows wheels: `repair-wheel-command = ""`, since delvewheel would copy + the TFEL DLLs under other names, so a behaviour loaded in python would + load a second copy of them. +- `.github/workflows/python-pip.yml`: cibuildwheel over + ubuntu/macos/windows x cp39…cp315 (cp312 only on pull requests), ccache + (one cache per OS, saved by the cp312 job; static musl ccache inside the + manylinux container, `CCACHE_DIR=/host/ccache`), publish to + PyPI and to the GitHub release on the `TFEL-x.y.z` tags. + +### Lessons of the review of TFEL PR #1083 (pybind11-stubgen) + +The same exercise is done for MGIS, so MGIS starts from the *reviewed* +design, not from the first proposal of PR #1083: + +1. `pybind11-stubgen` is **looked for and run with `${Python_EXECUTABLE}`** + (`${Python_EXECUTABLE} -c "import pybind11_stubgen"`, then + `${Python_EXECUTABLE} -m pybind11_stubgen `), never searched in + the `PATH`: the stubgen tool must import the modules, hence run with the + interpreter they are built for. If it is not available for this + interpreter, the stubs are simply not generated (the stubs are + optional, they shall never break a build). +2. **Multi-configuration generators** (Visual Studio) append the + configuration name to the output directory of the modules + (`mgis/Release/_mgis.pyd`), whereas `__init__.py` of the package is in + `mgis/`: importing the package from the build tree fails, which breaks + the stub generation on Windows. Fix (thelfer/tfel@e0e5a81): hold the + output directories in a generator expression, e.g. + `"$<1:${dir}>"`, so that no subdirectory is appended. Accepted + trade-off: with such a generator, the modules of the configurations + built in the same build directory overwrite each other, which is + already the case for the python tests (disabled with + multi-configuration generators). +3. `os.add_dll_directory` shall only be called on **existing** directories + (thelfer/tfel@969e4ed): the `__init__.py` scripts run when the modules + are imported from the build tree, where the `bin` directory does not + exist. (MGIS: `__init__.py` and `__init__-have-tfel.py` already guard + with `os.path.isdir`, nothing to do.) +4. On Windows, importing the modules from the build tree needs the + directories of the DLLs of the build tree (python ignores `PATH` since + 3.8): a **`sitecustomize.py`**, generated by cmake and placed in a + directory added to the `PYTHONPATH` used to run pybind11-stubgen, calls + `os.add_dll_directory` on those directories, determined from a global + property listing the libraries created by `mgis_library` (TFEL uses the + `TFEL_LIBRARIES` property, which required adding one + `set_property(GLOBAL APPEND …)` to `tfel_library_internal`). +5. The stubs are generated by a `python-stubs` target, built with the + project, and installed **next to the modules** they describe. +6. `pybind11-stubgen` is pinned to `>=3.0` in the pip build requires (the + versions below 3 are not tested). +7. `test_wheel.py` checks that the stubs are installed. +8. `py.typed`: agreed in the review (PEP 561: type checkers ignore the + stubs of an installed package without this marker), to be installed as + an empty file in each python package — not committed in TFEL yet; + MGIS shall install it too so that both packages are consistent. + +--- + +## 2. The hard part: consistency between the MGIS and TFEL wheels + +MGIS links `tfel::TFELMath` and `tfel::TFELMFrontDatabase` **PUBLICLY**, and +`MGIS_HAVE_TFEL` is a PUBLIC compile definition: TFEL is part of the ABI +MGIS exposes to its own consumers (and the python bindings import +`mfront.database`). A MGIS wheel must therefore be paired with one, and +only one, TFEL wheel. + +### 2.1 Candidate designs + +- **A. Vendor TFEL** (build TFEL from sources inside the MGIS wheel): + rebuilds all of TFEL for every python x OS cell, and duplicates the + content of `tfel-mfront` → two wheels owning the `tfel` python package, + one silently overwriting the other. **Rejected.** +- **B. Depend on the published `tfel-mfront` wheel as a build *and* run + dependency, pinned to the exact same version.** **Chosen.** +- **C. Build against TFEL workflow artifacts**: same pin problem as B and + no longer needed once `tfel-mfront` is on PyPI. Kept only as an escape + hatch (`CIBW_BEFORE_BUILD` installing a wheel from a URL) while + `tfel-mfront` is not published, which is the case today (pypi.org + answers 404 for `tfel-mfront`). **Rejected as the primary mechanism.** + +### 2.2 Design B: five complementary layers + +1. **One source of truth for the TFEL pin**: `TFEL_DEPENDENCY = + "tfel-mfront==X.Y[.Z]"` is a constant of `setup.py`; the pin is written + twice in `pyproject.toml` (`[build-system].requires` and + `[project].dependencies`) because `pyproject.toml` cannot compute it, + and `setup.py` raises if the two literal pins of `pyproject.toml` do not + match the constant. Bumping the pin is one edit + its copy. +2. **Build time**: `[build-system] requires = [..., "tfel-mfront==…"]` puts + a complete TFEL installation in pip's isolated build environment. + `setup.py` locates it with + `importlib.util.find_spec("tfel").submodule_search_locations[0]` + (no import, no library load) and configures MGIS with + `-DTFEL_DIR=/share/tfel/cmake` (+ `TFELHOME` in the environment), + `-Drequire-tfel=ON` and `-DMGIS_REQUIRED_TFEL_VERSION=`. The TFEL + wheel layout (`tfel/{bin,lib,include,share/tfel/cmake}`) is exactly what + MGIS's `FindTFEL.cmake` consumes. +3. **Configure-time assertions** (cmake changes, §4.2): the configuration + fails if TFEL is not found, if `MGIS_HAVE_MFRONT_SUPPORT` is off, if + `TFEL_PYTHON_BINDINGS` is off (the wheel needs `mfront.database`), or if + `TFEL_VERSION` differs from `MGIS_REQUIRED_TFEL_VERSION`. A wheel can + never be produced against the wrong TFEL. +4. **Run time**: `[project] dependencies = ["tfel-mfront==…"]` makes pip + install exactly the TFEL wheel MGIS was built against, and the preamble + inserted in `mgis/__init__.py` (pip variant, §4.3) checks at import + `importlib.metadata.version("tfel-mfront")` against the version baked in + at build time, and raises a clear `RuntimeError` on mismatch. This + matters because the TFEL wheel has **unversioned libraries** + (`-Dunversioned-libraries=ON`): `DT_NEEDED = libTFELMath.so` with no + soname version, so the dynamic loader cannot tell two TFEL versions + apart and would fail with an obscure `ImportError` much later. +5. **End-to-end proof in the job**: `test_wheel.py` (§5) compiles a + behaviour with the `mfront` of the TFEL wheel, loads it with + `mgis.behaviour.Behaviour` and integrates it, checks the TFEL versions + agree and the stubs are installed. A wrong toolchain/ABI/glibc + combination fails before publishing. + +### 2.3 Toolchain consistency and determinism + +The MGIS wheel links the TFEL libraries, so it must be built with the same +compiler and target as `tfel-mfront`: + +- Linux: same cibuildwheel manylinux image (`skip *-musllinux_*`, + `archs = ["x86_64"]`). The image shall be pinned explicitly + (`CIBW_MANYLINUX_X86_64_IMAGE`) in **both** projects so they cannot drift. +- macOS: `MACOSX_DEPLOYMENT_TARGET=11.0`, `archs = ["arm64"]` (as TFEL). +- Windows: same runner image (hence same MSVC), `archs = ["AMD64"]`. + +Release order: the TFEL wheels must be on PyPI first; add +`workflow_dispatch` to the MGIS workflow and document the order. + +Determinism — silent variation is a consistency bug too. `setup.py` shall +set **all** the options explicitly, in particular: + +``` +-DCMAKE_BUILD_TYPE=Release -Denable-python-bindings=ON +-Denable-portable-build=ON -Denable-testing=OFF +-Denable-website=OFF -Denable-doxygen-doc=OFF +-Denable-c-bindings=OFF -Denable-fortran-bindings=OFF +-Denable-fenics-bindings=OFF -Denable-julia-bindings=OFF +-Denable-cuda-algorithms=OFF -Denable-openmp=OFF +-Denable-exceptions=OFF -Ddisable-tfel=OFF +-Denable-hdf5-support=OFF -Denable-hdf5-automatic-support=OFF +-Drequire-tfel=ON -Denable-pybind11-stubgen=ON +-DMGIS_PYTHON_MODULES_INSTALL_DIRECTORY=site-packages +-DPython_EXECUTABLE= -Dpybind11_DIR= +``` + +`enable-hdf5-automatic-support=OFF` is essential: otherwise the content of +the wheel silently depends on whether HDF5 happens to be present in the +container. `pybind11` is copied to a fixed path (as in TFEL) so that the +changing paths of the isolated build environments do not defeat ccache. +OpenMP: OFF for v1, as in TFEL's pip build (it would tie the wheel to the +toolchain's `libgomp`); documented as a limitation. + +--- + +## 3. Wheel layout + +The `mgis` module plays the role of MGISHOME, exactly as the `tfel` module +is TFELHOME in `tfel-mfront`: + +``` +mgis/ # python package + MGISHOME + __init__.py # pip variant (see §4.3) + _mgis.cpython-3XX-*.so/.pyd + behaviour.* material_property.* model.* function.* + *.pyi # stubs + py.typed + lib/ (Windows: bin/) # libMFrontGenericInterface… + include/MGIS/… # MGIS headers (decision: ship them) + share/mgis/cmake/… # so that find_package(MFrontGenericInterface) + # also works from the wheel +``` + +`MGIS_APPEND_SUFFIX` is not used by the wheel (the package is `mgis`; the +PyPI name **`mgis` is available** — pypi.org answers 404 as of 2026-11-06 — +which is the natural name; alternative if disputed: +`mfront-generic-interface`). + +MGIS installs **no executables**, so no launcher module is needed: `mfront`, +`mtest` and `tfel-config` come from the `tfel-mfront` dependency's console +scripts. + +### Runtime paths (`set_relative_runtime_paths`, adapted from TFEL) + +Every ELF/Mach-O binary of the wheel gets a **relative** runtime path, +computed with `os.path.relpath` from its own directory to **both**: + +- `mgis/lib` (`mgis/bin` on Windows, irrelevant on ELF/Mach-O anyway), and +- the `lib` directory of the **sibling `tfel` wheel**, i.e. + `site-packages/mgis/lib/../..` → `site-packages/tfel/lib` + (`$ORIGIN/../../tfel/lib`, `@loader_path/../../tfel/lib`). The relative + path must be computed from the *installed* position: the root of the + wheel becomes `site-packages`, whereas the build directory of the package + is an arbitrary other directory, so the computation is done on simulated + `site-packages/mgis/...` paths. Computing it from the build tree gives a + path off by one level (which local tests may mask through + `LD_LIBRARY_PATH`). + +Linux: `patchelf --force-rpath --set-rpath` (`DT_RPATH`, searched before +`LD_LIBRARY_PATH`, as in TFEL); the rpath is a `:`-separated list of both +directories. macOS: `install_name_tool -delete_rpath/-add_rpath` + +`codesign --force --sign -`. Windows: nothing; the pip `__init__.py` +registers `mgis/bin` **and `tfel/bin`** with `os.add_dll_directory` +(importing `mgis` does not necessarily run `tfel/__init__.py`, and +MGIS's DLLs need TFEL's DLLs). + +### Avoiding re-vendoring TFEL (repair step) + +auditwheel (linux) and delocate (macOS) **vendor the libraries the wheel +needs which are not inside it** — that would copy the TFEL libraries of the +sibling wheel into the MGIS wheel under mangled names, and a behaviour +would then load two copies of TFEL (the exact failure TFEL disables +delvewheel for). The repair step must therefore *exclude* them: + +- linux: `CIBW_REPAIR_WHEEL_COMMAND = "auditwheel repair -w {dest_dir} + {wheel} --exclude …"`. Since auditwheel 6, `--exclude` is a + **glob** (`fnmatch`), not a regex: `libTFEL.*` silently matches nothing + and the TFEL libraries get vendored. The patterns used, `libTFEL*`, + `libMTest*`, `libMFM*`, `libMFrontQuery*`, `libMFrontLogStream*`, + `libMFrontProfiling*`, `libMFrontGenericParallelRuntime*`, behave the + same under both semantics and do not match MGIS's own + `libMFrontGenericInterface*` (verified: `libMFM*`, not `libmfm*`, is the + case of the actual library names). +- macOS: `delocate-wheel --require-archs {delocate_archs} -x …` + (`-x` is a regex). +- Windows: `repair-wheel-command = ""` (same reason as TFEL). + +`test_wheel.py` greps the wheel content or relies on the version-agreement +check to catch a regression here (a vendored `libTFELMath.so*` inside the +MGIS wheel makes the check pass silently: the real guard is the exclusion + +a check that the wheel holds no TFEL library, added to `test_wheel.py`). + +--- + +## 4. Changes required in MGIS + +### 4.1 Allow overriding the python modules destination + +`CMakeLists.txt` (lines 99-116) sets `MGIS_PYTHON_MODULES_INSTALL_DIRECTORY` +unconditionally; wrap the definition in `if(NOT +MGIS_PYTHON_MODULES_INSTALL_DIRECTORY)` so that the wheel can pass +`-DMGIS_PYTHON_MODULES_INSTALL_DIRECTORY=site-packages` (TFEL precedent: +`TFEL_PYTHON_SITE_PACKAGES_DIR`). + +### 4.2 Fail when TFEL is required but absent or not the expected one + +Next to `disable-tfel` (lines 224-234): + +```cmake +option(require-tfel "fail the configuration if TFEL is not found" OFF) +set(MGIS_REQUIRED_TFEL_VERSION "" CACHE STRING + "fail the configuration if the TFEL version is not this one") +``` + +With `require-tfel=ON`, `FATAL_ERROR` if `NOT TFEL_FOUND`, if +`MGIS_HAVE_MFRONT_SUPPORT` is off, if `TFEL_PYTHON_BINDINGS` is off, or if +`MGIS_REQUIRED_TFEL_VERSION` is non-empty and differs from `TFEL_VERSION`. +`setup.py` passes both; the normal build is unaffected. Add a job (or a +`check.yml` entry) exercising both outcomes. + +### 4.3 Pip variant of `mgis/__init__.py` + +The two existing variants only handle Windows DLL directories via +`MGISHOME` or a `../../../..` guess of the prefix — false in a wheel where +MGIS's libraries live inside the `mgis` module and TFEL's DLLs in the +sibling `tfel/bin`. Chosen mechanism (fewest cmake changes, TFEL +precedent): `setup.py` **post-processes the installed `__init__.py`**, +inserting after the `from __future__` statements a preamble which: + +- sets `MGISHOME` to the module directory (so that a `mfront` launched from + python finds MGIS's headers and libraries for `--interface=generic`), +- registers `mgis/bin` and `tfel/bin` with `os.add_dll_directory` on + Windows (guarded by `os.path.isdir`, cf. lesson 3), the `tfel` directory + being located with `importlib.util.find_spec("tfel")`, +- compares `importlib.metadata.version("tfel-mfront")` with the version + baked in by `setup.py` and raises a clear error on mismatch + (consistency layer 4; the `mfront.database` import of + `__init__-have-tfel.py` keeps working unchanged). + +### 4.4 pybind11-stubgen support (mirror of the reviewed TFEL PR #1083) + +- `option(enable-pybind11-stubgen "generates stubs for python extensions" + ON)` when `enable-python-bindings`, detection by `${Python_EXECUTABLE} -c + "import pybind11_stubgen"` (lesson 1). +- `cmake/modules/mgis.cmake`: `set_property(GLOBAL APPEND PROPERTY + MGIS_LIBRARIES ${name})` in `mgis_library()` (for the Windows DLL + directories of the build tree, lesson 4). +- A new `cmake/modules/mgis-python-modules.cmake` (or directly in + `bindings/python/src/CMakeLists.txt`, which currently defines + `mgis_python_module`): + - `mgis_python_module` sets `LIBRARY_OUTPUT_DIRECTORY` to + `"$<1:${MGIS_PYTHON_MODULES_BUILD_DIR}/mgis>"` (or `mgis_` when + `MGIS_APPEND_SUFFIX`), so that the modules are next to the + `__init__.py` of the package in the build tree (lesson 2 — MGIS does + not set an output directory at all today: the modules go to + `bindings/python/src/`, and the tests assemble a package by + **symlinks** in `bindings/python/tests/mgis/`; the symlink assembly can + stay as it is); + - a `python_module_stubgen(target package name)` function registering + `${target}:${module}` in a global property, called from + `mgis_python_module` for `_mgis`, `behaviour`, `material_property`, + `model`, `function` (respecting `MGIS_APPEND_SUFFIX` for the package + name); + - a `generate_python_stubs()` function, called at the end of the main + `CMakeLists.txt` (after all `add_subdirectory`), generating with + `${Python_EXECUTABLE} -m pybind11_stubgen --output-dir + ${MGIS_PYTHON_MODULES_BUILD_DIR}` a `python-stubs` custom target (ALL), + installing the `.pyi` files next to the modules in + `${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY}`; + - the build-tree package directory also gets a copy of the `__init__.py` + variant selected at configure time (`file(CONFIGURE …)` / + `configure_file`), as importing `mgis` runs it; + - Windows: the generated `sitecustomize.py` (lesson 4) registers, in + addition to the build-tree DLL directories from `MGIS_LIBRARIES`, the + `bin` directory of the TFEL installation (from `TFELHOME`) so that the + TFEL DLLs needed by `_mgis` are found. +- Install an empty `py.typed` marker in the `mgis` package (PEP 561; + lesson 8 — coordinate with TFEL, which has agreed to do the same). + +### 4.5 Relocatable cmake package (verification only) + +`MFrontGenericInterfaceConfig.cmake.in` already resolves TFEL through +`TFEL_DIR` / `TFELHOME` / `$ENV{TFELHOME_}` — the variable the +TFEL wheel sets at `import tfel`. Risk to check during implementation: +`install(EXPORT … EXPORT_LINK_INTERFACE_LIBRARIES)` may record absolute +TFEL paths from TFEL's own `Targets.cmake`. `test_wheel.py` runs a tiny +`find_package(MFrontGenericInterface)` project against the wheel's +`share/mgis/cmake` to prove it. + +### 4.6 Versioned libraries + +Contrary to an earlier reading of `cmake/modules/mgis.cmake`, the MGIS +libraries are **not** versioned: the `VERSION "${PROJECT_VERSION}"` there +only feeds `write_basic_package_version_file` (the cmake package version), +not the libraries. The installation holds a single unversioned +`libMFrontGenericInterface.so`, without soname version nor development +symlink, so the wheel layout has nothing to dereference and +`materialize_symlinks` in `setup.py` is only a safety net. + +The TFEL libraries, on the other hand, have a *versioned soname* +(`libTFELMath.so.5.2.0-dev`): a mismatched `tfel-mfront` version manifests +itself as a dynamic linker error, which the check inserted in +`mgis/__init__.py` (and the `MGIS_REQUIRED_TFEL_VERSION` check of cmake) +report earlier and more clearly. + +--- + +## 5. New files: `bindings/python/pip/` + +- `pyproject.toml`: + - `[build-system] requires = ["setuptools>=64", "cmake>=3.20", + "pybind11>=2.12", "pybind11-stubgen>=3.0", "numpy>=2.0", + "tfel-mfront==X.Y.Z", "patchelf; sys_platform == 'linux'"]`; + - `[project] name = "mgis"`, `dynamic = ["version"]` (from + `project("mfront-generic-interface" VERSION …)` of `CMakeLists.txt`, + `-dev` → `.dev0`), `requires-python = ">=3.9"`, + `dependencies = ["numpy", "tfel-mfront==X.Y.Z"]`; license CeCILL-C; + `[tool.setuptools] packages = [] py-modules = []`; + - `[tool.cibuildwheel] build-verbosity = 1`, `skip = ["*-musllinux_*"]`, + `test-command = "python {package}/test_wheel.py"`, per-OS archs as in + §2.3 and the repair commands of §3. +- `setup.py`: version pin guard + TFEL discovery (§2.2-2) + cmake + configure/build/install with the options of §2.3 + `layout_package()` + (copy `site-packages/*` at the wheel root, `bin`/`lib`/`include`/`share` + into `mgis/`) + `__init__.py` preamble insertion (§4.3) + + `set_relative_runtime_paths()` with the two rpath entries (§3) + + `BinaryDistribution` (`has_ext_modules`) + the whole thing driven from a + `build_ext` subclass (the only build command run when no python package + is declared to setuptools). +- `test_wheel.py`, run by cibuildwheel in a fresh venv containing the + built wheel (pip pulls the `tfel-mfront` dependency with it): + 1. `import mgis, mgis.behaviour, mgis.material_property, mgis.model, + mgis.function, mfront.database` (the last one through `import mgis`), + 2. assert the TFEL version check passed and `mgis.behaviour` reports the + expected `MGIS_HAVE_TFEL` features, + 3. assert no TFEL library was vendored into the wheel (§3), + 4. assert the `.pyi` stubs and `py.typed` are installed next to the + modules (lessons 7 and 8), + 5. on non-Windows: write `Elasticity.mfront`, run the wheel's `mfront + --obuild --interface=generic` (the `MGISHOME` and `TFELHOME` set by + `import mgis` and the tfel launcher are inherited), load the library + with `mgis.behaviour.Behaviour`, `mgis.behaviour.integrate` a uniaxial + strain, check `S_XX ≈ 150e6` against the analytic result — the + end-to-end consistency layer, + 6. on non-Windows: `cmake -find_package(MFrontGenericInterface)` on a + tiny project against the wheel's `share/mgis/cmake` (§4.5). + +--- + +## 6. New workflow: `.github/workflows/python-pip.yml` + +Copy of TFEL's with the following deltas: + +- triggers: push on the tags `MFrontGenericInterfaceSupport-[0-9]+.[0-9]+.*` + (the repo's release tags have both `x.y` and `x.y.z` forms — confirm the + convention for tagged wheel releases), push/PR on `master`, plus + `workflow_dispatch` (release order: TFEL first). +- matrix `os x python` exactly as TFEL (cp39…cp315, cp312 on PRs). +- ccache: reuse this repo's `.github/actions/{setup,save}-ccache` — to be + verified they expose the `key:` input and the `msvc.cmake` toolchain TFEL + versions provide; MGIS's actions were built for the spack/OCI + buildcache flows. One cache per OS (`key: wheel-`), saved by the + cp312 job; inside the manylinux container, static musl ccache via + `CIBW_BEFORE_ALL_LINUX` (HTTPS only) and `CCACHE_DIR=/host/ccache`. +- `pypa/cibuildwheel@v4.3.2`, `package-dir: bindings/python/pip`, + `output-dir: wheelhouse`, `CIBW_BUILD: ${{ matrix.python }}-*`. +- artifact `mgis-wheel-${{ os }}-${{ python }}`. +- `publish-pypi` and `publish-github-release`, both + `if: push && startsWith(github.ref, 'refs/tags/MFrontGenericInterfaceSupport-')`. + +--- + +## 7. Open questions + +1. **PyPI name**: `mgis` (available, recommended) vs + `mfront-generic-interface`. Note that a `mgis` conda/pip ecosystem name + clash, if any, is with an unrelated project only if one appears later; + reserving it early is an argument for acting now. +2. **Tag convention** the publish jobs key on (see §6). +3. **Pin strictness**: `tfel-mfront==X.Y.Z` recommended for v1 (the TFEL + wheel libraries carry a versioned soname, `libTFELMath.so.5.2.0-dev`, + so an untested TFEL would fail to load obscurely rather than silently; + the exact pin makes the failure explicit). Relax once the policy is + proven. +4. **MGIS dev version wheels**: TFEL maps `5.2-dev` → `5.2.dev0`; the same + mapping applies (`3.1.0` + `MFrontGenericInterfaceSupportDevelopmentVersion + ON` → `3.1.0.dev0`). Dev MGIS wheels must depend on a published TFEL + version, not a dev one (the pin is a PyPI requirement). +5. OpenMP OFF in the wheel (v1): accepted? (perf-sensitive users can build + from sources.) +6. Shipping `include/` + `share/` in the wheel: recommendation is yes + (cheap, keeps MGISHOME semantics identical to a normal install; needed + for `mfront --interface=generic` from python, which is how the wheel is + tested end-to-end). +7. `tfel-mfront` is **not on PyPI yet**: prototype against a locally built + TFEL wheel (`pip wheel` of the TFEL clone, `--find-links` + a pinned dev + version) until TFEL releases wheels; the PR job can even build the TFEL + wheel first in a preceding job (escape hatch C of §2.1). + +## 8. Implementation order + +1. CMake: §4.1 + §4.2 (+ a CI job exercising `require-tfel` success/failure). +2. CMake: §4.4 stubgen (single- and multi-config generators; a + `cmake-ninja-multi-config`-style job already exists in this repo to + smoke-test lesson 2). +3. `bindings/python/pip/{pyproject.toml,setup.py}` + `test_wheel.py`. +4. Locally: `pipx run cibuildwheel --print-build-identifiers`, then one + cell (`CIBW_BUILD=cp312-manylinux_x86_64 … --platform linux`) against a + locally built `tfel-mfront` wheel exposed with `--find-links`. +5. `.github/workflows/python-pip.yml`; iterate on the PR (cp312 only). +6. Docs: install page for the wheel + release notes (avoid TFEL's + mistake of linking a missing install-pip page). + +## 9. Findings of the local validation (against a simulated tfel-mfront) + +The wheel was built and tested locally with `--no-build-isolation` against +a directory simulating the tfel-mfront wheel layout (a `tfel` package +holding `bin`, `lib`, `include` and `share`, plus a `tfel_mfront` +dist-info), then installed in fresh virtual environments, tested with and +without an `auditwheel repair`, with `LD_LIBRARY_PATH`, `PYTHONPATH` and +`TFELHOME` unset. Everything below was verified, not reasoned: + +1. **The auditwheel excludes work and are necessary**: without them, + `libTFELSystem-.so.5.2.0-dev` and friends are grafted into + `mgis.libs/` of the MGIS wheel. The patterns are globs since auditwheel + 6 (`libTFEL*`, ...), cf. §3. +2. **The `tfel/lib` directory survives the repair of the tfel-mfront wheel + itself**: repairing a simulated tfel-mfront wheel leaves the libraries + with their original names in `tfel/lib` (auditwheel only grafts hashed + copies of the libraries needed by the TFEL extension modules, and does + not touch data files). The sibling relative runtime path of the MGIS + wheel therefore always finds its TFEL, whatever repair policy TFEL + chooses. (The default policy does make the TFEL wheel carry its + libraries twice, and register two consumers of the same versioned + sonames; worth reporting upstream, but harmless for MGIS.) +3. **The relative runtime paths are those of the installed layout** + (computed in a simulated `site-packages`, cf. §3): + `libMFrontGenericInterface.so` gets `$ORIGIN:$ORIGIN/../../tfel/lib` as + `DT_RPATH`, the extension modules `$ORIGIN/lib:$ORIGIN/../tfel/lib`. +4. **The version guard fires**: with the metadata of the installed + tfel-mfront changed, `import mgis` raises `RuntimeError: this mgis + wheel was built against tfel-mfront 5.2.0.dev0, but version 9.9.9 is + installed`, rather than failing later in the dynamic loader. +5. **The wheel is usable as a MGISHOME**: `test_wheel.py` compiles a + behaviour with the `mfront` of the tfel wheel, integrates it through + `mgis.behaviour` (exact value of the elastic stress), and builds a + consumer project with `find_package(MFrontGenericInterface)` against the + wheel, which loads the behaviour in C++ — for both the raw and the + repaired wheel, in a clean environment. From 2ba2e007cd4c6e0cbdaba0317b89995f553ba314 Mon Sep 17 00:00:00 2001 From: Thomas Helfer Date: Fri, 6 Nov 2026 11:33:45 +0100 Subject: [PATCH 04/14] ci: job building and publishing the wheels of the mgis package cibuildwheel builds the wheels of the python bindings for cp39 to cp315 on linux x86_64, macOS arm64 and windows AMD64 (configuration in bindings/python/pip/pyproject.toml), and runs test_wheel.py on them. Only one python version, cp312, is built for the pull requests. The compilations of the linux and macOS wheels use the ccache actions of the repository, shared by the versions of python through the key wheel-. The Windows build is not accelerated: the ccache actions only support Linux and macOS. The wheels are published to PyPI and attached to the GitHub release when a MFrontGenericInterfaceSupport tag is pushed, which also requires the tfel-mfront wheel the package depends on to be published (cf. issue #254). --- .github/workflows/python-pip.yml | 127 +++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 .github/workflows/python-pip.yml diff --git a/.github/workflows/python-pip.yml b/.github/workflows/python-pip.yml new file mode 100644 index 000000000..eea0745da --- /dev/null +++ b/.github/workflows/python-pip.yml @@ -0,0 +1,127 @@ +name: Build and Publish Python Pip Package + +on: + push: + tags: + - 'MFrontGenericInterfaceSupport-[0-9]+.[0-9]+*' + branches: + - master + pull_request: + branches: + - master + +jobs: + build-wheels: + name: Build wheel (${{ matrix.os }}, ${{ matrix.python }}) + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest, windows-latest] + # all the python versions on master and for the tags, only one + # for the pull requests + python: ${{ github.event_name == 'pull_request' && fromJSON('["cp312"]') || fromJSON('["cp39", "cp310", "cp311", "cp312", "cp313", "cp314", "cp315"]') }} + + steps: + - uses: actions/checkout@v4 + + # one cache per system, shared by the versions of python and saved by the + # job of the version also built for the pull requests. The ccache actions + # only support Linux and macOS, which are the systems of the builds of + # check.yml: the build of the windows wheel is not accelerated + - name: Set up ccache + id: ccache + if: matrix.os != 'windows-latest' + uses: ./.github/actions/setup-ccache + with: + key: wheel-${{ matrix.os }} + + # the environment variables CMAKE_C_COMPILER_LAUNCHER and + # CMAKE_CXX_COMPILER_LAUNCHER are used by cmake, including when it is + # run by setup.py inside the build container of cibuildwheel + - name: Use ccache in the builds + if: matrix.os != 'windows-latest' + shell: bash + run: | + echo "CMAKE_C_COMPILER_LAUNCHER=ccache" >> "$GITHUB_ENV" + echo "CMAKE_CXX_COMPILER_LAUNCHER=ccache" >> "$GITHUB_ENV" + + # on Linux, the wheels are built in a container which mounts the file + # system of the runner on /host, where ccache is not installed: the + # static musl build of ccache is copied into the container + # + # see bindings/python/pip/pyproject.toml for the configuration + # of cibuildwheel and bindings/python/pip/setup.py for the build + - name: Build and test the wheel + uses: pypa/cibuildwheel@v4.3.2 + with: + package-dir: bindings/python/pip + output-dir: wheelhouse + env: + CIBW_BUILD: ${{ matrix.python }}-* + CIBW_BEFORE_ALL_LINUX: >- + curl --proto '=https' -sSfL https://github.com/ccache/ccache/releases/download/v4.14.2/ccache-4.14.2-linux-x86_64-musl-static.tar.gz + | tar xz --strip-components=1 -C /usr/local/bin ccache-4.14.2-linux-x86_64-musl-static/ccache + # files writable by the runner, which removes the unused ones (save-ccache) + CIBW_ENVIRONMENT_LINUX: >- + CCACHE_DIR=/host${{ runner.temp }}/ccache CCACHE_MAXSIZE=1G CCACHE_UMASK=000 + CMAKE_C_COMPILER_LAUNCHER=ccache CMAKE_CXX_COMPILER_LAUNCHER=ccache + + - name: Save ccache + if: ${{ matrix.os != 'windows-latest' && !cancelled() && steps.ccache.outcome == 'success' && matrix.python == 'cp312' }} + uses: ./.github/actions/save-ccache + + - name: Upload Pip Wheel as Artifact + uses: actions/upload-artifact@v4 + with: + name: mgis-wheel-${{ matrix.os }}-${{ matrix.python }} + path: wheelhouse/*.whl + + publish-pypi: + name: Publish to PyPI + needs: build-wheels + runs-on: ubuntu-latest + if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/MFrontGenericInterfaceSupport-') + + steps: + - name: Download All Artifacts + uses: actions/download-artifact@v4 + with: + path: ${{github.workspace}}/artifacts + pattern: mgis-wheel-* + merge-multiple: true + + - name: List Downloaded Artifacts + run: | + ls -R ${{github.workspace}}/artifacts + + - name: Publish to PyPI + uses: pypa/gh-action-pypi-publish@release/v1 + with: + packages-dir: ${{github.workspace}}/artifacts/ + password: ${{ secrets.PYPI_API_TOKEN }} + verbose: true + + publish-github-release: + name: Publish to GitHub Release + needs: build-wheels + runs-on: ubuntu-latest + if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/MFrontGenericInterfaceSupport-') + permissions: + contents: write + + steps: + - name: Download All Artifacts + uses: actions/download-artifact@v4 + with: + path: ${{github.workspace}}/release-artifacts + pattern: mgis-wheel-* + merge-multiple: true + + - name: Create GitHub Release + uses: softprops/action-gh-release@v2 + with: + files: ${{github.workspace}}/release-artifacts/**/*.whl + generate_release_notes: true + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} From 0fd9d874ec445e60263b2ea67da62a190e9c2138 Mon Sep 17 00:00:00 2001 From: Thomas Helfer Date: Fri, 6 Nov 2026 11:34:47 +0100 Subject: [PATCH 05/14] docs: installation of the python bindings using pip --- docs/web/install.md | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/web/install.md b/docs/web/install.md index 870ab269b..0b2d519d5 100644 --- a/docs/web/install.md +++ b/docs/web/install.md @@ -111,6 +111,26 @@ generated by the `TFEL` project. This allows several versions of `MGIS` to be installed in the same prefix. +# Installing using `pip` + +Binary wheels of the `python` bindings are available on the Python +Package Index: + +~~~~{.bash} +$ pip install mgis +~~~~ + +The wheel contains the `MGIS` library, headers and `cmake` package, in +addition to the `python` modules, so that behaviours can be compiled and +solvers built using it. It requires a `C++` compiler to compile `MFront` +implementations, and depends on the `tfel-mfront` wheel, pinned to the +version of `TFEL` it has been built against: the `TFEL` libraries are not +duplicated in the `MGIS` wheel and a single consistent pair of wheels is +installed. + +Wheels are provided for `Linux` (`x86_64`), `macOS` (`arm64`) and +`Windows` (`AMD64`), for `python` versions 3.9 and above. + # Installing using `spack` `spack` is flexible package manager (https://spack.io/). From 5b834537a8040b235292ec5388bbc5a7e1e946b6 Mon Sep 17 00:00:00 2001 From: t Date: Fri, 6 Nov 2026 15:08:45 +0100 Subject: [PATCH 06/14] cmake: the generation of the stubs extends PYTHONPATH instead of replacing it pybind11-stubgen and the python bindings of TFEL may only be found through this variable, as in the isolated build environments of pip: pip wheel and pip install from the sources stopped with "No module named pybind11_stubgen". --- cmake/modules/mgis-python-modules.cmake | 18 +++++++++++++++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/cmake/modules/mgis-python-modules.cmake b/cmake/modules/mgis-python-modules.cmake index 1529e087d..1ef465397 100644 --- a/cmake/modules/mgis-python-modules.cmake +++ b/cmake/modules/mgis-python-modules.cmake @@ -142,10 +142,22 @@ for _directory in dict.fromkeys((r\"${mgis_stubgen_library_directories}\", )): if os.path.isdir(_directory): os.add_dll_directory(_directory) ") - # the two paths of the PYTHONPATH variable are separated by a semicolon - string(REPLACE ";" "$" mgis_stubgen_pythonpath - "${mgis_stubgen_sitecustomize_directory};${MGIS_PYTHON_MODULES_BUILD_DIR}") + set(mgis_stubgen_pythonpath + "${mgis_stubgen_sitecustomize_directory};${MGIS_PYTHON_MODULES_BUILD_DIR}") endif(WIN32) + # The PYTHONPATH variable is extended, not replaced: pybind11-stubgen and + # the python bindings of TFEL may only be found through it, as in the + # isolated build environments of pip. + if(NOT "$ENV{PYTHONPATH}" STREQUAL "") + if(WIN32) + string(APPEND mgis_stubgen_pythonpath ";$ENV{PYTHONPATH}") + else(WIN32) + string(APPEND mgis_stubgen_pythonpath ":$ENV{PYTHONPATH}") + endif(WIN32) + endif() + # the paths of the PYTHONPATH variable are separated by a semicolon on windows + string(REPLACE ";" "$" mgis_stubgen_pythonpath + "${mgis_stubgen_pythonpath}") set(pybind11_stubgen_files) foreach(entry ${MGIS_PYTHON_STUBGEN_MODULES}) string(REGEX REPLACE "^[^:]*:" "" module "${entry}") From 034c104323b2692cfeb0e5d23fddce71fd56ecb5 Mon Sep 17 00:00:00 2001 From: t Date: Fri, 6 Nov 2026 15:08:45 +0100 Subject: [PATCH 07/14] cmake: install the py.typed marker only if the stubs are generated Without stubs, this marker makes mypy report the modules as not found, as pybind11 modules do not provide any type information by themselves. --- bindings/python/mgis/CMakeLists.txt | 5 ----- cmake/modules/mgis-python-modules.cmake | 5 +++++ 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/bindings/python/mgis/CMakeLists.txt b/bindings/python/mgis/CMakeLists.txt index 401ed1694..1a83cc56e 100644 --- a/bindings/python/mgis/CMakeLists.txt +++ b/bindings/python/mgis/CMakeLists.txt @@ -10,11 +10,6 @@ install(FILES ${mgis_python_init_script} DESTINATION ${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY} COMPONENT python_bindings RENAME __init__.py) -# PEP 561 marker: the package installs the .pyi stubs of its pybind11 -# modules, which type checkers only use if this marker is present -install(FILES py.typed - DESTINATION ${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY} - COMPONENT python_bindings) # In the build tree, the package directory where the modules are placed # needs the __init__.py script so that the package can be imported, which # pybind11-stubgen requires to generate the stubs. diff --git a/cmake/modules/mgis-python-modules.cmake b/cmake/modules/mgis-python-modules.cmake index 1ef465397..501e0e9a0 100644 --- a/cmake/modules/mgis-python-modules.cmake +++ b/cmake/modules/mgis-python-modules.cmake @@ -176,6 +176,11 @@ for _directory in dict.fromkeys((r\"${mgis_stubgen_library_directories}\", )): DESTINATION "${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY}" COMPONENT python_bindings) endforeach(entry ${MGIS_PYTHON_STUBGEN_MODULES}) + # PEP 561 marker: type checkers only use the stubs of an installed package + # if it holds this marker. Without stubs, it would make them fail. + install(FILES "${PROJECT_SOURCE_DIR}/bindings/python/mgis/py.typed" + DESTINATION "${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY}" + COMPONENT python_bindings) add_custom_target(python-stubs ALL DEPENDS ${pybind11_stubgen_files}) endfunction(generate_python_stubs) From 3d7b51f76c73a278c1589ba196d6fbfabcc3ecac Mon Sep 17 00:00:00 2001 From: t Date: Fri, 6 Nov 2026 15:18:06 +0100 Subject: [PATCH 08/14] python: python names of the types in the signatures of the behaviour and model modules A type declared after a function using it appears by its C++ name in the signature of this function. pybind11-stubgen can not handle such a name, which left "..." or a type which does not exist in the stubs: s0 and s1 of MaterialDataManager and of its initializer, make_view, and the functions of the model module. --- bindings/python/src/behaviour-module.cxx | 6 ++++-- bindings/python/src/model-module.cxx | 11 ++++++++++- 2 files changed, 14 insertions(+), 3 deletions(-) diff --git a/bindings/python/src/behaviour-module.cxx b/bindings/python/src/behaviour-module.cxx index 49f9ac355..706a0e15f 100644 --- a/bindings/python/src/behaviour-module.cxx +++ b/bindings/python/src/behaviour-module.cxx @@ -33,10 +33,12 @@ PYBIND11_MODULE(behaviour, m) { declareBehaviourDescription(m); declareBehaviour(m); declareState(m); - declareBehaviourData(m); + // a class shall be declared before the functions and the classes using it, + // so that it appears by its python name in their signatures declareBehaviourDataView(m); - declareMaterialDataManager(m); + declareBehaviourData(m); declareMaterialStateManager(m); + declareMaterialDataManager(m); declareIntegrate(m); declareFiniteStrainSupport(m); } // end of module behaviour diff --git a/bindings/python/src/model-module.cxx b/bindings/python/src/model-module.cxx index 361fd83fb..702243924 100644 --- a/bindings/python/src/model-module.cxx +++ b/bindings/python/src/model-module.cxx @@ -12,9 +12,18 @@ * CeCILL-C_V1-en.txt and CeCILL-C_V1-fr.txt). */ +#include #include // forward declaration void declareModel(pybind11::module_&); -PYBIND11_MODULE(model, m) { declareModel(m); } // end of module model +PYBIND11_MODULE(model, m) { + // the types of the signatures of this module are declared by the behaviour + // module, which shall thus be loaded first, so that they appear by their + // python names. The name of the package depends on the suffix of MGIS. + const auto name = m.attr("__name__").cast(); + pybind11::module_::import( + (name.substr(0, name.rfind('.')) + ".behaviour").c_str()); + declareModel(m); +} // end of module model From 5a5c56c3943cba37bdaf23ba175f0d9cb58b5ad5 Mon Sep 17 00:00:00 2001 From: t Date: Fri, 6 Nov 2026 15:18:31 +0100 Subject: [PATCH 09/14] python: names of the arguments of the behaviour module The stubs generated by pybind11-stubgen showed these arguments as arg0, arg1, and they can now be passed by keyword. The special methods and the setters of the properties are left as they are. --- bindings/python/src/Behaviour.cxx | 67 ++++++++++++------- bindings/python/src/BehaviourData.cxx | 7 +- bindings/python/src/BehaviourDescription.cxx | 65 ++++++++++-------- bindings/python/src/FiniteStrainSupport.cxx | 7 +- bindings/python/src/Integrate.cxx | 69 +++++++++++++------- bindings/python/src/MaterialDataManager.cxx | 12 ++-- bindings/python/src/MaterialStateManager.cxx | 68 +++++++++++++------ bindings/python/src/State.cxx | 13 ++-- bindings/python/src/Variable.cxx | 17 +++-- 9 files changed, 213 insertions(+), 112 deletions(-) diff --git a/bindings/python/src/Behaviour.cxx b/bindings/python/src/Behaviour.cxx index 76cc9a221..c8c316fa7 100644 --- a/bindings/python/src/Behaviour.cxx +++ b/bindings/python/src/Behaviour.cxx @@ -245,40 +245,63 @@ void declareBehaviour(pybind11::module_ &m) { pybind11::class_(m, "Behaviour") // pybind11::class_("Behaviour") .def("getInitializeFunctionsNames", Behaviour_getInitializeFunctionsNames) - .def("getInitializeFunctionInputs", Behaviour_getInitializeFunctionInputs) + .def("getInitializeFunctionInputs", Behaviour_getInitializeFunctionInputs, + "name"_a) .def("getPostProcessingsNames", Behaviour_getPostProcessingsNames) - .def("getPostProcessingOutputs", Behaviour_getPostProcessingOutputs) - .def("setParameter", setParameter1) - .def("setIntegerParameter", setParameter2) - .def("setUnsignedShortParameter", setParameter3) - .def("rotateGradients", rotate_gradients_in_place_member) - .def("rotateGradients", rotate_gradients_out_of_place_member) + .def("getPostProcessingOutputs", Behaviour_getPostProcessingOutputs, + "name"_a) + .def("setParameter", setParameter1, "name"_a, "value"_a) + .def("setIntegerParameter", setParameter2, "name"_a, "value"_a) + .def("setUnsignedShortParameter", setParameter3, "name"_a, "value"_a) + .def("rotateGradients", rotate_gradients_in_place_member, "gradients"_a, + "rotation_matrix"_a) + .def("rotateGradients", rotate_gradients_out_of_place_member, + "material_frame_gradients"_a, "global_frame_gradients"_a, + "rotation_matrix"_a) .def("rotateThermodynamicForces", - rotate_thermodynamic_forces_in_place_member) + rotate_thermodynamic_forces_in_place_member, + "thermodynamic_forces"_a, "rotation_matrix"_a) .def("rotateThermodynamicForces", - rotate_thermodynamic_forces_out_of_place_member) + rotate_thermodynamic_forces_out_of_place_member, + "global_frame_thermodynamic_forces"_a, + "material_frame_thermodynamic_forces"_a, "rotation_matrix"_a) .def("rotateTangentOperatorBlocks", - rotate_tangent_operator_blocks_in_place_member) + rotate_tangent_operator_blocks_in_place_member, + "tangent_operator_blocks"_a, "rotation_matrix"_a) .def("rotateTangentOperatorBlocks", - rotate_tangent_operator_blocks_out_of_place_member); + rotate_tangent_operator_blocks_out_of_place_member, + "global_frame_tangent_operator_blocks"_a, + "material_frame_tangent_operator_blocks"_a, "rotation_matrix"_a); // wrapping free functions - m.def("rotateGradients", rotate_gradients_in_place); - m.def("rotateGradients", rotate_gradients_out_of_place); - m.def("rotateThermodynamicForces", rotate_thermodynamic_forces_in_place); - m.def("rotateThermodynamicForces", rotate_thermodynamic_forces_out_of_place); - m.def("rotateTangentOperatorBlocks", rotate_tangent_operator_blocks_in_place); + m.def("rotateGradients", rotate_gradients_in_place, "gradients"_a, + "behaviour"_a, "rotation_matrix"_a); + m.def("rotateGradients", rotate_gradients_out_of_place, + "material_frame_gradients"_a, "behaviour"_a, "global_frame_gradients"_a, + "rotation_matrix"_a); + m.def("rotateThermodynamicForces", rotate_thermodynamic_forces_in_place, + "thermodynamic_forces"_a, "behaviour"_a, "rotation_matrix"_a); + m.def("rotateThermodynamicForces", rotate_thermodynamic_forces_out_of_place, + "global_frame_thermodynamic_forces"_a, "behaviour"_a, + "material_frame_thermodynamic_forces"_a, "rotation_matrix"_a); + m.def("rotateTangentOperatorBlocks", rotate_tangent_operator_blocks_in_place, + "tangent_operator_blocks"_a, "behaviour"_a, "rotation_matrix"_a); m.def("rotateTangentOperatorBlocks", - rotate_tangent_operator_blocks_out_of_place); + rotate_tangent_operator_blocks_out_of_place, + "global_frame_tangent_operator_blocks"_a, "behaviour"_a, + "material_frame_tangent_operator_blocks"_a, "rotation_matrix"_a); - m.def("load", load_ptr); - m.def("load", load_ptr2); + m.def("load", load_ptr, "library"_a, "behaviour"_a, "hypothesis"_a); + m.def("load", load_ptr2, "options"_a, "library"_a, "behaviour"_a, + "hypothesis"_a); m.def("loadFromDatabase", Behaviour_loadFromDatabase, "name"_a, "hypothesis"_a, "material"_a = std::optional{}); m.def("loadFromDatabase", Behaviour_loadFromDatabase2, "options"_a, "name"_a, "hypothesis"_a, "material"_a = std::optional{}); - m.def("setParameter", setParameter1); - m.def("setIntegerParameter", setParameter2); - m.def("setUnsignedShortParameter", setParameter3); + m.def("setParameter", setParameter1, "behaviour"_a, "name"_a, "value"_a); + m.def("setIntegerParameter", setParameter2, "behaviour"_a, "name"_a, + "value"_a); + m.def("setUnsignedShortParameter", setParameter3, "behaviour"_a, "name"_a, + "value"_a); } // end of declareBehaviour diff --git a/bindings/python/src/BehaviourData.cxx b/bindings/python/src/BehaviourData.cxx index 327af0056..03bf9735e 100644 --- a/bindings/python/src/BehaviourData.cxx +++ b/bindings/python/src/BehaviourData.cxx @@ -39,6 +39,7 @@ static std::string BehaviourData_getErrorMessage( } // end of BehaviourData_getErrorMessage void declareBehaviourData(pybind11::module_& m) { + using namespace pybind11::literals; using mgis::behaviour::Behaviour; using mgis::behaviour::BehaviourData; using mgis::behaviour::BehaviourDataView; @@ -63,7 +64,7 @@ void declareBehaviourData(pybind11::module_& m) { // free functions BehaviourDataView (*ptr_make_view)(BehaviourData&) = &mgis::behaviour::make_view; - m.def("update", ptr_update); - m.def("revert", ptr_revert); - m.def("make_view", ptr_make_view, pybind11::keep_alive<0, 1>()); + m.def("update", ptr_update, "data"_a); + m.def("revert", ptr_revert, "data"_a); + m.def("make_view", ptr_make_view, "data"_a, pybind11::keep_alive<0, 1>()); } // end of declareBehaviourData diff --git a/bindings/python/src/BehaviourDescription.cxx b/bindings/python/src/BehaviourDescription.cxx index 214a33980..bf3ad3778 100644 --- a/bindings/python/src/BehaviourDescription.cxx +++ b/bindings/python/src/BehaviourDescription.cxx @@ -109,6 +109,7 @@ BehaviourDescription_getTangentOperatorBlocks( } // end of BehaviourDescription_getTangentOperatorBlocks void declareBehaviourDescription(pybind11::module_ &m) { + using namespace pybind11::literals; using mgis::behaviour::BehaviourDescription; // double (*getParameterDefaultValue1)(const BehaviourDescription &, @@ -275,38 +276,48 @@ void declareBehaviourDescription(pybind11::module_ &m) { "list of unsigned short parameters (same as the `usparams` property)") .def_property_readonly("tangent_operator_blocks", BehaviourDescription_getTangentOperatorBlocks) - .def("getParameterDefaultValue", getParameterDefaultValue1) - .def("getIntegerParameterDefaultValue", getParameterDefaultValue2) - .def("getUnsignedShortParameterDefaultValue", getParameterDefaultValue3) - .def("hasBounds", hasBounds) - .def("hasLowerBound", hasLowerBound) - .def("hasUpperBound", hasUpperBound) - .def("getLowerBound", getLowerBound) - .def("getUpperBound", getUpperBound) - .def("hasPhysicalBounds", hasPhysicalBounds) - .def("hasLowerPhysicalBound", hasLowerPhysicalBound) - .def("hasUpperPhysicalBound", hasUpperPhysicalBound) - .def("getLowerPhysicalBound", getLowerPhysicalBound) - .def("getUpperPhysicalBound", getUpperPhysicalBound); + .def("getParameterDefaultValue", getParameterDefaultValue1, "name"_a) + .def("getIntegerParameterDefaultValue", getParameterDefaultValue2, + "name"_a) + .def("getUnsignedShortParameterDefaultValue", getParameterDefaultValue3, + "name"_a) + .def("hasBounds", hasBounds, "name"_a) + .def("hasLowerBound", hasLowerBound, "name"_a) + .def("hasUpperBound", hasUpperBound, "name"_a) + .def("getLowerBound", getLowerBound, "name"_a) + .def("getUpperBound", getUpperBound, "name"_a) + .def("hasPhysicalBounds", hasPhysicalBounds, "name"_a) + .def("hasLowerPhysicalBound", hasLowerPhysicalBound, "name"_a) + .def("hasUpperPhysicalBound", hasUpperPhysicalBound, "name"_a) + .def("getLowerPhysicalBound", getLowerPhysicalBound, "name"_a) + .def("getUpperPhysicalBound", getUpperPhysicalBound, "name"_a); m.def("isStandardFiniteStrainBehaviour", - mgis::behaviour::isStandardFiniteStrainBehaviour, + mgis::behaviour::isStandardFiniteStrainBehaviour, "library"_a, + "behaviour"_a, "return if the given behaviour is a standard finite strain behaviour, " "i.e. is a finite strain behaviour using the standard finite strain " "kinematic (called F-Cauchy although the stress measure can be chosen " "when loading the behaviour)"); - m.def("getParameterDefaultValue", getParameterDefaultValue1); - m.def("getIntegerParameterDefaultValue", getParameterDefaultValue2); - m.def("getUnsignedShortParameterDefaultValue", getParameterDefaultValue3); - m.def("hasBounds", hasBounds); - m.def("hasLowerBound", hasLowerBound); - m.def("hasUpperBound", hasUpperBound); - m.def("getLowerBound", getLowerBound); - m.def("getUpperBound", getUpperBound); - m.def("hasPhysicalBounds", hasPhysicalBounds); - m.def("hasLowerPhysicalBound", hasLowerPhysicalBound); - m.def("hasUpperPhysicalBound", hasUpperPhysicalBound); - m.def("getLowerPhysicalBound", getLowerPhysicalBound); - m.def("getUpperPhysicalBound", getUpperPhysicalBound); + m.def("getParameterDefaultValue", getParameterDefaultValue1, "behaviour"_a, + "name"_a); + m.def("getIntegerParameterDefaultValue", getParameterDefaultValue2, + "behaviour"_a, "name"_a); + m.def("getUnsignedShortParameterDefaultValue", getParameterDefaultValue3, + "behaviour"_a, "name"_a); + m.def("hasBounds", hasBounds, "behaviour"_a, "name"_a); + m.def("hasLowerBound", hasLowerBound, "behaviour"_a, "name"_a); + m.def("hasUpperBound", hasUpperBound, "behaviour"_a, "name"_a); + m.def("getLowerBound", getLowerBound, "behaviour"_a, "name"_a); + m.def("getUpperBound", getUpperBound, "behaviour"_a, "name"_a); + m.def("hasPhysicalBounds", hasPhysicalBounds, "behaviour"_a, "name"_a); + m.def("hasLowerPhysicalBound", hasLowerPhysicalBound, "behaviour"_a, + "name"_a); + m.def("hasUpperPhysicalBound", hasUpperPhysicalBound, "behaviour"_a, + "name"_a); + m.def("getLowerPhysicalBound", getLowerPhysicalBound, "behaviour"_a, + "name"_a); + m.def("getUpperPhysicalBound", getUpperPhysicalBound, "behaviour"_a, + "name"_a); } // end of declareBehaviour diff --git a/bindings/python/src/FiniteStrainSupport.cxx b/bindings/python/src/FiniteStrainSupport.cxx index 84c2762d4..a5f5b6308 100644 --- a/bindings/python/src/FiniteStrainSupport.cxx +++ b/bindings/python/src/FiniteStrainSupport.cxx @@ -38,6 +38,7 @@ static void py_convertFiniteStrainTangentOperator( } // end of py_py_convertFiniteStrainTangentOperator void declareFiniteStrainSupport(pybind11::module_& m) { + using namespace pybind11::literals; using namespace mgis::behaviour; pybind11::enum_(m, "FiniteStrainStress") .value("PK1", FiniteStrainStress::PK1) @@ -45,7 +46,9 @@ void declareFiniteStrainSupport(pybind11::module_& m) { pybind11::enum_(m, "FiniteStrainTangentOperator") .value("DPK1_DF", FiniteStrainTangentOperator::DPK1_DF); - m.def("convertFiniteStrainStress", py_convertFiniteStrainStress); + m.def("convertFiniteStrainStress", py_convertFiniteStrainStress, "stress"_a, + "manager"_a, "type"_a); m.def("convertFiniteStrainTangentOperator", - py_convertFiniteStrainTangentOperator); + py_convertFiniteStrainTangentOperator, "tangent_operator"_a, + "manager"_a, "type"_a); } // end of declareFiniteStrainSupport diff --git a/bindings/python/src/Integrate.cxx b/bindings/python/src/Integrate.cxx index 9908ef859..067356486 100644 --- a/bindings/python/src/Integrate.cxx +++ b/bindings/python/src/Integrate.cxx @@ -153,6 +153,7 @@ MaterialDataManager_executePostProcessing3( } void declareIntegrate(pybind11::module_& m) { + using namespace pybind11::literals; using namespace mgis::behaviour; pybind11::enum_(m, "IntegrationType") @@ -226,21 +227,28 @@ void declareIntegrate(pybind11::module_& m) { &MultiThreadedBehaviourIntegrationResult::results); m.def("executeInitializeFunction", - BehaviourDataView_executeInitializeFunction); + BehaviourDataView_executeInitializeFunction, "view"_a, "behaviour"_a, + "name"_a); m.def("executeInitializeFunction", - BehaviourDataView_executeInitializeFunction2); + BehaviourDataView_executeInitializeFunction2, "view"_a, "behaviour"_a, + "name"_a, "inputs"_a); m.def("executeInitializeFunction", - MaterialDataManager_executeInitializeFunction); + MaterialDataManager_executeInitializeFunction, "manager"_a, "name"_a); m.def("executeInitializeFunction", - MaterialDataManager_executeInitializeFunction1); + MaterialDataManager_executeInitializeFunction1, "manager"_a, "name"_a, + "begin"_a, "end"_a); m.def("executeInitializeFunction", - MaterialDataManager_executeInitializeFunction2); + MaterialDataManager_executeInitializeFunction2, "thread_pool"_a, + "manager"_a, "name"_a); m.def("executeInitializeFunction", - MaterialDataManager_executeInitializeFunction3); + MaterialDataManager_executeInitializeFunction3, "manager"_a, "name"_a, + "inputs"_a); m.def("executeInitializeFunction", - MaterialDataManager_executeInitializeFunction4); + MaterialDataManager_executeInitializeFunction4, "manager"_a, "name"_a, + "inputs"_a, "begin"_a, "end"_a); m.def("executeInitializeFunction", - MaterialDataManager_executeInitializeFunction5); + MaterialDataManager_executeInitializeFunction5, "thread_pool"_a, + "manager"_a, "name"_a, "inputs"_a); int (*integrate_ptr1)(BehaviourDataView&, const Behaviour&) = integrate; int (*integrate_ptr2)(MaterialDataManager&, const IntegrationType, @@ -271,21 +279,34 @@ void declareIntegrate(pybind11::module_& m) { mgis::ThreadPool&, MaterialDataManager&, const BehaviourIntegrationOptions&, const mgis::real) = integrate_debug; - m.def("integrate", &integrateBehaviourData1); - m.def("integrate", integrate_ptr1); - m.def("integrate", integrate_ptr2); - m.def("integrate", integrate_ptr3); - m.def("integrate", integrate_ptr4); - m.def("integrate", integrate_ptr5); - m.def("integrate_debug", &integrateDebugBehaviourData1); - m.def("integrate_debug", integrate_debug_ptr1); - m.def("integrate_debug", integrate_debug_ptr2); - m.def("integrate_debug", integrate_debug_ptr3); - m.def("integrate_debug", integrate_debug_ptr4); - m.def("integrate_debug", integrate_debug_ptr5); - m.def("executePostProcessing", BehaviourDataView_executePostProcessing); - m.def("executePostProcessing", MaterialDataManager_executePostProcessing); - m.def("executePostProcessing", MaterialDataManager_executePostProcessing2); - m.def("executePostProcessing", MaterialDataManager_executePostProcessing3); + m.def("integrate", &integrateBehaviourData1, "data"_a, "behaviour"_a); + m.def("integrate", integrate_ptr1, "view"_a, "behaviour"_a); + m.def("integrate", integrate_ptr2, "manager"_a, "integration_type"_a, "dt"_a, + "begin"_a, "end"_a); + m.def("integrate", integrate_ptr3, "thread_pool"_a, "manager"_a, + "integration_type"_a, "dt"_a); + m.def("integrate", integrate_ptr4, "manager"_a, "options"_a, "dt"_a, + "begin"_a, "end"_a); + m.def("integrate", integrate_ptr5, "thread_pool"_a, "manager"_a, "options"_a, + "dt"_a); + m.def("integrate_debug", &integrateDebugBehaviourData1, "data"_a, + "behaviour"_a); + m.def("integrate_debug", integrate_debug_ptr1, "view"_a, "behaviour"_a); + m.def("integrate_debug", integrate_debug_ptr2, "manager"_a, + "integration_type"_a, "dt"_a, "begin"_a, "end"_a); + m.def("integrate_debug", integrate_debug_ptr3, "thread_pool"_a, "manager"_a, + "integration_type"_a, "dt"_a); + m.def("integrate_debug", integrate_debug_ptr4, "manager"_a, "options"_a, + "dt"_a, "begin"_a, "end"_a); + m.def("integrate_debug", integrate_debug_ptr5, "thread_pool"_a, "manager"_a, + "options"_a, "dt"_a); + m.def("executePostProcessing", BehaviourDataView_executePostProcessing, + "outputs"_a, "view"_a, "behaviour"_a, "name"_a); + m.def("executePostProcessing", MaterialDataManager_executePostProcessing, + "outputs"_a, "manager"_a, "name"_a); + m.def("executePostProcessing", MaterialDataManager_executePostProcessing2, + "outputs"_a, "manager"_a, "name"_a, "begin"_a, "end"_a); + m.def("executePostProcessing", MaterialDataManager_executePostProcessing3, + "outputs"_a, "thread_pool"_a, "manager"_a, "name"_a); } // end of declareIntegrate diff --git a/bindings/python/src/MaterialDataManager.cxx b/bindings/python/src/MaterialDataManager.cxx index cd45b2885..088283ec8 100644 --- a/bindings/python/src/MaterialDataManager.cxx +++ b/bindings/python/src/MaterialDataManager.cxx @@ -62,6 +62,7 @@ static pybind11::object MaterialDataManager_getSpeedOfSound( } // end of MaterialDataManager_getSpeedOfSound void declareMaterialDataManager(pybind11::module_& m) { + using namespace pybind11::literals; using mgis::size_type; using mgis::behaviour::Behaviour; using mgis::behaviour::MaterialDataManager; @@ -82,10 +83,11 @@ void declareMaterialDataManager(pybind11::module_& m) { "(the arrays bound through it must be kept alive by the " "caller)") .def("bindTangentOperator", - &MaterialDataManagerInitializer_bindTangentOperator, + &MaterialDataManagerInitializer_bindTangentOperator, "K"_a, "use the given array to store the tangent operator blocks", pybind11::keep_alive<1, 2>()) .def("bindSpeedOfSound", &MaterialDataManagerInitializer_bindSpeedOfSound, + "speed_of_sound"_a, "use the given array to store the speed of sounds", pybind11::keep_alive<1, 2>()); // exporting the MaterialDataManager class @@ -96,13 +98,14 @@ void declareMaterialDataManager(pybind11::module_& m) { const MaterialDataManagerInitializer&>(), pybind11::keep_alive<1, 2>(), pybind11::keep_alive<1, 4>()) .def("setThreadSafe", &MaterialDataManager::setThreadSafe, + "thread_safe"_a, "specify if various operations performed by the MaterialDataManager " "(memory allocations) shall be protected by a mutex") .def("allocateArrayOfTangentOperatorBlocks", &MaterialDataManager::allocateArrayOfTangentOperatorBlocks, "allocate the tangent operator blocks") .def("useExternalArrayOfTangentOperatorBlocks", - &MaterialDataManager_useExternalArrayOfTangentOperatorBlocks, + &MaterialDataManager_useExternalArrayOfTangentOperatorBlocks, "K"_a, "use and externally defined array to store the tangent operator " "blocks", pybind11::keep_alive<1, 2>()) @@ -114,6 +117,7 @@ void declareMaterialDataManager(pybind11::module_& m) { "allocate the array of speed of sounds") .def("useExternalArrayOfSpeedOfSounds", &MaterialDataManager_useExternalArrayOfSpeedOfSounds, + "speed_of_sound"_a, "use and externally defined array to store the spped of sounds", pybind11::keep_alive<1, 2>()) .def("releaseArrayOfSpeedOfSounds", @@ -132,7 +136,7 @@ void declareMaterialDataManager(pybind11::module_& m) { .def("update", ptr_update) .def("revert", ptr_revert); // free functions - m.def("update", ptr_update); - m.def("revert", ptr_revert); + m.def("update", ptr_update, "manager"_a); + m.def("revert", ptr_revert, "manager"_a); } // end of declareMaterialDataManager diff --git a/bindings/python/src/MaterialStateManager.cxx b/bindings/python/src/MaterialStateManager.cxx index b0d309102..09b832464 100644 --- a/bindings/python/src/MaterialStateManager.cxx +++ b/bindings/python/src/MaterialStateManager.cxx @@ -276,6 +276,7 @@ static void MaterialStateManager_setExternalStateVariable4( void declareMaterialStateManager(pybind11::module_&); void declareMaterialStateManager(pybind11::module_& m) { + using namespace pybind11::literals; using mgis::size_type; using mgis::behaviour::Behaviour; using mgis::behaviour::MaterialStateManager; @@ -310,22 +311,27 @@ void declareMaterialStateManager(pybind11::module_& m) { m, "MaterialStateManagerInitializer") .def(pybind11::init<>()) .def("bindGradients", &MaterialStateManagerInitializer_bindGradients, + "gradients"_a, "use the given array to store the gradients", pybind11::keep_alive<1, 2>()) .def("bindThermodynamicForces", &MaterialStateManagerInitializer_bindThermodynamicForces, + "thermodynamic_forces"_a, "use the given array to store the thermodynamic forces", pybind11::keep_alive<1, 2>()) .def("bindInternalStateVariables", &MaterialStateManagerInitializer_bindInternalStateVariables, + "internal_state_variables"_a, "use the given array to store the internal state variables", pybind11::keep_alive<1, 2>()) .def("bindStoredEnergies", &MaterialStateManagerInitializer_bindStoredEnergies, + "stored_energies"_a, "use the given array to store the stored energies", pybind11::keep_alive<1, 2>()) .def("bindDissipatedEnergies", &MaterialStateManagerInitializer_bindDissipatedEnergies, + "dissipated_energies"_a, "use the given array to store the dissipated energies", pybind11::keep_alive<1, 2>()); // wrapping the MaterialStateManager class @@ -351,46 +357,68 @@ void declareMaterialStateManager(pybind11::module_& m) { &MaterialStateManager_getDissipatedEnergies) .def_property_readonly("internal_state_variables", &MaterialStateManager_getInternalStateVariables) - .def("setMaterialProperty", &MaterialStateManager_setMaterialProperty) - .def("setMaterialProperty", &MaterialStateManager_setMaterialProperty2) + .def("setMaterialProperty", &MaterialStateManager_setMaterialProperty, + "name"_a, "value"_a) + .def("setMaterialProperty", &MaterialStateManager_setMaterialProperty2, + "name"_a, "value"_a, "update_policy"_a) .def("setMaterialProperty", &MaterialStateManager_setMaterialProperty3, + "name"_a, "values"_a, "storage_mode"_a, storage_mode_doc) .def("setMaterialProperty", &MaterialStateManager_setMaterialProperty4, + "name"_a, "values"_a, "storage_mode"_a, "update_policy"_a, storage_mode_doc) - .def("setMassDensity", &MaterialStateManager_setMassDensity) - .def("setMassDensity", &MaterialStateManager_setMassDensity2) - .def("setMassDensity", &MaterialStateManager_setMassDensity3, + .def("setMassDensity", &MaterialStateManager_setMassDensity, "value"_a) + .def("setMassDensity", &MaterialStateManager_setMassDensity2, "value"_a, + "update_policy"_a) + .def("setMassDensity", &MaterialStateManager_setMassDensity3, "values"_a, + "storage_mode"_a, storage_mode_doc) - .def("setMassDensity", &MaterialStateManager_setMassDensity4, + .def("setMassDensity", &MaterialStateManager_setMassDensity4, "values"_a, + "storage_mode"_a, "update_policy"_a, storage_mode_doc) .def("setExternalStateVariable", - &MaterialStateManager_setExternalStateVariable) + &MaterialStateManager_setExternalStateVariable, "name"_a, "value"_a) .def("setExternalStateVariable", - &MaterialStateManager_setExternalStateVariable2) + &MaterialStateManager_setExternalStateVariable2, "name"_a, "value"_a, + "update_policy"_a) .def("setExternalStateVariable", - &MaterialStateManager_setExternalStateVariable3, storage_mode_doc) + &MaterialStateManager_setExternalStateVariable3, "name"_a, + "values"_a, "storage_mode"_a, storage_mode_doc) .def("setExternalStateVariable", - &MaterialStateManager_setExternalStateVariable4, storage_mode_doc); + &MaterialStateManager_setExternalStateVariable4, "name"_a, + "values"_a, "storage_mode"_a, "update_policy"_a, storage_mode_doc); // free functions - m.def("setMaterialProperty", &MaterialStateManager_setMaterialProperty); - m.def("setMaterialProperty", &MaterialStateManager_setMaterialProperty2); + m.def("setMaterialProperty", &MaterialStateManager_setMaterialProperty, + "state"_a, "name"_a, "value"_a); + m.def("setMaterialProperty", &MaterialStateManager_setMaterialProperty2, + "state"_a, "name"_a, "value"_a, "update_policy"_a); m.def("setMaterialProperty", &MaterialStateManager_setMaterialProperty3, + "state"_a, "name"_a, "values"_a, "storage_mode"_a, storage_mode_doc); m.def("setMaterialProperty", &MaterialStateManager_setMaterialProperty4, + "state"_a, "name"_a, "values"_a, "storage_mode"_a, "update_policy"_a, storage_mode_doc); - m.def("setMassDensity", &MaterialStateManager_setMassDensity); - m.def("setMassDensity", &MaterialStateManager_setMassDensity2); - m.def("setMassDensity", &MaterialStateManager_setMassDensity3, + m.def("setMassDensity", &MaterialStateManager_setMassDensity, "state"_a, + "value"_a); + m.def("setMassDensity", &MaterialStateManager_setMassDensity2, "state"_a, + "value"_a, "update_policy"_a); + m.def("setMassDensity", &MaterialStateManager_setMassDensity3, "state"_a, + "values"_a, "storage_mode"_a, storage_mode_doc); - m.def("setMassDensity", &MaterialStateManager_setMassDensity4, + m.def("setMassDensity", &MaterialStateManager_setMassDensity4, "state"_a, + "values"_a, "storage_mode"_a, "update_policy"_a, storage_mode_doc); m.def("setExternalStateVariable", - &MaterialStateManager_setExternalStateVariable); + &MaterialStateManager_setExternalStateVariable, "state"_a, "name"_a, + "value"_a); m.def("setExternalStateVariable", - &MaterialStateManager_setExternalStateVariable2); + &MaterialStateManager_setExternalStateVariable2, "state"_a, "name"_a, + "value"_a, "update_policy"_a); m.def("setExternalStateVariable", - &MaterialStateManager_setExternalStateVariable3, storage_mode_doc); + &MaterialStateManager_setExternalStateVariable3, "state"_a, "name"_a, + "values"_a, "storage_mode"_a, storage_mode_doc); m.def("setExternalStateVariable", - &MaterialStateManager_setExternalStateVariable4, storage_mode_doc); + &MaterialStateManager_setExternalStateVariable4, "state"_a, "name"_a, + "values"_a, "storage_mode"_a, "update_policy"_a, storage_mode_doc); } // end of declareMaterialStateManager diff --git a/bindings/python/src/State.cxx b/bindings/python/src/State.cxx index 2b5e29e6d..4cb9e9c6b 100644 --- a/bindings/python/src/State.cxx +++ b/bindings/python/src/State.cxx @@ -102,6 +102,7 @@ static void State_setExternalStateVariable2(mgis::behaviour::State& s, } // end of State_setExternalStateVariable2 void declareState(pybind11::module_& m) { + using namespace pybind11::literals; using mgis::behaviour::Behaviour; using mgis::behaviour::State; pybind11::class_(m, "State") @@ -118,13 +119,17 @@ void declareState(pybind11::module_& m) { .def_property_readonly("external_state_variables", &State_getExternalStateVariables); // - m.def("setMaterialProperty", State_setMaterialProperty, + m.def("setMaterialProperty", State_setMaterialProperty, "state"_a, "name"_a, + "value"_a, "set the value of a material property by name"); - m.def("setMaterialProperty", State_setMaterialProperty2, + m.def("setMaterialProperty", State_setMaterialProperty2, "state"_a, + "offset"_a, "value"_a, "set the value of a material property by offset"); - m.def("setExternalStateVariable", State_setExternalStateVariable, + m.def("setExternalStateVariable", State_setExternalStateVariable, "state"_a, + "name"_a, "value"_a, "set the value of an external state variable by name"); - m.def("setExternalStateVariable", State_setExternalStateVariable2, + m.def("setExternalStateVariable", State_setExternalStateVariable2, "state"_a, + "offset"_a, "value"_a, "set the value of an external state variable by offset"); } // end of declareState diff --git a/bindings/python/src/Variable.cxx b/bindings/python/src/Variable.cxx index 73276cb7a..afefedf81 100644 --- a/bindings/python/src/Variable.cxx +++ b/bindings/python/src/Variable.cxx @@ -83,6 +83,7 @@ static mgis::size_type getVariableSizeByString( void declareVariable(pybind11::module_&); void declareVariable(pybind11::module_& m) { + using namespace pybind11::literals; using mgis::behaviour::Variable; // wrapping the Variable::Type enum pybind11::enum_(m, "VariableType") @@ -129,19 +130,23 @@ void declareVariable(pybind11::module_& m) { "`Tensor`, `Tensor1D`, `Tensor2D`, `Tensor3D`, `HigherOrderTensor` " "and `Array`"); // free functions - m.def("getVariable", getVariableByString, + m.def("getVariable", getVariableByString, "variables"_a, "name"_a, pybind11::return_value_policy::copy); m.def("getVariableSize", pybind11::overload_cast( - &mgis::behaviour::getVariableSize)); - m.def("getVariableSize", getVariableSizeByString); + &mgis::behaviour::getVariableSize), + "variable"_a, "hypothesis"_a); + m.def("getVariableSize", getVariableSizeByString, "variables"_a, "name"_a, + "hypothesis"_a); m.def("getArraySize", pybind11::overload_cast&, const mgis::behaviour::Hypothesis>( - &mgis::behaviour::getArraySize)); - m.def("getVariableOffset", getVariableOffsetByString); + &mgis::behaviour::getArraySize), + "variables"_a, "hypothesis"_a); + m.def("getVariableOffset", getVariableOffsetByString, "variables"_a, "name"_a, + "hypothesis"_a); m.def("getVariableTypeSymbolicRepresentation", - &mgis::behaviour::getVariableTypeSymbolicRepresentation); + &mgis::behaviour::getVariableTypeSymbolicRepresentation, "type"_a); } // end of declareVariable From 15f5f855419613d44834dba450b753385324c6af Mon Sep 17 00:00:00 2001 From: t Date: Fri, 6 Nov 2026 15:18:31 +0100 Subject: [PATCH 10/14] python: names of the arguments of the material_property and model modules --- bindings/python/src/MaterialProperty.cxx | 3 ++- bindings/python/src/Model.cxx | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/bindings/python/src/MaterialProperty.cxx b/bindings/python/src/MaterialProperty.cxx index 0bec92275..eafc3e1c3 100644 --- a/bindings/python/src/MaterialProperty.cxx +++ b/bindings/python/src/MaterialProperty.cxx @@ -19,6 +19,7 @@ void declareMaterialProperty(pybind11::module_&); void declareMaterialProperty(pybind11::module_& m) { + using namespace pybind11::literals; using mgis::material_property::MaterialProperty; // wrapping the MaterialProperty class pybind11::class_(m, "MaterialProperty") @@ -38,6 +39,6 @@ void declareMaterialProperty(pybind11::module_& m) { .def_readonly("inputs", &MaterialProperty::inputs, "inputs of the material property"); // wrapping free functions - m.def("load", mgis::material_property::load); + m.def("load", mgis::material_property::load, "library"_a, "name"_a); } // end of declareMaterialProperty diff --git a/bindings/python/src/Model.cxx b/bindings/python/src/Model.cxx index d7d6707fb..1f8d2d46a 100644 --- a/bindings/python/src/Model.cxx +++ b/bindings/python/src/Model.cxx @@ -32,7 +32,8 @@ void declareModel(pybind11::module_& m) { // wrapping free functions m.def("load", pybind11::overload_cast( - mgis::model::load)); + mgis::model::load), + "library"_a, "model"_a, "hypothesis"_a); m.def("loadFromDatabase", Model_loadFromDatabase, "name"_a, "hypothesis"_a, "material"_a = std::optional{}); From ae2a17328b5f8d90d01e72eff1a84e7569bc16c8 Mon Sep 17 00:00:00 2001 From: t Date: Fri, 6 Nov 2026 15:19:45 +0100 Subject: [PATCH 11/14] pip: the test of the wheels checks that the stubs are valid python --- bindings/python/pip/test_wheel.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/bindings/python/pip/test_wheel.py b/bindings/python/pip/test_wheel.py index c1470029c..aff2fadc8 100644 --- a/bindings/python/pip/test_wheel.py +++ b/bindings/python/pip/test_wheel.py @@ -8,6 +8,7 @@ Windows, building behaviours requires Visual Studio and is not tested. """ +import ast import os import re import shutil @@ -41,11 +42,15 @@ sys.exit("the mgis wheel must not contain the library " + name) # the stubs of the python modules are installed next to them, as well as -# the py.typed marker +# the py.typed marker. Type checkers stop on a stub which is not valid python for stub in ("_mgis.pyi", "behaviour.pyi", "material_property.pyi", "model.pyi", "function.pyi", "py.typed"): - if not os.path.isfile(os.path.join(mgishome, stub)): + path = os.path.join(mgishome, stub) + if not os.path.isfile(path): sys.exit("missing " + stub) + if stub.endswith(".pyi"): + with open(path, encoding="utf-8") as f: + ast.parse(f.read(), path) if os.name == "nt": sys.exit(0) From 5527a13d20c2e19a08ced0f96e07ca8a7d6f2ad7 Mon Sep 17 00:00:00 2001 From: t Date: Fri, 6 Nov 2026 15:19:45 +0100 Subject: [PATCH 12/14] pip: the libraries of the tfel-mfront wheel are not versioned --- bindings/python/pip/setup.py | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/bindings/python/pip/setup.py b/bindings/python/pip/setup.py index 737bc630d..630e37f19 100644 --- a/bindings/python/pip/setup.py +++ b/bindings/python/pip/setup.py @@ -68,14 +68,13 @@ _TFEL_MFRONT_VERSION = "@TFEL_MFRONT_VERSION@" -# The shared libraries of TFEL have a versioned soname, such as -# libTFELMath.so.5.2.0-dev, so importing a module of this wheel fails with -# a obscure 'libTFELXXX.so.5.2.0-dev: cannot open shared object file' error -# when the installed tfel-mfront does not have the version this wheel was -# built against. Check the version of the installed tfel-mfront package -# instead, which also covers the cases where the libraries are not the ones -# of a wheel (TFELHOME set externally), and which is what cmake verified at -# configuration time (require-tfel and MGIS_REQUIRED_TFEL_VERSION). +# The libraries of the tfel-mfront wheel are not versioned, so the dynamic +# loader would silently use another version of TFEL than the one this wheel +# was built against, whose ABI may differ. The version of the installed +# tfel-mfront package is thus checked, which also covers the cases where the +# libraries are not the ones of a wheel (TFELHOME set externally), and which +# is what cmake verified at configuration time (require-tfel and +# MGIS_REQUIRED_TFEL_VERSION). def _check_tfel_mfront(): from importlib import metadata From a93fd6647418b0e9564bd937e566f9c712309c8d Mon Sep 17 00:00:00 2001 From: t Date: Fri, 6 Nov 2026 15:19:45 +0100 Subject: [PATCH 13/14] remove the design note of the pip package It was a proposal, written before the implementation. It remains available in the history of this branch (0fd9d87). --- pip-package.md | 519 ------------------------------------------------- 1 file changed, 519 deletions(-) delete mode 100644 pip-package.md diff --git a/pip-package.md b/pip-package.md deleted file mode 100644 index 73e116359..000000000 --- a/pip-package.md +++ /dev/null @@ -1,519 +0,0 @@ -# Proposal: a `pip` package for MGIS (issue #254) - -Status: proposal, to be discussed on the issue before implementation. - -Scope of the first version: **python bindings only** (no C / Fortran / FEniCS / -Julia bindings in the wheel), **portable build** -(`-Denable-portable-build=ON`), TFEL support **fully enabled** -(`MGIS_HAVE_TFEL`, `MGIS/Function` + precompiled operations, MFront -database, TFEL python bindings), **stubs generated with -`pybind11-stubgen`** as in TFEL (PR thelfer/tfel#1083). - -The wheels are built by a GitHub Actions workflow modeled on TFEL's -`.github/workflows/python-pip.yml`, with `pypa/cibuildwheel`. - ---- - -## 1. Reference: what TFEL already does - -- `bindings/python/pip/{pyproject.toml,setup.py,test_wheel.py}`: `setup.py` - configures, builds and installs TFEL with cmake, then lays the - installation out as a python package. The `tfel` module *is* TFELHOME: - `bin`, `lib`, `include` and `share` are placed inside it, and a short - preamble inserted into the `__init__.py` scripts sets the - `TFELHOME_` environment variable, which TFEL's - `GetInstallPath.cxx` honours with priority over `TFELHOME`. -- `set_relative_runtime_paths()` rewrites the runtime path of every binary - of the wheel to be relative to `tfel/lib` (`patchelf --force-rpath`, - hence `DT_RPATH`, on purpose: it is searched before `LD_LIBRARY_PATH`; - `install_name_tool` + `codesign --force --sign -` on macOS; nothing on - Windows, where `__init__.py` calls `os.add_dll_directory`). -- Windows wheels: `repair-wheel-command = ""`, since delvewheel would copy - the TFEL DLLs under other names, so a behaviour loaded in python would - load a second copy of them. -- `.github/workflows/python-pip.yml`: cibuildwheel over - ubuntu/macos/windows x cp39…cp315 (cp312 only on pull requests), ccache - (one cache per OS, saved by the cp312 job; static musl ccache inside the - manylinux container, `CCACHE_DIR=/host/ccache`), publish to - PyPI and to the GitHub release on the `TFEL-x.y.z` tags. - -### Lessons of the review of TFEL PR #1083 (pybind11-stubgen) - -The same exercise is done for MGIS, so MGIS starts from the *reviewed* -design, not from the first proposal of PR #1083: - -1. `pybind11-stubgen` is **looked for and run with `${Python_EXECUTABLE}`** - (`${Python_EXECUTABLE} -c "import pybind11_stubgen"`, then - `${Python_EXECUTABLE} -m pybind11_stubgen `), never searched in - the `PATH`: the stubgen tool must import the modules, hence run with the - interpreter they are built for. If it is not available for this - interpreter, the stubs are simply not generated (the stubs are - optional, they shall never break a build). -2. **Multi-configuration generators** (Visual Studio) append the - configuration name to the output directory of the modules - (`mgis/Release/_mgis.pyd`), whereas `__init__.py` of the package is in - `mgis/`: importing the package from the build tree fails, which breaks - the stub generation on Windows. Fix (thelfer/tfel@e0e5a81): hold the - output directories in a generator expression, e.g. - `"$<1:${dir}>"`, so that no subdirectory is appended. Accepted - trade-off: with such a generator, the modules of the configurations - built in the same build directory overwrite each other, which is - already the case for the python tests (disabled with - multi-configuration generators). -3. `os.add_dll_directory` shall only be called on **existing** directories - (thelfer/tfel@969e4ed): the `__init__.py` scripts run when the modules - are imported from the build tree, where the `bin` directory does not - exist. (MGIS: `__init__.py` and `__init__-have-tfel.py` already guard - with `os.path.isdir`, nothing to do.) -4. On Windows, importing the modules from the build tree needs the - directories of the DLLs of the build tree (python ignores `PATH` since - 3.8): a **`sitecustomize.py`**, generated by cmake and placed in a - directory added to the `PYTHONPATH` used to run pybind11-stubgen, calls - `os.add_dll_directory` on those directories, determined from a global - property listing the libraries created by `mgis_library` (TFEL uses the - `TFEL_LIBRARIES` property, which required adding one - `set_property(GLOBAL APPEND …)` to `tfel_library_internal`). -5. The stubs are generated by a `python-stubs` target, built with the - project, and installed **next to the modules** they describe. -6. `pybind11-stubgen` is pinned to `>=3.0` in the pip build requires (the - versions below 3 are not tested). -7. `test_wheel.py` checks that the stubs are installed. -8. `py.typed`: agreed in the review (PEP 561: type checkers ignore the - stubs of an installed package without this marker), to be installed as - an empty file in each python package — not committed in TFEL yet; - MGIS shall install it too so that both packages are consistent. - ---- - -## 2. The hard part: consistency between the MGIS and TFEL wheels - -MGIS links `tfel::TFELMath` and `tfel::TFELMFrontDatabase` **PUBLICLY**, and -`MGIS_HAVE_TFEL` is a PUBLIC compile definition: TFEL is part of the ABI -MGIS exposes to its own consumers (and the python bindings import -`mfront.database`). A MGIS wheel must therefore be paired with one, and -only one, TFEL wheel. - -### 2.1 Candidate designs - -- **A. Vendor TFEL** (build TFEL from sources inside the MGIS wheel): - rebuilds all of TFEL for every python x OS cell, and duplicates the - content of `tfel-mfront` → two wheels owning the `tfel` python package, - one silently overwriting the other. **Rejected.** -- **B. Depend on the published `tfel-mfront` wheel as a build *and* run - dependency, pinned to the exact same version.** **Chosen.** -- **C. Build against TFEL workflow artifacts**: same pin problem as B and - no longer needed once `tfel-mfront` is on PyPI. Kept only as an escape - hatch (`CIBW_BEFORE_BUILD` installing a wheel from a URL) while - `tfel-mfront` is not published, which is the case today (pypi.org - answers 404 for `tfel-mfront`). **Rejected as the primary mechanism.** - -### 2.2 Design B: five complementary layers - -1. **One source of truth for the TFEL pin**: `TFEL_DEPENDENCY = - "tfel-mfront==X.Y[.Z]"` is a constant of `setup.py`; the pin is written - twice in `pyproject.toml` (`[build-system].requires` and - `[project].dependencies`) because `pyproject.toml` cannot compute it, - and `setup.py` raises if the two literal pins of `pyproject.toml` do not - match the constant. Bumping the pin is one edit + its copy. -2. **Build time**: `[build-system] requires = [..., "tfel-mfront==…"]` puts - a complete TFEL installation in pip's isolated build environment. - `setup.py` locates it with - `importlib.util.find_spec("tfel").submodule_search_locations[0]` - (no import, no library load) and configures MGIS with - `-DTFEL_DIR=/share/tfel/cmake` (+ `TFELHOME` in the environment), - `-Drequire-tfel=ON` and `-DMGIS_REQUIRED_TFEL_VERSION=`. The TFEL - wheel layout (`tfel/{bin,lib,include,share/tfel/cmake}`) is exactly what - MGIS's `FindTFEL.cmake` consumes. -3. **Configure-time assertions** (cmake changes, §4.2): the configuration - fails if TFEL is not found, if `MGIS_HAVE_MFRONT_SUPPORT` is off, if - `TFEL_PYTHON_BINDINGS` is off (the wheel needs `mfront.database`), or if - `TFEL_VERSION` differs from `MGIS_REQUIRED_TFEL_VERSION`. A wheel can - never be produced against the wrong TFEL. -4. **Run time**: `[project] dependencies = ["tfel-mfront==…"]` makes pip - install exactly the TFEL wheel MGIS was built against, and the preamble - inserted in `mgis/__init__.py` (pip variant, §4.3) checks at import - `importlib.metadata.version("tfel-mfront")` against the version baked in - at build time, and raises a clear `RuntimeError` on mismatch. This - matters because the TFEL wheel has **unversioned libraries** - (`-Dunversioned-libraries=ON`): `DT_NEEDED = libTFELMath.so` with no - soname version, so the dynamic loader cannot tell two TFEL versions - apart and would fail with an obscure `ImportError` much later. -5. **End-to-end proof in the job**: `test_wheel.py` (§5) compiles a - behaviour with the `mfront` of the TFEL wheel, loads it with - `mgis.behaviour.Behaviour` and integrates it, checks the TFEL versions - agree and the stubs are installed. A wrong toolchain/ABI/glibc - combination fails before publishing. - -### 2.3 Toolchain consistency and determinism - -The MGIS wheel links the TFEL libraries, so it must be built with the same -compiler and target as `tfel-mfront`: - -- Linux: same cibuildwheel manylinux image (`skip *-musllinux_*`, - `archs = ["x86_64"]`). The image shall be pinned explicitly - (`CIBW_MANYLINUX_X86_64_IMAGE`) in **both** projects so they cannot drift. -- macOS: `MACOSX_DEPLOYMENT_TARGET=11.0`, `archs = ["arm64"]` (as TFEL). -- Windows: same runner image (hence same MSVC), `archs = ["AMD64"]`. - -Release order: the TFEL wheels must be on PyPI first; add -`workflow_dispatch` to the MGIS workflow and document the order. - -Determinism — silent variation is a consistency bug too. `setup.py` shall -set **all** the options explicitly, in particular: - -``` --DCMAKE_BUILD_TYPE=Release -Denable-python-bindings=ON --Denable-portable-build=ON -Denable-testing=OFF --Denable-website=OFF -Denable-doxygen-doc=OFF --Denable-c-bindings=OFF -Denable-fortran-bindings=OFF --Denable-fenics-bindings=OFF -Denable-julia-bindings=OFF --Denable-cuda-algorithms=OFF -Denable-openmp=OFF --Denable-exceptions=OFF -Ddisable-tfel=OFF --Denable-hdf5-support=OFF -Denable-hdf5-automatic-support=OFF --Drequire-tfel=ON -Denable-pybind11-stubgen=ON --DMGIS_PYTHON_MODULES_INSTALL_DIRECTORY=site-packages --DPython_EXECUTABLE= -Dpybind11_DIR= -``` - -`enable-hdf5-automatic-support=OFF` is essential: otherwise the content of -the wheel silently depends on whether HDF5 happens to be present in the -container. `pybind11` is copied to a fixed path (as in TFEL) so that the -changing paths of the isolated build environments do not defeat ccache. -OpenMP: OFF for v1, as in TFEL's pip build (it would tie the wheel to the -toolchain's `libgomp`); documented as a limitation. - ---- - -## 3. Wheel layout - -The `mgis` module plays the role of MGISHOME, exactly as the `tfel` module -is TFELHOME in `tfel-mfront`: - -``` -mgis/ # python package + MGISHOME - __init__.py # pip variant (see §4.3) - _mgis.cpython-3XX-*.so/.pyd - behaviour.* material_property.* model.* function.* - *.pyi # stubs + py.typed - lib/ (Windows: bin/) # libMFrontGenericInterface… - include/MGIS/… # MGIS headers (decision: ship them) - share/mgis/cmake/… # so that find_package(MFrontGenericInterface) - # also works from the wheel -``` - -`MGIS_APPEND_SUFFIX` is not used by the wheel (the package is `mgis`; the -PyPI name **`mgis` is available** — pypi.org answers 404 as of 2026-11-06 — -which is the natural name; alternative if disputed: -`mfront-generic-interface`). - -MGIS installs **no executables**, so no launcher module is needed: `mfront`, -`mtest` and `tfel-config` come from the `tfel-mfront` dependency's console -scripts. - -### Runtime paths (`set_relative_runtime_paths`, adapted from TFEL) - -Every ELF/Mach-O binary of the wheel gets a **relative** runtime path, -computed with `os.path.relpath` from its own directory to **both**: - -- `mgis/lib` (`mgis/bin` on Windows, irrelevant on ELF/Mach-O anyway), and -- the `lib` directory of the **sibling `tfel` wheel**, i.e. - `site-packages/mgis/lib/../..` → `site-packages/tfel/lib` - (`$ORIGIN/../../tfel/lib`, `@loader_path/../../tfel/lib`). The relative - path must be computed from the *installed* position: the root of the - wheel becomes `site-packages`, whereas the build directory of the package - is an arbitrary other directory, so the computation is done on simulated - `site-packages/mgis/...` paths. Computing it from the build tree gives a - path off by one level (which local tests may mask through - `LD_LIBRARY_PATH`). - -Linux: `patchelf --force-rpath --set-rpath` (`DT_RPATH`, searched before -`LD_LIBRARY_PATH`, as in TFEL); the rpath is a `:`-separated list of both -directories. macOS: `install_name_tool -delete_rpath/-add_rpath` + -`codesign --force --sign -`. Windows: nothing; the pip `__init__.py` -registers `mgis/bin` **and `tfel/bin`** with `os.add_dll_directory` -(importing `mgis` does not necessarily run `tfel/__init__.py`, and -MGIS's DLLs need TFEL's DLLs). - -### Avoiding re-vendoring TFEL (repair step) - -auditwheel (linux) and delocate (macOS) **vendor the libraries the wheel -needs which are not inside it** — that would copy the TFEL libraries of the -sibling wheel into the MGIS wheel under mangled names, and a behaviour -would then load two copies of TFEL (the exact failure TFEL disables -delvewheel for). The repair step must therefore *exclude* them: - -- linux: `CIBW_REPAIR_WHEEL_COMMAND = "auditwheel repair -w {dest_dir} - {wheel} --exclude …"`. Since auditwheel 6, `--exclude` is a - **glob** (`fnmatch`), not a regex: `libTFEL.*` silently matches nothing - and the TFEL libraries get vendored. The patterns used, `libTFEL*`, - `libMTest*`, `libMFM*`, `libMFrontQuery*`, `libMFrontLogStream*`, - `libMFrontProfiling*`, `libMFrontGenericParallelRuntime*`, behave the - same under both semantics and do not match MGIS's own - `libMFrontGenericInterface*` (verified: `libMFM*`, not `libmfm*`, is the - case of the actual library names). -- macOS: `delocate-wheel --require-archs {delocate_archs} -x …` - (`-x` is a regex). -- Windows: `repair-wheel-command = ""` (same reason as TFEL). - -`test_wheel.py` greps the wheel content or relies on the version-agreement -check to catch a regression here (a vendored `libTFELMath.so*` inside the -MGIS wheel makes the check pass silently: the real guard is the exclusion + -a check that the wheel holds no TFEL library, added to `test_wheel.py`). - ---- - -## 4. Changes required in MGIS - -### 4.1 Allow overriding the python modules destination - -`CMakeLists.txt` (lines 99-116) sets `MGIS_PYTHON_MODULES_INSTALL_DIRECTORY` -unconditionally; wrap the definition in `if(NOT -MGIS_PYTHON_MODULES_INSTALL_DIRECTORY)` so that the wheel can pass -`-DMGIS_PYTHON_MODULES_INSTALL_DIRECTORY=site-packages` (TFEL precedent: -`TFEL_PYTHON_SITE_PACKAGES_DIR`). - -### 4.2 Fail when TFEL is required but absent or not the expected one - -Next to `disable-tfel` (lines 224-234): - -```cmake -option(require-tfel "fail the configuration if TFEL is not found" OFF) -set(MGIS_REQUIRED_TFEL_VERSION "" CACHE STRING - "fail the configuration if the TFEL version is not this one") -``` - -With `require-tfel=ON`, `FATAL_ERROR` if `NOT TFEL_FOUND`, if -`MGIS_HAVE_MFRONT_SUPPORT` is off, if `TFEL_PYTHON_BINDINGS` is off, or if -`MGIS_REQUIRED_TFEL_VERSION` is non-empty and differs from `TFEL_VERSION`. -`setup.py` passes both; the normal build is unaffected. Add a job (or a -`check.yml` entry) exercising both outcomes. - -### 4.3 Pip variant of `mgis/__init__.py` - -The two existing variants only handle Windows DLL directories via -`MGISHOME` or a `../../../..` guess of the prefix — false in a wheel where -MGIS's libraries live inside the `mgis` module and TFEL's DLLs in the -sibling `tfel/bin`. Chosen mechanism (fewest cmake changes, TFEL -precedent): `setup.py` **post-processes the installed `__init__.py`**, -inserting after the `from __future__` statements a preamble which: - -- sets `MGISHOME` to the module directory (so that a `mfront` launched from - python finds MGIS's headers and libraries for `--interface=generic`), -- registers `mgis/bin` and `tfel/bin` with `os.add_dll_directory` on - Windows (guarded by `os.path.isdir`, cf. lesson 3), the `tfel` directory - being located with `importlib.util.find_spec("tfel")`, -- compares `importlib.metadata.version("tfel-mfront")` with the version - baked in by `setup.py` and raises a clear error on mismatch - (consistency layer 4; the `mfront.database` import of - `__init__-have-tfel.py` keeps working unchanged). - -### 4.4 pybind11-stubgen support (mirror of the reviewed TFEL PR #1083) - -- `option(enable-pybind11-stubgen "generates stubs for python extensions" - ON)` when `enable-python-bindings`, detection by `${Python_EXECUTABLE} -c - "import pybind11_stubgen"` (lesson 1). -- `cmake/modules/mgis.cmake`: `set_property(GLOBAL APPEND PROPERTY - MGIS_LIBRARIES ${name})` in `mgis_library()` (for the Windows DLL - directories of the build tree, lesson 4). -- A new `cmake/modules/mgis-python-modules.cmake` (or directly in - `bindings/python/src/CMakeLists.txt`, which currently defines - `mgis_python_module`): - - `mgis_python_module` sets `LIBRARY_OUTPUT_DIRECTORY` to - `"$<1:${MGIS_PYTHON_MODULES_BUILD_DIR}/mgis>"` (or `mgis_` when - `MGIS_APPEND_SUFFIX`), so that the modules are next to the - `__init__.py` of the package in the build tree (lesson 2 — MGIS does - not set an output directory at all today: the modules go to - `bindings/python/src/`, and the tests assemble a package by - **symlinks** in `bindings/python/tests/mgis/`; the symlink assembly can - stay as it is); - - a `python_module_stubgen(target package name)` function registering - `${target}:${module}` in a global property, called from - `mgis_python_module` for `_mgis`, `behaviour`, `material_property`, - `model`, `function` (respecting `MGIS_APPEND_SUFFIX` for the package - name); - - a `generate_python_stubs()` function, called at the end of the main - `CMakeLists.txt` (after all `add_subdirectory`), generating with - `${Python_EXECUTABLE} -m pybind11_stubgen --output-dir - ${MGIS_PYTHON_MODULES_BUILD_DIR}` a `python-stubs` custom target (ALL), - installing the `.pyi` files next to the modules in - `${MGIS_PYTHON_MODULES_INSTALL_DIRECTORY}`; - - the build-tree package directory also gets a copy of the `__init__.py` - variant selected at configure time (`file(CONFIGURE …)` / - `configure_file`), as importing `mgis` runs it; - - Windows: the generated `sitecustomize.py` (lesson 4) registers, in - addition to the build-tree DLL directories from `MGIS_LIBRARIES`, the - `bin` directory of the TFEL installation (from `TFELHOME`) so that the - TFEL DLLs needed by `_mgis` are found. -- Install an empty `py.typed` marker in the `mgis` package (PEP 561; - lesson 8 — coordinate with TFEL, which has agreed to do the same). - -### 4.5 Relocatable cmake package (verification only) - -`MFrontGenericInterfaceConfig.cmake.in` already resolves TFEL through -`TFEL_DIR` / `TFELHOME` / `$ENV{TFELHOME_}` — the variable the -TFEL wheel sets at `import tfel`. Risk to check during implementation: -`install(EXPORT … EXPORT_LINK_INTERFACE_LIBRARIES)` may record absolute -TFEL paths from TFEL's own `Targets.cmake`. `test_wheel.py` runs a tiny -`find_package(MFrontGenericInterface)` project against the wheel's -`share/mgis/cmake` to prove it. - -### 4.6 Versioned libraries - -Contrary to an earlier reading of `cmake/modules/mgis.cmake`, the MGIS -libraries are **not** versioned: the `VERSION "${PROJECT_VERSION}"` there -only feeds `write_basic_package_version_file` (the cmake package version), -not the libraries. The installation holds a single unversioned -`libMFrontGenericInterface.so`, without soname version nor development -symlink, so the wheel layout has nothing to dereference and -`materialize_symlinks` in `setup.py` is only a safety net. - -The TFEL libraries, on the other hand, have a *versioned soname* -(`libTFELMath.so.5.2.0-dev`): a mismatched `tfel-mfront` version manifests -itself as a dynamic linker error, which the check inserted in -`mgis/__init__.py` (and the `MGIS_REQUIRED_TFEL_VERSION` check of cmake) -report earlier and more clearly. - ---- - -## 5. New files: `bindings/python/pip/` - -- `pyproject.toml`: - - `[build-system] requires = ["setuptools>=64", "cmake>=3.20", - "pybind11>=2.12", "pybind11-stubgen>=3.0", "numpy>=2.0", - "tfel-mfront==X.Y.Z", "patchelf; sys_platform == 'linux'"]`; - - `[project] name = "mgis"`, `dynamic = ["version"]` (from - `project("mfront-generic-interface" VERSION …)` of `CMakeLists.txt`, - `-dev` → `.dev0`), `requires-python = ">=3.9"`, - `dependencies = ["numpy", "tfel-mfront==X.Y.Z"]`; license CeCILL-C; - `[tool.setuptools] packages = [] py-modules = []`; - - `[tool.cibuildwheel] build-verbosity = 1`, `skip = ["*-musllinux_*"]`, - `test-command = "python {package}/test_wheel.py"`, per-OS archs as in - §2.3 and the repair commands of §3. -- `setup.py`: version pin guard + TFEL discovery (§2.2-2) + cmake - configure/build/install with the options of §2.3 + `layout_package()` - (copy `site-packages/*` at the wheel root, `bin`/`lib`/`include`/`share` - into `mgis/`) + `__init__.py` preamble insertion (§4.3) + - `set_relative_runtime_paths()` with the two rpath entries (§3) + - `BinaryDistribution` (`has_ext_modules`) + the whole thing driven from a - `build_ext` subclass (the only build command run when no python package - is declared to setuptools). -- `test_wheel.py`, run by cibuildwheel in a fresh venv containing the - built wheel (pip pulls the `tfel-mfront` dependency with it): - 1. `import mgis, mgis.behaviour, mgis.material_property, mgis.model, - mgis.function, mfront.database` (the last one through `import mgis`), - 2. assert the TFEL version check passed and `mgis.behaviour` reports the - expected `MGIS_HAVE_TFEL` features, - 3. assert no TFEL library was vendored into the wheel (§3), - 4. assert the `.pyi` stubs and `py.typed` are installed next to the - modules (lessons 7 and 8), - 5. on non-Windows: write `Elasticity.mfront`, run the wheel's `mfront - --obuild --interface=generic` (the `MGISHOME` and `TFELHOME` set by - `import mgis` and the tfel launcher are inherited), load the library - with `mgis.behaviour.Behaviour`, `mgis.behaviour.integrate` a uniaxial - strain, check `S_XX ≈ 150e6` against the analytic result — the - end-to-end consistency layer, - 6. on non-Windows: `cmake -find_package(MFrontGenericInterface)` on a - tiny project against the wheel's `share/mgis/cmake` (§4.5). - ---- - -## 6. New workflow: `.github/workflows/python-pip.yml` - -Copy of TFEL's with the following deltas: - -- triggers: push on the tags `MFrontGenericInterfaceSupport-[0-9]+.[0-9]+.*` - (the repo's release tags have both `x.y` and `x.y.z` forms — confirm the - convention for tagged wheel releases), push/PR on `master`, plus - `workflow_dispatch` (release order: TFEL first). -- matrix `os x python` exactly as TFEL (cp39…cp315, cp312 on PRs). -- ccache: reuse this repo's `.github/actions/{setup,save}-ccache` — to be - verified they expose the `key:` input and the `msvc.cmake` toolchain TFEL - versions provide; MGIS's actions were built for the spack/OCI - buildcache flows. One cache per OS (`key: wheel-`), saved by the - cp312 job; inside the manylinux container, static musl ccache via - `CIBW_BEFORE_ALL_LINUX` (HTTPS only) and `CCACHE_DIR=/host/ccache`. -- `pypa/cibuildwheel@v4.3.2`, `package-dir: bindings/python/pip`, - `output-dir: wheelhouse`, `CIBW_BUILD: ${{ matrix.python }}-*`. -- artifact `mgis-wheel-${{ os }}-${{ python }}`. -- `publish-pypi` and `publish-github-release`, both - `if: push && startsWith(github.ref, 'refs/tags/MFrontGenericInterfaceSupport-')`. - ---- - -## 7. Open questions - -1. **PyPI name**: `mgis` (available, recommended) vs - `mfront-generic-interface`. Note that a `mgis` conda/pip ecosystem name - clash, if any, is with an unrelated project only if one appears later; - reserving it early is an argument for acting now. -2. **Tag convention** the publish jobs key on (see §6). -3. **Pin strictness**: `tfel-mfront==X.Y.Z` recommended for v1 (the TFEL - wheel libraries carry a versioned soname, `libTFELMath.so.5.2.0-dev`, - so an untested TFEL would fail to load obscurely rather than silently; - the exact pin makes the failure explicit). Relax once the policy is - proven. -4. **MGIS dev version wheels**: TFEL maps `5.2-dev` → `5.2.dev0`; the same - mapping applies (`3.1.0` + `MFrontGenericInterfaceSupportDevelopmentVersion - ON` → `3.1.0.dev0`). Dev MGIS wheels must depend on a published TFEL - version, not a dev one (the pin is a PyPI requirement). -5. OpenMP OFF in the wheel (v1): accepted? (perf-sensitive users can build - from sources.) -6. Shipping `include/` + `share/` in the wheel: recommendation is yes - (cheap, keeps MGISHOME semantics identical to a normal install; needed - for `mfront --interface=generic` from python, which is how the wheel is - tested end-to-end). -7. `tfel-mfront` is **not on PyPI yet**: prototype against a locally built - TFEL wheel (`pip wheel` of the TFEL clone, `--find-links` + a pinned dev - version) until TFEL releases wheels; the PR job can even build the TFEL - wheel first in a preceding job (escape hatch C of §2.1). - -## 8. Implementation order - -1. CMake: §4.1 + §4.2 (+ a CI job exercising `require-tfel` success/failure). -2. CMake: §4.4 stubgen (single- and multi-config generators; a - `cmake-ninja-multi-config`-style job already exists in this repo to - smoke-test lesson 2). -3. `bindings/python/pip/{pyproject.toml,setup.py}` + `test_wheel.py`. -4. Locally: `pipx run cibuildwheel --print-build-identifiers`, then one - cell (`CIBW_BUILD=cp312-manylinux_x86_64 … --platform linux`) against a - locally built `tfel-mfront` wheel exposed with `--find-links`. -5. `.github/workflows/python-pip.yml`; iterate on the PR (cp312 only). -6. Docs: install page for the wheel + release notes (avoid TFEL's - mistake of linking a missing install-pip page). - -## 9. Findings of the local validation (against a simulated tfel-mfront) - -The wheel was built and tested locally with `--no-build-isolation` against -a directory simulating the tfel-mfront wheel layout (a `tfel` package -holding `bin`, `lib`, `include` and `share`, plus a `tfel_mfront` -dist-info), then installed in fresh virtual environments, tested with and -without an `auditwheel repair`, with `LD_LIBRARY_PATH`, `PYTHONPATH` and -`TFELHOME` unset. Everything below was verified, not reasoned: - -1. **The auditwheel excludes work and are necessary**: without them, - `libTFELSystem-.so.5.2.0-dev` and friends are grafted into - `mgis.libs/` of the MGIS wheel. The patterns are globs since auditwheel - 6 (`libTFEL*`, ...), cf. §3. -2. **The `tfel/lib` directory survives the repair of the tfel-mfront wheel - itself**: repairing a simulated tfel-mfront wheel leaves the libraries - with their original names in `tfel/lib` (auditwheel only grafts hashed - copies of the libraries needed by the TFEL extension modules, and does - not touch data files). The sibling relative runtime path of the MGIS - wheel therefore always finds its TFEL, whatever repair policy TFEL - chooses. (The default policy does make the TFEL wheel carry its - libraries twice, and register two consumers of the same versioned - sonames; worth reporting upstream, but harmless for MGIS.) -3. **The relative runtime paths are those of the installed layout** - (computed in a simulated `site-packages`, cf. §3): - `libMFrontGenericInterface.so` gets `$ORIGIN:$ORIGIN/../../tfel/lib` as - `DT_RPATH`, the extension modules `$ORIGIN/lib:$ORIGIN/../tfel/lib`. -4. **The version guard fires**: with the metadata of the installed - tfel-mfront changed, `import mgis` raises `RuntimeError: this mgis - wheel was built against tfel-mfront 5.2.0.dev0, but version 9.9.9 is - installed`, rather than failing later in the dynamic loader. -5. **The wheel is usable as a MGISHOME**: `test_wheel.py` compiles a - behaviour with the `mfront` of the tfel wheel, integrates it through - `mgis.behaviour` (exact value of the elastic stress), and builds a - consumer project with `find_package(MFrontGenericInterface)` against the - wheel, which loads the behaviour in C++ — for both the raw and the - repaired wheel, in a clean environment. From a799aa0757d7bd2101506fb6ea17f340f9f98bcc Mon Sep 17 00:00:00 2001 From: t Date: Fri, 6 Nov 2026 15:19:45 +0100 Subject: [PATCH 14/14] docs: release notes of the pip package and of the stubs --- docs/web/release-notes-3.2.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/docs/web/release-notes-3.2.md b/docs/web/release-notes-3.2.md index b43bff118..9b92f9ef6 100644 --- a/docs/web/release-notes-3.2.md +++ b/docs/web/release-notes-3.2.md @@ -280,6 +280,22 @@ if (!isInvariantSatisfied) { } ~~~~ +## `pip` package + +The python bindings of `MGIS` can be installed using `pip`, see the +[installation page](install.html). The wheel depends on the `tfel-mfront` +wheel, pinned to the version of `TFEL` it is built against. + +## Stubs of the python modules + +When the python bindings are enabled and the `pybind11-stubgen` tool is +found, the stub files (`.pyi` files) of the python modules are generated +by the `python-stubs` target and installed next to the modules, with a +`py.typed` marker. The `enable-pybind11-stubgen` option turns this off. + +The arguments of the python functions and methods now have names, and can +be passed by keyword. + # New features of the `MGIS/Behaviour` library ## Save/restore operations in `MaterialStateManager` and `MaterialDataManager` @@ -683,6 +699,10 @@ For more details, see +## Issue 319: Add support for `pybind11_stubgen` + +For more details, see + ## Issue 308: Wrong statements and typos in the documentation and error messages For more details, see @@ -839,6 +859,10 @@ For more details, see +## Issue 254: Add a `pip` package + +For more details, see + ## Issue 250: Add `ErrorBacktrace::assertOrTerminate` For more details, see