pyconmech 0.6.0
py bindings for conmech: a C++ lib for 3D frame elastis deformation analysis.
License: MIT license
Keywords: 3D frame analysis,Finite Element Analysis,Structural Analysis

=======
conmech
=======



.. Write 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 <https://manual.karamba3d.com/3-in-depth-component-reference/3.5-algorithms/3.5.1-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 <https://github.com/pybind/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.

Usage
-----

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 <https://github.com/yijiangh/conmech/tree/master/tests/test_data>`_.

The easiest way to generate the model JSON file by exporting from a `Karamba3D`_ model in `Rhino-Grasshopper`_. 
A `example GH export file <https://github.com/yijiangh/conmech/tree/master/examples/gh_scripts/karamba/export_from_karamba.gh>`_ is provided:

.. image:: ./examples/gh_scripts/karamba/images/karamba_model_export.png
    :width: 200px
    :align: center
    :target: https://coveralls.io/github/yijiangh/conmech?branch=master
    :alt: karamba_model_export

You can also parse your model JSON file back to Rhino/GH for visualization/debugging by using the `parse GH example file <https://github.com/yijiangh/conmech/tree/master/examples/gh_scripts/parse_frame_json_conmech.ghx>`_.

Analysis
^^^^^^^^

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

.. code-block:: python

    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]) 
    sc.set_loads(gravity_load=gravity_load)

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

    # 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 <https://github.com/yijiangh/conmech/blob/master/tests/python/test_stiffness_checker.py>`_ for more examples.

Installation
------------

::

  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
^^^^^^^^^^^^^^^^^^^^^

Prerequisites
"""""""""""""

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 ``setup.py`` file included in the base folder, the pip install command will invoke CMake and build the pybind11 module as specified in CMakeLists.txt.

**Note:**

*conmech*'s python bindings are built with a CMake-based build system via pybind11.
Take a look at `cmake_example for pybind11 <https://github.com/pybind/cmake_example>`_ 
if you want to learn more about this.

*conmech* depends on `Eigen <http://eigen.tuxfamily.org/index.php?title=Main_Page>`_ for linear algebra 
and `nlohmann::json <https://github.com/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 .


References
----------

Credits
^^^^^^^

    Yijiang Huang. Conmech. https://pypi.org/project/pyconmech/. 2020.

This package was initiated and maintained by Yijiang Huang `@yijiangh <https://github.com/yijiangh>`_
and other `contributors <https://github.com/yijiangh/conmech/blob/master/AUTHORS.rst>`_.

References
^^^^^^^^^^^^^

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).


Related repos
^^^^^^^^^^^^^

`Frame3dd`_: A static and dynamic structural analysis software of 2D and 3D frames and trusses with elastic and geometric stiffness written in `C`.

.. -----------------

.. _Karamba3D: https://www.karamba3d.com/
.. _Frame3dd: http://frame3dd.sourceforge.net/
.. _Rhino-Grasshopper: https://www.rhino3d.com/6/new/grasshopper

=========
Changelog
=========

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

The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_
and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.

0.6.0
----------

**added**

- 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**

- 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.

**removed**

**fixed**


0.5.0
----------

**added**

- 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**

- 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 ``setup_cmake_utils.py`` to disable cpp test building in ``python setup.py build``

**removed**

**fixed**

**changed**

0.4.0
-----------

**Added**

- 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**

- Changed ``rapidjson`` to ``nlohmann::json``

**Removed**

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

**Fixed**

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

0.3.1
----------

**Added**

- Added unit tests for `std::throw` in parsing material properties

0.3.0
----------

**Changed**

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

0.2.0
-----

**Changed**

- 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``.


**Added**

- 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

0.1.0
-----

Initial version