PolyFEM builds a C++ finite element stack you configure at CMake time

A polyvalent FEM library that ships an app, not just headers

PolyFEM describes itself as a polyvalent C++ FEM library, and the repository layout shows both halves of that. There is a src directory with the library itself, plus app, tools, tests, cmake and json-specs directories, and a Doxyfile for generated documentation. The important detail for a user is that the deliverable is an executable, not a library you wire into your own program. The main executable is called PolyFEM_bin and can be launched either with a graphical interface or through a command line interface, with the same binary handling both. A Dockerfile.cuda sits next to the ordinary Dockerfile, and the project is described as tested on Windows, macOS and Linux, with topics covering cross-platform builds.

The first CMake configure downloads dependencies, so Git and a network are required

The build requirements are specific and one of them is unusual for a C++ library. A source build needs CMake 3.25 or newer, a C++17 compiler, Python 3 with its development headers, and Git plus an internet connection during the first CMake configuration, because the configuration step downloads the C++ dependencies. That last requirement means the build is not hermetic and cannot be done on an isolated machine without a prepared cache. Python is only needed unless Python expressions are disabled at configure time with -DPOLYFEM_WITH_PYTHON=OFF, which is the switch to reach for when you want a build with no scripting in the scene description. Ninja is optional but recommended, since the documented commands use it and CMake will otherwise pick whatever generator is available on the system.

Configure and build are two commands, and the Docker path encodes the same options

The documented build is short. With Ninja selected explicitly and a release build type.

    cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
    cmake --build build

The container recipe in the Dockerfile shows the same thing with more knobs. It starts from ubuntu:24.04, installs build-essential, cmake, git, libmpfr-dev, libssl-dev, python3 with development headers, pip and ccache, then configures with -DPOLYFEM_WITH_TESTS=OFF, -DPOLYFEM_PORTABLE_BUILD=ON and -DPOLYFEM_WITH_CCACHE=ON, with a BuildKit cache mount for the compiler cache. It sets the working directory to /data and makes the built binary the entrypoint, which is what makes the container usable for batch runs where the scene file is mounted rather than picked in a file dialog.

Running the binary opens a GUI unless you pass a scene file

The usage section is one sentence: the main executable can be called with a GUI or through a command line interface, and running it with no arguments starts it.

    ./PolyFEM_bin

That single command is also the reason two platform notes exist. On Linux, zenity is required for the file dialog window to work, while on macOS and Windows the native windows are used directly. So a headless Linux box without zenity installed has a broken file picker even though the solver itself is fine, and the workaround is to pass a scene path on the command line. The Docker image sidesteps the issue by setting the entrypoint to the binary directly and leaving the working directory at /data for mounted inputs.

Python expressions are the scripting layer, and HDF5 bundles break their usual assumptions

The most interesting constraint in the documentation is about HDF5 input. Python expression scripts stored in an HDF5 bundle must be self-contained with respect to bundled files. PolyFEM extracts the requested script to a temporary file and does not extract sibling files, nor does it redirect Python file reads and imports through the HDF5 resource reader, so reading a data file beside __file__ will not find that file inside the bundle. Files accessed indirectly by Python are not automatically discovered or embedded in checkpoints, and installed Python packages must remain available in the runtime environment, while ordinary filesystem inputs keep their normal Python file access behaviour. In practice this means a scene that references a helper module next to it in the archive will work on disk and fail in a bundle.

Regenerating higher-order basis formulas pulls in a Python toolchain of its own

There is an optional build feature that surprises people. The formula for higher-order bases can be regenerated at CMake time using external Python scripts, and doing so requires numpy and sympy along with quadpy. That is a build-time dependency on a scientific Python stack for a C++ project, which has to be present in the build environment before the first configure. It is optional, so the ordinary path does not need it, but any CI image that rebuilds the formulas has to carry those packages. The repository also includes a PolyFEMOptions.cmake.sample file and a pre-commit configuration, which indicates that build options are meant to be tracked and reviewed rather than improvised per developer machine.

MIT for the code, with a dependency licence audit still on you

PolyFEM itself is under the MIT licence, and the README asks you to be mindful of the third-party libraries it uses, which may be under different terms. That clause is not boilerplate here. The CMake configure step downloads dependencies, so the set of libraries in your build is determined by configuration options rather than by a checked-in manifest, and SPQR, SuiteSparse and the rest enter the picture depending on what you enable. A licence review therefore has to be done against the resolved dependency set of your configuration, not against the repository. The software is developed at the Geometric Computing Lab at NYU Courant and the University of Victoria, and the project asks users to cite both a PolyFEM entry and the Poly-Spline Finite-Element Method paper.

One release tag in 2022, with continuous integration running since

The release history is the weakest signal in this project and it deserves to be read carefully. There is a single tagged release, v0.5, dated 2022-03-03. Meanwhile the repository carries a continuous integration workflow badge, a nightly workflow badge and a codecov badge, and the last push was on 2026-10-14, so the code is being worked on continuously even though nothing has been tagged for years. If you need a pinned, citable version, the tag is v0.5 and it is not recent. If you need current fixes, you are tracking master, which means you own the upgrade cost and the regression risk. The absence of tagged releases is not evidence of abandonment, but it does mean the version number in your papers and your build metadata says very little about the code you actually ran.

Editorial conclusion

Adopt PolyFEM if you want a finite element stack where the same binary offers both a GUI and a command line interface, and if you can accept a source build that pulls dependencies over the network during CMake configuration. Do not adopt it if you expected a packaged binary distribution or a stable release cadence, since the only tagged release is v0.5 from March 2022 and the project ships as source. Verify first that your toolchain has CMake 3.25 or newer and a C++17 compiler, that Python 3 development headers are present unless you configure with -DPOLYFEM_WITH_PYTHON=OFF, and that on macOS you avoid SuiteSparse from MacPorts, since the documented workaround is Homebrew or -DPOLYSOLVE_WITH_SPQR=OFF.

Frequently asked questions

Official sources

1. License: MIT
2. polyfem/polyfem on GitHub
3. Project website
4. README
5. Releases