Skip to main content

py bindings for conmech: a C++ lib for 3D frame elastis deformation analysis.

Project description


conmech is a stiffness checker that performs elastic deformation analysis for 3D frame structures. It is designed for construction sequencing applications, which involves testing the partially assembled structure (subset of the element permutation) many times.

For now, conmech only supports first-order linear FEM simulations of 2D/3D frame structures (similar to the Analyze component in Karamba), but stay tune for a shell analysis backend coming soon ☕!

conmech has a high-performing C++ backend (written in C++11 and wrapped friendly with Python via pybind11) and a flexible, but less performative numpy backend.

🚧 The C++ backend is under development to keep up with the latest feature implemented in the numpy backend. Please use the numpy backend until the next release.


Input model

There are two ways to specify and input a structural model (geometry, material, cross sections, joint releases, support conditions, and loads) to conmech:

  1. directly input data following class structures specified in pyconmech.frame_analysis.io_base
  2. write your data in a JSON format and input the file path to conmech (See file examples here.

The easiest way to generate the model JSON file by exporting from a Karamba3D model in Rhino-Grasshopper. A example GH export file is provided:


You can also parse your model JSON file back to Rhino/GH for visualization/debugging by using the parse GH example file.


After you have the input model ready, analysis is straight-forward:

from pyconmech import StiffnessChecker

sc = StiffnessChecker.from_json(json_file_path=frame_file_path, checker_engine="numpy", verbose=True)
gravity_load = GravityLoad([0,0,-1])

# if the structure's nodal deformation exceeds 1e-3 meter,
# we want the checker to return `sol_success = False`
trans_tol = 1e-3

# existing elements' indices
existing_ids = [0,4,88,6]

# False if the analysis result
sol_success = sc.solve(existing_ids)

# Get all the analysis information:
# nodal deformation, fixity reactions, element reactions
success, nD, fR, eR = sc.get_solved_results()

See python unit tests for more examples.


python -m pip install pyconmech --user
# or python3 if default python is 2.x (OSX or Linux)
# try the following flags when updating: --user --upgrade --force

Build from source

Build python bindings


The following dependencies come from pybind11 for building the python wrappers.

On Unix (Linux, OS X)

  • A compiler with C++11 support
  • CMake >= 3.1

On Windows

  • Visual Studio 2015 (required for all Python versions, see notes below)
  • CMake >= 3.1

Then, clone this repository and pip install.

cd conmech
python -m pip install .
# or python3 if default python is 2.x (OSX or Linux)
# try the following flags when updating: --user --upgrade --force

With the file included in the base folder, the pip install command will invoke CMake and build the pybind11 module as specified in CMakeLists.txt.


conmech’s python bindings are built with a CMake-based build system via pybind11. Take a look at cmake_example for pybind11 if you want to learn more about this.

conmech depends on Eigen for linear algebra and nlohmann::json for json (de-)serialization, both of which are handled automatically by cmake for downloading.

Build C++ code

mkdir build
cd build
cmake ..
make -j2 # Unix

Or on Windows, replace the last line with

cmake --build .



Yijiang Huang. Conmech. 2020.

This package was initiated and maintained by Yijiang Huang @yijiangh and other contributors.


The following textbook is an excellent resource for learning 2D/3D truss/frame analysis, many of conmech’s unit tests are using examples in this textbook as analytical benchmarks:

McGuire, W., R. H. Gallagher, and R. D. Ziemian. “Structural Analysis, Title: Matrix Structural Analysis.” (2015).


All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.



  • Added karamba_io module to facilitate Karamba3d-JSON two way conversion.
  • Added Model and LoadCase classes
  • Added element information to ValueError when encountering zero-length line element
  • Added print out attributes to Node and Element


  • Changed StiffnessBase’s __init__ from inputting nodes, elements, … to Model
  • Moved get_element_crossec and get_element_material from NumpyStiffness to StiffnessBase
  • Changed StiffnessChecker’s set_loads to take LoadCase object
  • Changed Joint’s c_conditions attribute to a 12-entry list instead of a dictionary with two six-entry lists
  • Karamba conversion is now done more formally with karam_io modules, without using an ad-hoc C# component.





  • added the numpy engine
  • added removing loads functionality by passing in none
  • added base classes for input data: io_base.node, element, support, joint, material, crosssec, pointload, etc.


  • changed frame data format, use karamba exported format
  • changed stiffnesschecker’s __init__ function’s arguments to take io_base.* data
  • changed stiffnesschecker’s default behavior: not applying gravity load by default
  • changed -dconmech_build_tests=off in to disable cpp test building in python build






  • Added StiffnessChecker class method, directly construct from frame data, without saving data to a temp json
  • Added some initial cpp unit tests, test data fed in by CMake and tests organized by Catch2


  • Changed rapidjson to nlohmann::json


  • Removed the Frame data structure in Stiffness checker’s cpp backend
  • Removed all the git submodule and used CMake download external instead


  • Fixed the memory leak caused by the smart pointer cycle dependency in Frame



  • Added unit tests for std::throw in parsing material properties



  • Changed try/catch in the C++ file parsing to std::throw



  • The original stiffness_checker extension module is wrapper as _stiffness_checker. All the cpp modules are wrapper under a top-level python classes/functions, to give more flexibility.
  • API change: stiffness_checker class is renamed to StiffnessChecker to conform
    to the class naming convention. All other APIs within this class are left unchanged.
  • Delete radius entry from material_properties.


  • documentation is hosted on readthedocs!
  • add grasshopper examples - parse/save files, karamba comparsion, solve/get result in GH via ghpython-remote
  • supports material / cross sectional properties for each element.
  • supports uniformly distributed load
  • add gravity magnitude and direction


Initial version

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyconmech-0.6.0.tar.gz (7.2 MB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page