# Welcome to Karamba3D The official guide to using Karamba3D v3. The latest version is 3.1.4. Karamba3D is an interactive, parametric engineering tool that allows you to perform quick and accurate Finite Element Analysis (FEA). It has been specially tailored to the needs of design professionals in the early design phases. Karamba3D is embedded in the parametric environment of Grasshopper in the 3d modelling program Rhino3D. This makes it easy to combine parameterized geometric models, Finite Element calculations and optimization algorithms like Galapagos, Octopus, Wallacei and many more. Karamba3D can also be used as a standalone .NET library for integrating Finite Element functionality into your scripts. This v3 manual is currently available in English only. The Chinese manual is available for version v1. The Japanese manual (v1) can be downloaded from our [website](https://karamba3d.com/resources/). ## Citing Karamba3D In case you use Karamba3D for your scientific work, please cite the following paper: > Preisinger, C. (2013), *Linking Structure and Parametric Geometry*. Architectural Design, 83: 110-113\ > DOI: 10.1002/ad.1564. ## Disclaimer Although being tested thoroughly Karamba3D probably contains errors – therefore no guarantee can be given that Karamba3D computes correct results. Use of Karamba3D is entirely at your own risk. Please read the [license agreement](https://karamba3d.com/license-agreement/) that comes with Karamba3D in case of further questions. This manual is written by Clemens Preisinger except when noted otherwise.\ Editing by Georg Lobe & Matthew Tam & Sara Rodiqi.\ Chinese translation by Lei Feng. # New in Karamba3D 3.1 {% embed url="" %} We regularly release service updates on [GitHub](https://github.com/karamba3d/K3D_NightlyBuilds/releases) and through Rhino's YAK package manager. Each service release includes a list of new features and bug fixes. ## Karamba3D 3.1.60519 #### New Features: * **Model Export:** Added the ability to export directly to ETABS using E2K files and SAP2000 using S2K files. * MeshLoads now support defining a minimum length when creating trapezoidal loads on beams. * **Curve-Curve Intersection Component:** Replaces the *Line-Line Intersection* component, and supports polylines and curves as inputs - see [here](/3-in-depth-component-reference/3.8-utilities/3.8.7-line-line-intersection). #### Bug Fixes: * Updated load components: for imperial units, inputs must now be provided in psf (lb/ft²) and lb/ft. Output values have also been revised, which may affect existing setups that relied on ksi outputs.\ The selection of units for component input and output changed - see [here](/2-getting-started/2-getting-started-1/2.3-physical-units#how-to-set-unit-preferences). * Fixed an issue where prescribed displacement loads yielded incorrect results approximately every 30th recalculation. * Resolved a problem causing the LinearElement component to disappear when used inside a cluster that was saved and reopened. * Introduced a warning to highlight compatibility issues with other plugins using EPPlus.dll. * Updated Beso, Eigenmodes, NaturalVibes, BucklingModes, and TenComEliminator: load cases can now be specified using the format “LoadCaseCombinationName/IndexOfLoadCase.” * Removed the “Work in Progress” label from the CalculationReport component. * Corrected product type classifications in cross-section tables (rolled, welded, cold-formed). * Fixed a stack overflow error in SAF export for polylinear loads. * Corrected visualization issues related to load offsets. ## Karamba3D 3.1.60309 #### New Features: * **MeshLoad Component:** Now supports generating non‑uniform line loads on beam elements. See here: [3.2.1: General Loads](/3-in-depth-component-reference/3.2-load/3.2.1-loads#mesh-load-const-and-variable). * **Cross Section Selector Component:** Added a fuzzy‑search option in the context menu, allowing more flexible matching of cross‑section names (e.g., “IPE 80”, “IPE-80”, “IP 80” will all correctly resolve to IPE 80). See here: [3.3.8: Cross Section Selector](/3-in-depth-component-reference/3.3-cross-section/3.3.10-cross-section-selector). * Introduced new Japanese cross‑section families. * Added multi-byte letter support for cross-section names. * **Support Agent Component**: Newly added component to streamline the workflow for defining supports. See here: [3.1.16: Support Agent](/3-in-depth-component-reference/3.1-model/3.1.16-support-agent). * **ModelView**: Added a Loads Offset slider that lets users visualize loads at a custom distance from their actual point of application. See here: [3.7.1.1 ModelView](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.6.1-modelview). #### Bug Fixes: * **SAF Exporter:** Corrected the export of trapezoidal line loads. * **RFEM6 DSTV Export:** Fixed units mismatch when exporting line loads; Could not make export of supports and gravity work; * Fixed issue [#148](https://github.com/karamba3d/K3D_NightlyBuilds/issues/148): Eccentricity display can now be disabled even for models that have not yet been analyzed. * Fixed issue [#147](https://github.com/karamba3d/K3D_NightlyBuilds/issues/147) * Corrected missing numerical output in cross‑section force diagrams at beam endpoints when values were constant. * **Cross Section Range Selector Component:** Improved performance—fixed sluggish behavior when many cross sections were selected simultaneously. * **Calculation Report Component:** Fixed an issue preventing correct output of displacement values for models containing both beams and shells. ## Karamba3D 3.1.51222 #### New Features: * **Disassemble Support Component:** Introduced a component that retrieves the properties of supports. See here: [3.1.17: Disassemble Support](/3-in-depth-component-reference/3.1-model/3.1.17-disassemble-support). * **Load Case Properties Component:** Load cases can now be defined independently of loads. In addition to the load-case name, one can specify the load duration type and action type. The load-case durations determine those of the load combinations (adresses request [#139](https://github.com/karamba3d/K3D_NightlyBuilds/issues/139)). See here: [3.2.5.4 Load-Case Properties](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations/3.2.5.4-load-case-properties). * **Automatic Obsolete Component Update:** Added a menu item under Grasshopper → Karamba3D → Components → Update Obsolete Components to automatically replace outdated Karamba3D components with their updated versions. This applies to components deprecated in this release (adresses request [#135](https://github.com/karamba3d/K3D_NightlyBuilds/issues/135)). See here [2.3 The Karamba3D Menu](/2-getting-started/2-getting-started-1/2.3-the-karamba3d-menu). * **Cross Section Range Selector:** Added a drop-down menu for selecting a specific cross-section within a family. See here: [3.3.7: Cross Section Range Selector](/3-in-depth-component-reference/3.3-cross-section/3.3.9-cross-section-range-selector). * **Cross Section Database:** Included Japanese H, CHS, and RHS sections. * **Element Guids:** GUIDs are now linked to element creation components. Updating a component preserves the sequence of GUIDs, making it easier to manage element identities in C# scripts. * **ModelView Enhancements:** Annotation text now stacks when multiple options are selected and is displayed as 3D text for improved visibility. Under Annotations, a new slider allows scaling the offset of text from elements. See here: [3.7.1.1 ModelView](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.6.1-modelview). * **Hierarchical Element Identifiers:** Element names can now include dots (.) to represent hierarchical levels. For example, an element named level1.level2.level3 can be referenced as level1, level1.level2, or level1.level2.level3. See here: [2.7 Naming and Selection of Elements](/2-getting-started/2-getting-started-1/2.7-naming-and-selection-of-elements). * **HUD Legend Component:** Added an input for adjusting text size. See here: [3.9.19 Head-Up Display Legend](/3-in-depth-component-reference/3.8-utilities/3.9.19-head-up-display-legend). #### Bug Fixes: * **Bending Moment Diagrams:** Diagrams generated by the BeamView component now display on the side corresponding to tensile stresses (fixes issue [#143](https://github.com/karamba3d/K3D_NightlyBuilds/issues/143)) * **Colors of Elements, Cross Sections and Materials**: now show correctly (fixes issue [#145](https://github.com/karamba3d/K3D_NightlyBuilds/issues/145)). * **Missing HUD Legend**: was readded (fixes issue [#144](https://github.com/karamba3d/K3D_NightlyBuilds/issues/144)). * **MeshLoad Component**: accepts again regular expressions (fixes issue [#138](https://github.com/karamba3d/K3D_NightlyBuilds/issues/138)). ## Karamba3D 3.1.50925 #### New Features: * **AnalyseThII Component:** Introduced the *NoComNII* option, which restricts compressive normal or in-plane forces to small positive values in the geometric stiffness calculation. This enables stabilization of structures with localized compressive regions, such as membranes. * **KeyListener Component:** Utility component that triggers recomputation when the user presses *Shift + F1–F12* within Rhino or Grasshopper. Facilitates rapid switching between Karamba3D model visualization modes. * **Cross-Section Database:** Updated and refined Japanese steel section data; introduced cross-section type *H* corresponding to I-profiles. * **Material Database:** Updated Japanese steel material properties. * **HUD Legend Component:** Added *TextSize* input parameter. * **Element Query Component:** Added *Axis* output to provide element axes. #### Bug Fixes: * **Second-Order Theory:** Corrected omission of stabilizing effects from tensile normal and in-plane forces, which previously resulted in overly conservative buckling load factors and overestimated displacements in ThII analyses. * **Load Case Combination:** Eliminated duplicate load case generation; dead weight from multiple load cases can now be combined like other load types. * **Beam Rendering:** Enhanced beam mesh visualization by implementing independent caps as mesh parts. * **Component Labels:** Removed duplicate nicknames in English-language mode. * **Node Forces Component:** *Elems* output can now be used to derive element axes. ## Karamba3D 3.1.50730 #### Bug Fixes: * Implemented a workaround to ensure Karamba3D updates properly on YAK. * **Support Component**: Resultant support reactions are now correctly transformed into global directions. * **SurfaceToTruss Component**: Subdivision count of 1 no longer causes an error. * **New Mesher**: Improved performance when intersecting a large number of surfaces. * **BeamModifier**: Resolved issue where the buckling length changed despite no input modifications. * **LineToBeam Component**: Buckling length can now be explicitly set to zero. ## Karamba3D 3.1.50707 #### New Features: * Introduced the WIP "Report" component for exporting calculation results to Excel files. * Implemented a compatibility check for conflicting versions of "libiomp5md.dll" that may interfere with Karamba3D. * Relocated the language settings from "Show Components" to the "Settings" section of the Karamba3D Grasshopper menu. * Added a new "Number Format Digits" option under "Settings" in the Karamba3D menu for adjusting numeric precision of graphical outputs. * Updated the "Material Selection" component to include a country selector for filtering materials by region. * Standardized the "Surface To Truss" component output so that all typologies now generate the same number of geometry output branches. * Introduced a new legend component for heads-up display. #### Bug Fixes: * Corrected the numeric labels on line-load symbols. (Fixes issue [#119](https://github.com/karamba3d/K3D_NightlyBuilds/issues/119)) * Nodal loads are now properly deactivated when all connected elements are inactive. (Fixes issue [#120](https://github.com/karamba3d/K3D_NightlyBuilds/issues/120)) * Disabled Trace.Listener output in the Rhino command window. (Fixes issue [#122](https://github.com/karamba3d/K3D_NightlyBuilds/issues/122)) * It is now possible to feed elements into the MeshLoad-component so that they get loaded. (Fixes issue [#125](https://github.com/karamba3d/K3D_NightlyBuilds/issues/125)) * Duplicate load cases are now properly removed from load case combinations. (Fixes issue [#126](https://github.com/karamba3d/K3D_NightlyBuilds/issues/126)) * The Tension/Compression component now supports individual load cases defined by 'loadCaseCombinationName/idx1/idx2/…', using specified indices for tension/compression elimination checks. (Fixes issue [#127](https://github.com/karamba3d/K3D_NightlyBuilds/issues/127)) * The WIP mesher now handles additional edge cases in Brep geometry. * Fixed the placement of concentrated beam loads on eccentric beam axes. ## **Karamba3D 3.1.50414** ### Bug Fixes: 1. Resolved an error in calculating support reactions based on the second-order theory for shell and membrane elements. (Fixes issue [#103](https://github.com/karamba3d/K3D_NightlyBuilds/issues/103)) 2. Removed a memory leak in the cross-section optimizer. (Fixes issue [#102](https://github.com/karamba3d/K3D_NightlyBuilds/issues/102)) 3. Addressed issues in the cross-section optimizer related to optimization with displacement limits. (Fixes issues [#101](https://github.com/karamba3d/K3D_NightlyBuilds/issues/101) and [#100](https://github.com/karamba3d/K3D_NightlyBuilds/issues/100)) 4. Buckling length can now be set at the "LinearElement"-component. (Fixes issue [#99](https://github.com/karamba3d/K3D_NightlyBuilds/issues/99)) 5. In the LineLineIntersection component, the "LDist" input now correctly sets the maximum distance for line intersections. Minimum intersection segment length is now allowed to be smaller. (Fixes issue [#116](https://github.com/karamba3d/K3D_NightlyBuilds/issues/116)) 6. The "SurfaceToTruss" component now generates equal numbers of line segments for the upper and lower chords when set to "Warren Truss." (Fixes issue [#115](https://github.com/karamba3d/K3D_NightlyBuilds/issues/115)) 7. Corrected a bug in the result selection logic. Numerical result components with "LCC/0" now correctly select only the first load case in a load case combination, rather than all. (Fixes issue [#111](https://github.com/karamba3d/K3D_NightlyBuilds/issues/111)) 8. Updated the help texts for all "LCase" input parameters to clarify default behaviors. (Fixes issue [#110](https://github.com/karamba3d/K3D_NightlyBuilds/issues/110)) ## **Karamba3D 3.1.50129** ### Bug Fixes: 1. Fixed bugs in the ReactionView-component: Now the legend colors and tags show up again. 2. Added a ribbon icon for Karamba3D in RH8. ## **Karamba3D 3.1.50121** ### New Features 1. **Load-case and Load-case Combination Ordering:** * Load-cases and their combinations are now ordered as they are input into the Assemble component. * **Breaking Change:** Older definitions relying on alphabetical ordering may be affected. 2. **Numerical Result Ordering:** * Element results are now structured based on selection order at the corresponding component input. * **Breaking Change:** Previously, results were structured by tree-branches indexed by element index. 3. **String Input for Load-Containers:** Allows the creation of a dummy load to facilitate ordering of load-cases within the Assemble component. 4. **Prediscribed Displacements at Supports:** Now included within the 'Load' component. 5. **Enhanced Support Capabilities:** Supports can now incorporate attached spring stiffnesses. 6. **BeamView Enhancements:** Additional display options, including utilization visualization according to EC3 standards via colored lines, buckling lengths, and more. 7. **ModelView Improvements:** * The "View" input plug now accepts planes and base-lines to define visibility settings. * Example available: "ModelView\_SelectView\_BaseLine.gh" in folder `07_Results` of installed examples. 8. **"karamba.ini" Configuration:** The parameter `MinNumberOfSegmentsForResults` can now be set to "1" to allow mesh faces spanning the entire beam length. 9. **LineJoint Component Usability:** Simplified operation with no requirement for Y- and Z-direction definitions when working with naked edges and single-surface joints. 10. **Cross Section Optimizer Enhancements:** Differentiates between elements reaching maximum size (warning issued) and elements where cross-section selection did not converge (remark issued). 11. **Element Utilization Calculation:** * If no capacity exists to resist a specific cross-section force component, a value of `1E6` is added to utilization. * Utilization resulting predominantly from compression is now returned as a negative number. 12. **Parametric UI Rendering:** Improved symbol display for better visualization. ### Bug Fixes: 1. Resolved memory leak issues. 2. Fixed calculation bug in user-defined circular cross-section (Wt computation). 3. Corrected "$" notation functionality for load-case selection in load-case combinations. 4. Addressed a bug in static license activation. 5. Fixed symbol scaling issues when switching units from meters to millimeters. ## **Karamba3D 3.1.41125** ### New Features: 1. **Async-Enabled Components:** The following components are now fully asynchronous (async) compatible: AssembleModel, all Algorithms components, ModelView, BeamView, ShellView, LineResultsOnShells, MeshBreps and Shell Section.\ For details see [section 2.6](/2-getting-started/2-getting-started-1/2.6-asynchronous-execution-of-karamba3d-components). 2. **Load Case Combinations:** When defining combinations using the "Load-Case-Combinator" component, load case names containing special characters (e.g., +, -, \*, etc.) can now be enclosed in quotation marks (" or ') to ensure proper handling as a single entity. 3. **Warning for Incomplete Load-Case Combinations:** The Assemble component now issues a warning if load cases referenced in load-case combinations do not have associated loads. 4. **Rhino8 YAK-Installer Enhancements:** The installer now includes support for both .NETCore 7 and .NET Framework versions. ### Bug Fixes: 1. **Line-Load Annotations:** Resolved an issue where annotations were missing on line loads applied to beams when combined with non-unit load factors. 2. **Connected Parts Component:** Addressed missing paths in the "Connected Parts" component for models that include both shells and beams. ## **Karamba3D 3.1.41024** ### What's New: The following components are now asynchronous (async) capable: AssembleModel, all Algorithms components, ModelView, BeamView, ShellView, LineResultsOnShells, and MeshBreps. * These components can operate without blocking the UI thread. * New context menu options include "Cancel" and "Parallel Execution." * Global async computation control is available under Karamba3D > Settings > Async Execution. * By default, async execution is turned off. * To prevent potential crashes, disable async execution when using loops or optimizers (e.g., Galapagos). Karamba3D is now thread safe. ### Fixed Bugs: * Resolved a crash that occurred when using Eigenmodes, NaturalVibes, or Buckling components before running any prior analysis. ## **Karamba3D 3.1.40918** ### What's New: * Load cases and load case combinations can now be excluded from the default set (e.g., for "Analyse") by adding an underscore ("\_") at the start or end of their names. * Added an example script for retrieving the system stiffness matrix. * Improved the performance of the CroSecOpti routine. * Introduced safeguards against large models that would lead to long render times (configurable via the MaxEvaluationPointsInModel parameter in the karamba.ini file), which may occur due to incorrect length units. ### Fixed Bugs: * Fixed a memory leak in the NaturalVibes calculation. * Corrected export issues for box cross-sections in Speckle. * Ensured the outline of trapezoid cross-sections is closed during Speckle export. * Fixed an exception when retrieving beam forces at positions defined by maximum distance. * Help text units now correctly update when the length unit setting in the GH definition differs from local user settings. * CroSecOpti: Displacement optimization now handles cases where elements exhibit negative virtual work. * Added safeguards for element identifiers against number-only names when using the "name1|name2|..." format, where multiple names can be assigned per element. * AnalyzeNonLin: Resolved crashes when working with multiple load cases. * Corrected display of prestrain load values. * Fixed scaling issues with load symbols when different length units are applied. ## **Karamba3D 3.1.40718** ### What's New: * Added Speckle structural model import- and export-component. It is work in progress. Enable "View WIP components" in the Karamba3D menu to see it. ### Fixed Bugs: * Fixed a memory leak. * Fixed a bug in the displacement control part of the cross section optimizer. * SAF export: fixed signs of cross section forces and moments to correspond to IDEA StatiCa. * Fixed a units conversion bug regarding the stiffness values of the JointAgent-component. * Fixed a bug in the internalization of Karamba3D models. ## **New in Karamba3D 3.1.4** * **"Reaction View" component**: This new component simplifies the rendering of reaction forces and moments at supports. A corresponding parametric user interface component, **"Reaction View pui"**, is also available. * **"Export Model to SAF" component**: This component exports Karamba3D models to the **SAF format**, compatible with many traditional AEC applications. The export includes surfaces and certain types of surface loads. * **"Create Linear Element" component**: Consolidates functionality from the previous **"Line to Beam"**, **"Connectivity to Beam"**, and **"Index to Beam"** components into a single component. * **"Optimize Cross Section" component**: Now allows virtual force load-cases to be directly supplied, enabling finer control over displacement. * **"Assemble Model" component**: The **"Points"** input plug has been moved to the **"Options"** submenu to reduce confusion regarding required inputs for model assembly. * Changing the **language or physical units** in the Grasshopper/Karamba3D model now instantly updates component help texts and annotations. * **Base physical units** (force, length, mass) are now stored within the Grasshopper definition, making model exchange smoother and preventing unexpected changes. * **MSI-installers** are now available for **Rhino 8** for both **.NET Framework** and **.NET Core**. The **.NET Core** version of Karamba3D is installed when using the package manager in Rhino 8. * Enhanced accuracy in representing **discontinuities** in beam section force diagrams. * **Version numbering** now reflects the build's year, month, and day (last five digits). * **"Disassemble Mesh Load" component**: Improved for exporting mesh loads as line loads on elements. **Bug Fixes:** * Inclusion of the **Spanish language** version for user interface texts in the MSI-installer. * The **"Element Felting"** component now supports **springs** as connection elements. ## **New in Karamba3D 3.0.0.5** * ["Optimize Cross Section"-component](/3-in-depth-component-reference/3.5-algorithms/3.5.8-optimize-cross-section): * Different load-case-combinations can be used for ultimate limit state (ULS) and serviceability limit state (SLS) design optimization. * Displacement optimization for SLS is now done using a virtual forces approach for more economic results. * Elements with insufficient cross sections in ULS and SLS can be highlighted using the "ModelView"-component. * The "ModelView"-component: * "Annotation/NII" option now outputs the NII force of the currently visible load-case. * A "Result Selection" submenu was added to the "ModelView"-component. This allows to quickly select the display of minimum and/or maximum results for load-case combinations of a specific load-case of a combination. * The "Annotations" submenu now contains a slider to quickly adapt display text-heights. * It is possible to display single shell sub-elements by providing "Shell-Index/Meshface-Index" at the "View" input-plug. * [The "Line-Line Intersection"-component](/3-in-depth-component-reference/3.8-utilities/3.8.7-line-line-intersection): * Has been refined: it is now possible to define intersecting lines and lines to intersect. * Can intersect parallel lines which lie on each other. * The grammar for defining load case combinations has been made more flexible. * The order of load cases and load case combinations in the model adheres to the order of defining load case combinations and feeding load cases into the assemble component. * The order of loads after disassembling a model now corresponds to the order of input at the "Assemble"-component. * When using Karamba3D's "Mesh Breps"-component the underlying surface gets attached to the mesh as custom data. * "Point-Mass"-component: added scaling factors for mass for translational inertia in global directions. * Added the "Analyse ThII"-component to have a shortcut for specifying second order theory analysis steps. This represents an alternative to applying the "Load Case Combination Settings"-component. * The "Buckling Modes"- and "Natural Vibes"-components now have an input-plug for specifying the load-case-combination from which second order theory forces NII are to be taken. * "Joint Agent"-component: * fixed bug that caused hinges to be added to beams when the beam-identifier of the second beam did not exist. * made limit-distance of joint agent for testing points for vicinity dependent on the limit-distance of the 'Assemble'-component. * Changed handling of materials with different absolute values of tensile and compressive strength in EC3 design procedure: sign of normal force decides whether the tensile or compressive strength shall be applied. * Added joint colors to the "karamba.ini"-file. * Added a warning in case Karamba3D detects another Grasshopper plug-in which might come with its own version of the OpenMP-library "libiomp5md.dll" since this can cause crashes. * Made "Shell Section"-component work with breps as intersecting geometries. **Bug fixes:** * Fixed bug in serialization of locally oriented supports. * Fixed a bug in the retrieval of shell-section results which resulted in partial result display. * Parametric UI: made arrow heads scale with the forces and moments. * Fixed bug in definition of Tsai-Wu factor for orthotropic materials. * "LineToBeam"-component did not convert linear-curves. Now it does. * Material table: compressive strength of glulam timber was positive. * Fixed problem with coloring of results with small positive and large negative range. * Fixed bug in setting the color range via the "ModelView"-component. ## **New in Karamba3D 3.0.0.4** There are two big new features: * Load case combinations * Interoperability via BHoM (see section ["BHom"](broken://pages/nHSWzwh3oaYTMfhznBg7) of this manual and the Github repository [here](https://github.com/BHoM/Karamba3D_Toolkit)) which will be included in the official BHoM release in the next few days. The current version 3.0.0 is work in progress: * Load-case combinations haven't yet been integrated into the cross-section optimizer. The "Optimize Cross Section"-component results are based on all load-cases present in the model. * The $$N^{II}$$-forces used for cross section optimization, eigenmodes-, eigen frequency- and buckling-calculations are taken as the smallest value encountered in a previous analyze step. * Result combinations will be included to provide spectral analysis for earthquake loads. * Not all of the examples in this manual have not yet been updated to version 3. ## **Load Case Combinations** Up to now Karamba3D provided the possibility to work with load-cases. These were defined at the components for creating loads by specifying their name. With version 3.0.0 Karamba3D offers load case combinations. These components help in creating and handling load case combinations: * ["Load-Case-Combinator"-component](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations/3.2.5.1-load-case-combinator): Takes a list of combination rules expressed as text and converts them into load-case combinations. * ["Load-Case-Disassemble"-component](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations/3.2.5.2-disassemble-load-case-combinaton): Reveals details of a load-case combination: which load-cases contribute with what factors. * ["Load-Case-Combination Options"-component](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations/3.2.5.3-load-case-combination-settings): Specifies details with regards to how the load-case-combination needs to be evaluated: first order theory, second order theory with possibility of linear superposition or second order theory for each load-case individually. * ["Analyze"-component](/3-in-depth-component-reference/3.5-algorithms/3.5.1-analyze): Load-case combinations know about their calculation type. The "Analyze"-component uses this information to treat them accordingly. The user can specify the load-case-combinations of interest and limit analysis to these. * ["Load-Case Selector"-component](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.7.1.2-result-selector): Load case combinations can contain large sets of load-cases. The "Load-Case Selector"-component helps to select the results of interest for each point of a structure. It is possible to select the envelope of specific response properties, results of a load case of interest, or the set of results that accompany a leading property (e.g., maximum moment and other cross section forces that come along with it). The component outputs a query string which can be used as input for specifying the load-case in all result components of Karamba3D. Depending on the given load-case selection result-components output values for multiple load-cases. This works now via Grasshopper's Data-Tree-objects. The outmost branches correspond to load-cases, then come positions along an element (if applicable), then the level of elements. Branch indexes at element-level correspond to element-indexes in the model. This eliminates the necessity to introduce dummy values in case a result-component does not apply to all types of elements. Without the definition of load-case combinations the handling of Karamba3D models does not change as compared to previous versions of Karamba3D - with the exception of Data-Tree output at the result-components. Flattening these eliminates the difference between new and old version. # 1.1 Installation These are the prerequisites for installing Karamba3D: * Rhino 6.0 (PC only), Rhino 7.0 or Rhino 8.0. * Grasshopper * Windows 10 or above / macOS 12 or above In case you do not possess [Rhino](https://www.rhino3d.com/), download a fully featured, free trial version. ## Installation via Installer Program {% embed url="" %} [Download ](https://www.karamba3d.com/download/)one of the installers and double-click on the msi-file. The installation procedure lets you set the physical units used for calculation. By default Karamba3D assumes input to be in SI units (e.g. meters for point coordinates). You can switch to Imperial units either on installation or later via the Grasshopper/Karamba3D menu under "Physical Units". When using Imperial Units coordinates will be interpreted to be in “feet”, force in “kips”, material strength in “ksi” and so on. For [Rhino8](https://www.rhino3d.com/en/docs/guides/netcore/) there exist two installer files: one for .NETFramework and on for .NETCore. By default Rhino 8 runs on .NETCore. In orer to run old plug-ins, Rhino 8 can be switched to .NETFramework mode with the command 'SetDotNetRuntime'. In these situations the .NETFramework version of Karamba3D can be used. Upon successful installation you should see a Karamba3D tab when you open Grasshopper in Rhino. Additionally, as a default setting a shortcut to the installation folder will be placed on your desktop. Double-click on the Karamba3D desktop-icon will get you to the standard installation directory which is in the Plug-ins-folder of your Rhino installation directory. If Karamba3D does not show up, please refer to our [troubleshooting ](/troubleshooting/4.3.-miscellaneous-problems/4.3.1-installation-issues)guide. Karamba3D license can be activated as cloud or network licenses. Standalone licenses are only valid for workshops or universities. {% content-ref url="/pages/-MCkEPscNP\_GouaetMDP" %} [1.2.1 Cloud Licenses](/1-introduction/1.2-licenses/1.2.1-cloud-licenses) {% endcontent-ref %} {% content-ref url="/pages/-MCkEPsZl8HXNZYXsaNn" %} [1.2.4 Standalone Licenses](/1-introduction/1.2-licenses/1.2.4-standalone-licenses) {% endcontent-ref %} {% content-ref url="/pages/-MCkEPs\_LeHTa5tYcR3h" %} [1.2.2 Network Licenses](/1-introduction/1.2-licenses/1.2.2-network-licenses) {% endcontent-ref %} ## Installation via the YAK Package Manager {% hint style="danger" %} Karamba3D can only be installed via msi-file **or** yak. If both are installed at the same time, the 'Karamba3DGetLicense'-command will not work.\ If you happen to have installed both: uninstall them and remove the Karamba3DLicense-plugin in Rhino via Options/Plug-ins, unhooking 'Enabled' and restarting Rhino. {% endhint %} {% embed url="" %} YAK is the Package Manager for Rhino. It can automatically download and install plug-ins required for a specific Grasshopper definition. Thus one possibility of installing Karamba3D is to open a GH definition with some Karamba3D components in it. Alternatively the package manager can be started in Rhino by typing 'PackageManager' in the command window. Make sure to activate 'Include pre-releases' in the window that pops-up. Under YAK Karamba3D comes as 'karambaGH' which installs the FULL version of Karamba3D. The Rhino8 Package Manager installs the .NETCore version of Karamba3D under Windows to the folder %appdata%\AppData\Roaming\McNeel\Rhinoceros\packages\8.0 - which is different from where it is placed by the msi-installer. When starting Grasshopper for the first time after a YAK-installation of Karamba3D, a window with copyright notice and terms and conditions will appear. Copyright notice and license agreement can be found on Windows under C:\ProgramData\Karamba3D\\. {% hint style="info" %} The path to Karamba3D depends on whether installation was done via the msi-installer or YAK. This means that scripts which make use of the Karamba3D API may be broken. In case of GH C# scripting components one needs to adapt the path via "Manage Assemblies..." in the components context menu. {% endhint %} {% hint style="warning" %} To run Karamba3D in Rhino8 for Mac, make sure to enable [Rosetta](/troubleshooting/4.3.-miscellaneous-problems/4.3.1-installation-issues#karamba3d-for-rhino8-mac-does-not-seem-to-show-up). {% endhint %} ## Rhino6, Rhino7 and Rhino8 in parallel You can install the Rhino 6, 7 and 8 versions of Karamba3D simultaneously by installing one with the msi installer, and the other with the Package Manager. ## Silent Installation To install Karamba3D on remote machines without triggering the installer’s graphical user interface, you can use the `msiexec.exe` tool from the Windows Command Prompt. First, navigate to the directory containing the Karamba3D installer, then run a command like the following in a single line: `msiexec.exe /i karamba3d_2_0_0_RH6.msi /passive ADDLOCAL=DLLs,LicensePlugin,SIUnits,LicensePublicKey,Tables,Examples` This installs Karamba3D with SI units (`SIUnits`), cross-section and material tables (`Tables`), and example files (`Examples`). **License Setup Without GUI** A static license can be provided without using a graphical interface. Simply rename your license file to `licensePRO.lic` and place it in the `License` folder under: ...\Rhino\Plug-ins\Karamba. **Using msiexec on Windows together with Karamba3D:** The basic syntax for *msiexec* is: `msiexec /option [optional parameter]` **Install Options for msiexec:** To install a package, you can use the */i* option followed by the path to the package: `msiexec /i "C:\path\to\karamba.msi"` Other install options include: * */a*: Administrative installation. * */ju*: Advertise the product to the current user. * */jm*: Advertise the product to all users. * */x*: Uninstall the package Installation Options via `ADDLOCAL` You can customize the installation by specifying components using the `ADDLOCAL` parameter: * `DLLs`: Installs the FEM kernel DLLs. * `LicensePlugin`: Adds the Rhino plugin used for license activation. * `SIUnit` or `IMPUnits`: Sets the default unit system (modifiable later in Grasshopper via the Karamba3D menu). * `LicensePublicKey`: Installs the public key required to validate the license. * `Tables`: Installs cross-section and material tables. * `Examples`: Installs sample Grasshopper definitions. ## **Automate installation** The following files and folder will be copied to your machine during installation: * “karamba.dll” and “libiomp5md.dll” to C:\Windows. * “karambaCommon.dll”, “karamba.gha” and the Karamba-folder to the “Plug-ins”-folder of Rhino. The Karamba3D-folder contains material- and cross section libraries, examples, the karamba.ini- file and the license-folder. This is typically *C:\Program Files\Rhinoceros 6\Plug-ins* or *C:\Program Files\Rhino 6\Plug-ins.* * If not already present the C++ runtime libraries of Visual Studio 2019 will be copied to your machine. Karamba3D is installed for all users by default. In order to get Karamba3D running without the installer simply copy the above files and the Karamba3D-folder from one machine to the next.\ Unless deselected, the installer places a Karamba3D-icon on the desktop. Double-click on it to open the Karamba3D-folder. # 1.2 Licenses In addition to the EDU student license and the LAB university license, which are for non-commercial use only, there is also a PRO version of Karamba3D available for commercial use. PRO, EDU & LAB licenses can be purchased from our[ website](https://karamba3d.com/get-started/#license). Further information can be found on [features ](https://karamba3d.com/get-started/#license)& [license agreement](https://www.karamba3d.com/buy/license-agreement/). ## Activating Licenses Licenses can be installed as: 1. [Cloud licenses](/1-introduction/1.2-licenses/1.2.1-cloud-licenses): these require a Cloud Zoo account and allows you to use them from any device and/or share them with team members. Find out more on [Cloud Zoo Licenses](https://wiki.mcneel.com/rhino_accounts/home) on McNeel. 2. [Network licenses](/1-introduction/1.2-licenses/1.2.2-network-licenses) (PRO or LAB users only): also known as LAN Zoo; keeps your licenses on your private LAN server and lets you share them among the Rhino users on your network. Find out more on [LAN Licenses](https://wiki.mcneel.com/zoo/home) on McNeel. # 1.2.1 Cloud Licenses Guide to running Karamba3D with a cloud license. Find out more on [Cloud Zoo Licenses](https://wiki.mcneel.com/rhino_accounts/home) on McNeel. {% hint style="warning" %} Please note that we do not have access to your Rhino account. You can always remove and add the license to a different account/team at any time. Refer to [Account Settings](#account-administration). {% endhint %} If you are looking to upgrade an existing standalone or network to the cloud, please email us at . ## **Installation** ### 1. Load License Make sure you have Karamba3D for Rhino6 or above [installed](/1-introduction/a.2-installation#standard-installation). Type "**Karamba3DGetLicense"** in the Command line ![](/files/-MCkERwzK9x0C9MI88Kq) ### 2. Login into your Rhino3D account Login to your account at Rhino3D account. Cloud licenses are available on McNeel's [Cloud Zoo Licensing](https://www.rhino3d.com/en/6/new/licensing-and-administration#cloud-zoo) platform. Create an [account ](https://accounts.rhino3d.com/help)if you have not already done so. ![](/files/-MCkERx-G-beDOda58Ar) ### 3. Fetch license Karamba3D will try to fetch the license from the cloud. ![](/files/-MCkERx0DlKLAcaMXVML) If this it the first time installing a license, there will be no license found. Click **Add a License** to add your license. ![](/files/-MCkERx1nSaLLNcx0sdg) ### 4. Add License A new window will open up in your internet browser and you will be asked to which account you wish to add the license to: * use Personal Licenses if installing an individual license for personal use * use [Team Licenses](/1-introduction/1.2-licenses/1.2.1-cloud-licenses#create-a-team) if installing for a company or institution. Team licenses can be shared amongst any group of people. ![](/files/-MCkERx2-W74NnHNwh4R) ### 5. Enter the License Key You will have received an email with the license key. ![](/files/-MCkERx3icNNRIrW0f8w) ### 6. Check License Details Click on **View License Details** to see information about the license. It will display the type of license, the number of seats and the expiration date of the license. ![](/files/-MCkERx4xNvKMOCFJYl8) ### 7. Add License Click **Add License** and the license should be added to your account. ![](/files/-MCkERx5Flva-3othU01) ### 8. Check License Click on the license to check the status of the license ![](/files/-MCkERx6Xr6KVgRBcqDN) ### 10. Fetch License Go back to Rhino3d and click **Try Again** in the Licensing Window ![](/files/-MCkERx7lY80S2cFfl7p) ### 11. License Loaded The license will load and upon successful activation, the license information will be displayed in the Command Line ![](/files/-MCkERx8FQnv0AeQHBN3) ### **12. Check License Status** Open Grasshopper and place the **"License"**-component onto the grasshopper canvas and connect a panel to it. The panel displays the status and expiration of the license. ![](/files/-MCkEQkuRI0lbWN_RIOS) ### 13. Load License upon Startup The license has been successfully installed. Every time you open Rhino, you need to type **Karamba3DGetLicense** to load the license each time. This needs to be done before opening Grasshopper. ### 14. Automate License Load The Karamba3D license can simply be loaded by typing "**Karamba3DGetLicense"** each time Rhino loads, but this process can be automated in the **Tools/Options -> Rhino Options/General**.. Type "**Karamba3DGetLicense"** into the **Command Lists** textbox. The license will then be automatically loaded upon opening Rhino. ![](/files/-MCkERx90gf0DG-JAlmo) {% hint style="danger" %} Make sure to run the "**Karamba3DGetLicense"** command before opening Grasshopper otherwise the license will not be activated. {% endhint %} ## Reactivating License Should Grasshopper be opened when the license has been pulled from the cloud, you can also activate the license by typing "karamba3dgetlicense" in the Command Line in Rhino. Then simply place the "License" component on the grasshopper canvas, and recompute the Grasshopper definition. ## Releasing the License When pulling the license from the cloud for the first time, Rhino temporarily holds the license for a few days for offline use. You can manually release the license by logging out of your Rhino account. This will also release your Rhino license. {% hint style="info" %} To release the license, you will need to logout of your account by typing **"logout"**. {% endhint %} ## **Check License** Restart Rhino and your license should run. Upon successful installation of the license you should be able to open example files which have more than 20 beam elements or 50 shell elements. Double check if the license and correct Karamba3D version are installed by opening the below definition: {% file src="/files/bLul730c7XSCDpet9S2c" %} ## Account administration
### Account Settings You can log into your [Rhino ](https://accounts.rhino3d.com/?controller=home)account to administer licenses and set up teams. We do not have access to your account information. ### Create a Team If you intend to share licenses with a other users, make sure to create a [Team ](https://accounts.rhino3d.com/?controller=groups)and add the licenses to the team. Read more on [McNeel](https://wiki.mcneel.com/rhino_accounts/create_team). ### License Management You can check the [licenses ](https://www.rhino3d.com/licenses?controller=home&_forceEmpty=true)installed on your personal or team accounts. All licenses can be administered here and live-usage can be checked. ### Switch Accounts To switch your license key to a different account, log into your current account, remove the license key and then add it to your new account. ### Add licenses You can add licenses by logging into your cloud account and proceed to the [Add Licenses](https://www.rhino3d.com/licenses/?controller=add_licenses) page. Read more on [McNeel](https://wiki.mcneel.com/rhino_accounts/add_licenses). # 1.2.2 Network Licenses Guide to running Karamba3D with a network license (PRO or LAB users only); also known as LAN Zoo. A network license can only be installed with the **McNeel Zoo 6 (or 7) License** network server (only for Rhino7 or Rhino6). Find out more on [LAN Licenses](https://wiki.mcneel.com/zoo/home) on McNeel. {% hint style="info" %} If you are updating an existing network license, simply skip to the [Upgrade ](#updatelicense)section. {% endhint %} {% hint style="warning" %} For network licenses generated before 18/05/2020 please refer to this [guide](https://manual-1-3.karamba3d.com/1-introduction/1.2-licenses/1.2.2-network-licenses/1.2.2.1-network-license-archived). {% endhint %} ## **Installation on Server End** ### **1. Unblock License Package** Make sure you have Karamba3D [installed](/1-introduction/a.2-installation#standard-installation) and [Zoo6 (or above) ](https://wiki.mcneel.com/zoo/home)License Administrator installed. You will have received a license package upon purchasing the license. Make sure to **unblock** the license package before unpacking it. Right click on the file in Windows Explorer and go to **Properties**. If the file is blocked, there will be an option to **‘Unblock’** the file at the bottom of the Properties Window. You may need to adjust your Administrator or Security settings to be able to unblock the file. ![](/files/-MCkEaQnz31ABEMBZZss) ### **2. Unzip License Package** Unzip the contents of the network license package. It should contain the following files: * *ActivationKey.txt* * Karamba3D\_LicensePlugin\_Zoo6.dll * *README.txt* * *XXX\_License.lic* ![](/files/-MCkEaQpgoVXzeL6mOaw) ### **3. Zoo Administrator** Open the Zoo Administrator. You will need administrator rights to perform this installation. The Zoo Administrator needs to be first stopped before installing the license. Make sure you do not have any existing Kamba3D licenses installed (If you are updating an existing license see [below](/1-introduction/1.2-licenses/1.2.2-network-licenses#remove-existing-licenses)). Click on the **Stop** Icon. ![](/files/-MCkEaQs7GacAz1r6z8t) #### Remove Existing Licenses {% hint style="info" %} If you are updating an existing network license. {% endhint %} Select the Karamba3D license from the list of network licenses. Click the **Delete License** Icon. Make sure all users are not currently using the license otherwise you will not be able to remove them. ![](/files/-MCkEaQuuQRjhtJRJ4UJ) ### **4. Move License Files** Copy the **"Karamba3D\_LicensePlugin\_Zoo6.dll*****"*** *\*\*\_into \_C:\Program Files (x86)\Zoo 6\Plugins* folder.\ This can also be *C:\Program Files (x86)\Zoo 6.0\Plugins* folder. ![](/files/-MCkEaQv-oWfLCeDcWAM) ### **5. Start Zoo Service** Start the Zoo Service in the Zoo Administrator. Click on the **Start** Icon. ![](/files/-MCkEaQwXc4TO8dWi5I2) ### **6. Add License** Click on the **Add Product** **Icon** or select **Add** from the **Edit Menu**. ![](/files/-MCkEaQxSsQXgYSximgm) ### **7. Enter License Key** A window will pop up where you can select *"**Karamba3D\_ZooLicense"*** from the **Product type**. Enter your personal details for Registered owner and organisation. Both entries need to be filled in. The **Product license code** or **CD key** can be found in the **ActivationKey.txt** located in the ZIP package. This should be a **12 digit** code. Click **Add** and the license should now be loaded. ![](/files/-MCkEaQy_ikj2L7enRxi) If the "**Karamba\_ZooLicense"** is not listed in the dropdown menu, close and reopen the Zoo Administrator and check if the file is located in the correct folder. Make sure the Zoo License Server is updated. ### 8. License Loaded The license will be added and you will see the Karamba3D licenses in the list of Products. ![](/files/-MCkEaR0o09Ajz5zPtDQ) ### 9. Check License Status Double click on the license to check the license status. ![](/files/-MCkEaR2n5UGHIsHzdTk) ## Installation on Client End (User) After the license has been installed on the server, you need to install the license file for each user: ### 1. Run Rhino as Administrator Right click and select ***‘Run as Administrator’***. You will need to have administrator rights on your computer. ![](/files/-MCkEaR8Mf-RUkhMGENE) ### **2. Load Grasshopper** Type **"Grasshopper"** in the Command Line to load Grasshopper. ![](/files/-MCkEaR9maaPbg1hpz_3) ### **3. Locate License Component** Place (drag and drop) the **"License"**-component on the grasshopper canvas. This can be found in the Karamba3D tab. ![](/files/-MCkEZNbUIVzzILKXJ-F) ### **4. Load License** Right click on the red “**K**” icon or the **"License"** label. Select **"Load license file"** from the menu. ![](/files/-MCkEZNglWTbOQq4p6by) ### **5. Locate the License File** Locate the ***"XXX\_License.lic"*** that you received in the license package. Click **"Open"** to load the license. ![](/files/-MCkEZNhz4MPMls-Pk9z) ### **6. Load License** The license should be successfully copied. If the license does not load successfully, make sure that you have [unblocked](#id-1.-unblock-license-package) the files as well as opened Rhino as [administrator](/1-introduction/1.2-licenses/1.2.2-network-licenses#1-run-rhino-as-administrator). ![](/files/-MCkEZNiFFHAQCN0HUBf) ### **7. Restart Rhino** Close Rhino and Grasshopper and open Rhino once more, this time in standard mode. ### 8. Fetch the license Type "**Karamba3DGetLicense"** in the Command line ![](/files/-MCkERwzK9x0C9MI88Kq) ### 9. Load Zoo License A window should pop up. Select **"Use the Zoo"**. ![](/files/-MCkEaRCEb-E4m0e0oHj) ### 10. Locate Zoo Server Try to Detect the Zoo automatically. Often, you will need to enter the network name manually. Once the network has been found, click **Continue**. ![](/files/-MCkEaRD1vv5QxcyKDrS) ### 11. License Loaded The license will load from the zoo and the license information will be displayed in the Command Line. ![](/files/-MCkEaREjBAYa2uk2rab) ### **12. Check License Status** Open Grasshopper and place the **"License"**-component onto the canvas and connect a panel to it. The panel displays the status and expiration of the license. ![](/files/-MCkEaRFrdA11f1dLWxd) ### **13. Automate License Load** The Karamba3D license can simply be loaded by typing "**Karamba3DGetLicense"** each time Rhino loads, but this process can be automated in the **Tools/Options -> Rhino Options/General**. Type "**Karamba3DGetLicense"** into the **Command Lists** textbox. The license will then be automatically loaded upon opening Rhino. ![](/files/-MCkEaRGlMaLMFlHdlHN) {% hint style="success" %} Congratulations, the license has been successfully installed and you are free to use the full features of Karamba3D! {% endhint %} {% hint style="info" %} Make sure to run the "**Karamba3DGetLicense"** command opening Grasshopper. {% endhint %} ## **Check License** Upon successful installation of the license you should be able to open example files which have more than 20 beam elements or 50 shell elements. Double check if the license and correct Karamba3D version are installed by opening the below definition: {% file src="/files/GdHb0xfS3LxvCVCyJx1y" %}
## **Perform a remote installation of the Zoo network license** ### Installation on Server End 1. On a test machine, install Karamba3D. 2. Run Rhino and Karamba3D. 3. When prompted for a Karamba3D license, enter the name of your Zoo server. 4. Close Rhino. 5. Open this folder in Explorer: *%allusersprofile%\McNeel\Rhinoceros\6.0\License Manager\Licenses* 6. In this folder you should see at least two .lic files. The '*55500d41-3a41-4474-99b3-684032a4f4df.lic'* file is for Rhino 6. The other ('06bb1e79-5456-47a1-ad6d-111118cd894b.lic') should be for Karamba3D. Note, the file name will make the Id of the Karamba3D plug-in (Tools > Options > Plug-ins) 7. When using the Zoo, the license file is plain text and can be viewed from Notepad. It can also be copied from machine to machine. {% hint style="info" %} Rhino 7 licenses are stored also in the Rhino 6 folder. {% endhint %} ### Installation on Client End So in addition to pushing out the required registry key, required by the Rhino licensing system to find the Zoo, copy the Karamba3D license folder - with the file 'licensePRO.lic' in it - to each machine.\ \ This is typically *C:\Program Files\Rhino 6\Plug-ins\Karamba\License* ![](/files/-MW3VWqRaUvpJ-tp6En3) Open Rhino, use "Karamba3DGetLicense" to request a license, and when prompted, enter your server name or IP address. ## Error Message: The product ID is not correct Should you receive the following error message, check that the licensePRO.lic file has been properly installed, and that you are directing to the correct IP address. ![](/files/-MW3VZgtZBbt1G9gsQbi) # 1.2.3 Temporary Licenses {% hint style="warning" %} ### Get a free trial license on our [website](https://www.karamba3d.com/trial-license/). {% endhint %} ## **Licensing for Workshops/Training** We always encourage the use and exchange of Karamba3D with all users. Therefore we support workshops and training programs with Karamba3D licenses. For workshops within a university for educational purposes, we offer 6 month licenses. For external workshops with professionals we offer 1 month licenses. {% hint style="info" %} Please send us an [email ](mailto:license@karamba3d.com)to inquire about the free workshop licenses. {% endhint %} ## **Licensing for University Courses** We support university courses by providing teachers and students with free 6 month educational licenses for the duration of the semester. We kindly ask that all requests for university licenses be done so by the instructors or professors. {% hint style="info" %} Apply for a [university license](https://karamba3d.com/get-started/university/). {% endhint %} # 1.2.4 Standalone Licenses Guide to running Karamba3D with a standalone license. Standalone licenses are only supported for workshops and universities. ## **Install License File** ### **1. Receive License File** Download the *“**XXX\_License.lic**”* -file and save this license file somewhere on your computer where you can easily find it. This license file will turn your Karamba3D TRIAL installation into ***WORKSHOP*** version ### **2. Unblock License Package** Make sure to **unblock** the license before installing it. Right click on the file in Windows Explorer and go to **Properties**. If the file is blocked, there will be an option to **‘Unblock’** the file at the bottom of the Properties Window. You may need to adjust your Administrator or Security settings to be able to unblock the file. ![](/files/-MCkEZNe2e1rt_Wz-yiA) ### **3. Open Rhino** Make sure you open Rhino as administrator before installing the license (right click and select ***‘Run as Administrator’***). You will need to have administrator rights. ![](/files/-MCkEZNfVkWG5TgiTiR6) ### **4. Load License File** Open Grasshopper and place the **"License"**-component on your Grasshopper canvas. Right-click on the red “**K**” icon or the **"License"** label of the **"License"**-component and select “***Load license file***“. ![](/files/-MCkEZNglWTbOQq4p6by) ### **5. Locate the License File** Locate the ***"XXX\_License.lic"*** that you received in the license package. Click **"Open"** to load the license. ![](/files/-MCkEZNhz4MPMls-Pk9z) ### **6. Load License** The license should be successfully copied. If the license does not load successfully, make sure that you have [unblocked ](#id-2.-unblock-license-package)the files as well as opened Rhino as [administrator](#id-3.-open-rhino). ![](/files/-MCkEZNiFFHAQCN0HUBf) ### **7. Restart Rhino** Close Rhino and Grasshopper and open Rhino once more, this time in standard mode. ### **8. Check License Status** The panel displays the status and expiration date of the license. ![](/files/-MCkEZNjx_2vx-2fD47Z) ## **License Load Error** Errors occur if you do not open Rhino as Administrator or if you do not unblock the file before loading it into Karamba3d. ![](/files/-MCkEZNkCuaDsEJ95QIK) ## **Manual installation in Explorer** Make sure Rhino is closed and that the ***"license.lic"***-file is unblocked. ![](/files/-MCkEZNlp95VqiWRyyBO) Rename the license-file to: ***"license.lic"*** and move (overwrite) it to the License folder of your Karamba3d installation. This can be: *C:\Program Files\Rhino 7\Plug-ins\Karamba or C:\Program Files\Rhino 6\Plug-ins\Karamba.* Renaming the license file to ***"licensePRO.lic"*** ensures that the file is not erased upon installing Karamba3D updates. ![](/files/-MCkEZNmHXDqY9Z4Fzss) ## **Check License** Restart Rhino and your license should run. Upon successful installation of the license you should be able to open example files which have more than 20 beam elements or 50 shell elements. Double check if the license and correct Karamba3D version are installed by opening the below definition: {% file src="/files/GdHb0xfS3LxvCVCyJx1y" %}
# 2 Getting Started If all goes well during installation you will notice upon starting Grasshopper (GH) that there is a new category called Karamba3D on the component panel. It consists of roughly twelve subsections (see fig. 2.1). In case you do not see any icons select **“Draw All Components”** in Grasshopper's **“View”**-menu. The installation can be tested by placing a Karamba3D **“License”**-component on the canvas: it should not issue a warning or error. If not, see section [4.1.3](/troubleshooting/4.3.-miscellaneous-problems/licensing) for how to solve that issue. {% hint style="info" %} On Apple machines make sure to have Microsoft's [.NET Framework 4.5](https://www.microsoft.com/en-us/download/details.aspx?id=30653) in case of Rhino6 and [version 4.8](https://support.microsoft.com/en-us/topic/microsoft-net-framework-4-8-offline-installer-for-windows-9d23f658-3b97-68ab-d013-aa3c3e7495e0) in case of Rhino7. {% endhint %}

Fig. 2.1: Category “Karamba3D” on the component panel

These are the subsections which show up in the Karamba3D category: | Tab | Function | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | License | The **“License”-**component contained in here delivers information regarding the current type of license and how to get a pro-version of Karamba3D | | Params | containers for Karamba3D objects like beams, loads, models, . . | | 1.Model | lets you create a basic models with default settings for cross sections and materials | | 2.Load | components for defining external forces | | 3.Cross Section | contains components to create and select cross sections for elements. | | 4.Joint | for defining joints on beams and shells. | | 5.Materials | components for the definition and selection of materials | | 6.Algorithms | components for analyzing the structural model | | 7.Results | for the retrieval of calculation results | | 8.Export | for exporting Karamba3D-models to RStab or Robot via DStV-file | | 9.Utilities | contains some extra geometric functionality that makes it easier to handle and optimize models | | x1.ParamUI | components for controlling the display of models via parameter-input only | {% hint style="info" %} The colors of Karamba3D’s icons have a special meaning: black or white designates the entity or entities on which a component acts. Products of components get referenced by a blue symbol. {% endhint %} Karamba3D adds a section in the Grasshopper menu (see fig. 2.2.). There it is possible to * set the basic physical units and whether to work in Imperial or SI Units, * optimize the visibility of Karamba3D components in the toolbar, * set the language of the user interface, * edit the initial settings file and * get help

Fig 2.2.: Section "Karamba3D" in the Grasshopper menu.

# 2.1 Karamba3D Entities Grasshopper (GH) is an object oriented, visual scripting environment. It provides items like points, curves, surfaces, . . . for geometric computing. The full range of geometric items can be inspected in the subcategory **“Geometry”** of the toolbar section **“Params”**. Karamba3D adds eight entities for building structural models: | Entity | Typology | | ------------- | --------------------------------------------------------------------------------------- | | Model | contains all the information related to a structure | | Element | can be a beam, truss, shell or spring | | Element Set | groups together elements in a given order, makes them accessible under a common name | | Joint | defines the connectivity between neighboring elements | | Load | external action which is imposed on the structure | | Cross-section | defines a structural element’s geometry in section | | Material | provides information regarding the physical behavior of what a cross section is made of | | Support | defines how a structure connects to the ground. | Karamba3D objects behave like GH entities. * They can be stored in containers (see the **“Params”** subcategory of the **“Karamba3D”** toolbar). * When converted into text by plugging them into a panel they provide textual output regarding their fundamental properties. ## Default Settings In order to build a structural model not all of the above entities need to be present. Karamba3D assumes default settings for materials and cross sections: * If no material is given, Karamba3D chooses steel (S235 according to EC3 with$$f\_{yk} = 23.5 kN/cm^2$$) for all cross sections. * For beams the default is a circular hollow cross sections (CHS) with an outer diameter of$$114.4mm$$and a wall thickness of $$4mm$$. The default thickness of shells amounts to $$10mm$$. ## Graphical User Interface Some Karamba3D components come with graphical user interface components like radio-buttons, drop-down lists and sub-menus. Sliders on Karamba3D components have a preset number-range. Double-click on the knob to change the precision and range to your specific need. In some cases the user can select between different options at a component input (e.g. the Load-Case at a result component, or the degrees of freedom at a support-component). To select these options via ValueList-components right-click on the Karamba3D-component and select "**Expand ValueLists**" from the context menu or plug a ValueList into the corresponding input-plug. The selection of dynamic content that depends on the upstream model (e.g. selection of load-cases) works only after the component executed at least once. So one needs to connect the mandatory input-plugs before expanding dynamic value-lists. The ModelView-, BeamView- and ShellView-components provide a short-cut for selecting color-ranges for result display: Right-click on the components and select 'Colors' from the context menu. # 2.2 Setting up a Structural Analysis A simple structural analysis can be performed in Karamba3D in eight steps: 1. [Define the Model Elements](/2-getting-started/2-getting-started-1/setting-up-a-structural-analysis/2.2.1-define-the-model-elements) 2. [View the Model](/2-getting-started/2-getting-started-1/setting-up-a-structural-analysis/2.2.2-view-the-model) 3. [Add Supports](/2-getting-started/2-getting-started-1/setting-up-a-structural-analysis/2.2.3-add-supports) 4. [Define Loads](/2-getting-started/2-getting-started-1/setting-up-a-structural-analysis/2.2.4-define-loads) 5. [Choose an Algorithm ](/2-getting-started/2-getting-started-1/setting-up-a-structural-analysis/2.2.5-choose-an-algorithm) 6. [Provide Cross Sections](/2-getting-started/2-getting-started-1/setting-up-a-structural-analysis/2.2.6-provide-cross-sections) 7. [Specify Materials ](/2-getting-started/2-getting-started-1/setting-up-a-structural-analysis/2.2.7-specify-materials) 8. [Retrieve Results](/2-getting-started/2-getting-started-1/setting-up-a-structural-analysis/2.2.8-retrieve-results) # 2.2.1 Define the Model Elements In Karamba3D, straight lines form the basis for beam, truss, and spring elements, while shells and slabs are based on meshes. Figure 2.2.1.1 illustrates a definition that creates a single beam, assembles a model, and displays it. The **“Create Linear Element”** component, in its LineToBeam variant, takes a **“Line”** object as input and generates a beam element from it. By default, Karamba3D assumes all geometry input is in meters, disregarding the unit settings chosen in Rhino. Assigning names to elements is beneficial when working with large, complex structures. In Figure 2.2.1.1, the name “MyBeam” is assigned to the new beam element. For grouping elements, it can be useful to give them multiple names at once. This can be achieved by separating the alternative names with "|" which stands for "or". {% hint style="info" %} Element identifiers do not need to be unique, allowing for the grouping of elements. {% endhint %}

Fig. 2.2.1.1: A structural model with geometry only

The **“Assemble”** component consolidates all structural information into a model. When connected to a panel, the model displays its basic features: **“c.Length”** represents the characteristic length, calculated as the diagonal of the bounding box of the structure. For a beam, two nodes define one element. In the absence of material definitions, Karamba3D automatically generates a default material, applied to the default beam and shell cross-section, resulting in two cross-sections as shown in Figure 2.2.1.1. The model does not contain loads but includes a default load-case. {% hint style="info" %} A load-case represents a scenario where a group of external actions simultaneously impact a model. For instance, wind can affect a structure from multiple directions, but not all directions at once. Each distinct wind direction is treated as a separate load-case. {% endhint %} # 2.2.2 View the Model There are four components for controlling how a model is displayed in the Rhino viewport: | Component | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | **“ModelView”** | Sets the general display properties, which are stored in the model and remain valid until overwritten by a downstream **“ModelView”** component. | | **“BeamView”** | Controls the display properties specific to beams, such as rendering the cross-section as a mesh. | | **“ShellView”** | Contains the display settings for shells. | | **"ReactionView"** | Provides refined means for displaying reaction forces at supports. | Figure 2.2.2.1 demonstrates how the **“ModelView”** and **“BeamView”** components can be combined to render the beam model. To expand the viewing components, click on the black section headings on the components. In the **“Tags”** section of **“ModelView”**, the **“Elements”** checkbox is enabled by default, displaying the element's middle axis. Activating the **“Node numbers”** option will display the node numbers. Nodes in a Karamba3D model are numbered starting from zero, as are model elements. Displaying their identifiers via **“Element tags”** can be useful in certain situations.

Fig. 2.2.2.1: “ModelView”- and “BeamView”-components are used to display a model

When more than one element is present, the **“Assemble”** component rigidly connects them if their nodes coincide. If the geometry is imprecise, this can result in unexpected outcomes: elements may appear connected, but small gaps between nodes can exist. These gaps can significantly affect the model's physical behavior. Displaying node indexes can help identify such gaps, as two node numbers will appear in the same location. # 2.2.3 Add Supports Supports define how a structure connects to the ground by suppressing translations or rotations at nodes. In the **“Support”** component, an activated button appears black, indicating zero translation (T) in the direction of the global x-, y-, or z-axis, or zero rotation (R) about the corresponding global axis (or local axis if a plane is input). A node index or position can be used to specify the location of a support. To specify locally oriented support conditions, supply a plane as input. {% hint style="info" %} Green arrows symbolize translational supports, while purple circles represent rotational supports (see Fig. 2.2.3.1). {% endhint %}

Fig. 2.2.3.1: Supports specify how a structure interacts with the ground.

For static analysis, a structure must be supported to prevent it from moving freely. In three-dimensional space, a rigid body has six modes of movement or degrees of freedom (DOFs): three translations and three rotations (see Fig. 2.2.3.2). Therefore, a structural model requires at least six support conditions to be fixed. If a model or parts of it are moveable, the **“Analyze”** component will either refuse to calculate or return large displacements. If this issue arises, connect your model to the **“Eigen Modes”** component to detect the rigid body movements causing the problem. ![ Fig. 2.2.3.2: A body in space has six degrees of freedom (DOFs).](/files/-MCkERBi-R4LXw9qywEI) Supports can only be defined at structure nodes. If a support position is not set on a node, the **“Assemble Model”** component will issue an error. The error message will contain the coordinates of the support that does not attach to the model. To get an overview of the faulty model, deactivate the **“Support”** component and use the **“ModelView”** component to visually inspect the model. # 2.2.4 Define Loads

Fig. 2.2.4.1: A cantilever with a point-load at its tip

In fig. 2.2.4.1 a point-load of 1 kilo Newton ($$kN$$) is added at the tip of the cantilever beam. A vector at the input-plug **“Force”** specifies direction and magnitude of the load: since the global Z-axis points upwards a load acting downwards has a negative z-component. {% hint style="info" %} The input plug **“LCase”** can be used to set the name of the load case in which the load acts. This allows different load scenarios (e.g., wind from different directions) to be created and combined later on. {% endhint %}

Fig. 2.2.4.2: Definitions of different load types

The dropdown lists at the bottom of the **“Loads”** component allows selection between different types of loads as shown in Figure 2.2.4.2: * **Gravity Loads:** Act on the entire structure. * **Point Loads:** Concentrated load; Location can be specified by node index or position. * **Initial Strain:** Imposes an initial change of geometry on structural elements. * **Temperature:** Via the coefficient of thermal expansion (see section [3.5.1](/3-in-depth-component-reference/3.4-material/3.4.1-material-properties)) temperature changes are linked to axial or in-plane strains. * **Distributed Loads on Meshes:** They get reduced to approximately statically equivalent node and beam loads. There exist two variants: "MeshLoad Const" which defines a uniform surface load and "MeshLoad Var" where pressures can be defined for each mesh-face individually. The directions of gravity and point loads refer to the global coordinate system. The direction vector of beam and mesh loads can be specified relative to the global or local coordinate system (related to the element or mesh). Point-loads can only be defined at structure nodes. If a Point-load position is not set on a node, the **“Assemble Model”** component will issue an error. The error message will contain the coordinates of the point load that does not attach to the model. To get an overview of the faulty model, deactivate the corresponding "Load" component and use the **“ModelView”** component to visually inspect the model. Besides the above loads which apply irrespective of the type of loaded element, the component **"Beam Loads"** can be used to define loads specific to beams (see section [3.2.2](/3-in-depth-component-reference/3.2-load/3.2.2-beam-loads)).
# 2.2.5 Choose an Algorithm

Fig. 2.2.5.1: Deflection and stress-strength ratio of a cantilever beam with a point-load at its tip

Karamba3D provides various options for analyzing a structural model. The **“Analyze”** component (see Fig. 2.2.5.1) calculates the deformation and stresses of a model under external loads. The **“Deformation”** slider in the **“Display Scales”** submenu of the **“ModelView”** component allows scaling the graphical output of the displacements. The default magnification factor is 50, but this can be adjusted if the numeric range of the **“Deformation”** slider does not fit. {% hint style="info" %} Double-clicking the knob of the slider opens a window for adjusting the slider settings. {% endhint %} To obtain the numerical values corresponding to the colors of the utilization output, use the **“Legend”** component as shown in Fig. 2.2.5.1. The stress-wise utilization output of the **“BeamView”** component is calculated by dividing the normal stress at a point of the cantilever by the strength of its material. Negative values indicate compression, while positive values indicate tension. However, stress-wise utilization can be misleading. Slender beams under axial compression may buckle and collapse before the compressive stresses reach the material strength. In such cases, use the **“Utilization”** component, which includes stability considerations. # 2.2.6 Provide Cross Sections There are two methods for attaching cross sections to elements: 1. **Direct Assignment:** Directly at the component where the element is created, as shown in Fig. 2.2.6.1. 2. **Assignment via Names or Regular Expressions:** Using element names (“B” and “S” in Fig. 2.2.6.2) or regular expressions by plugging cross sections into the **“Assemble”** component.

Fig. 2.2.6.1: Definition of a cross section.

Figure 2.2.6.1 illustrates how to attach a custom cross section to an element. The example shows an I-profile with a height and width of 50 cm. The physical unit of any input or output value is indicated in the help text that appears when hovering over the corresponding plug. {% hint style="info" %} Assignment via the **“Assemble”**-component overrides direct assignment at the element. {% endhint %} ![ Fig. 2.2.6.2: Definition of a cross section via element names.](/files/-MCkEZqa5h3AZAiNTQu1) Figure 2.2.6.2 shows how cross sections can be attached to elements via their names **“Elem|Id”**: 1. Definition of a beam cross section. 2. Definition of a shell cross section. 3. Selection of a cross section from the default cross section library. An element's index can be used as its default name. Arbitrary I-, hollow box, filled trapezoid, and hollow circular cross sections can be defined for beams. Alternatively, Karamba3D allows users to select a predefined standard cross section. For shells, it is possible to attach a different cross section to each element. Karamba3D cross sections are available as multi-components and can be accessed via the single **“Cross Sections”** component. The drop-down menu allows for the selection of the cross section type. {% hint style="info" %} Should you not assign a cross section to your beam or shell elements, the [default cross section ](/2-getting-started/2-getting-started-1/karamba3d-entities#default-settings)will be used. {% endhint %} # 2.2.7 Specify Materials Materials can be defined either by manually setting their mechanical properties or by selecting from a library of predefined materials (see Fig. 2.2.7.1, item 3). Materials attach to cross-sections. There are two options for assigning materials: ![Fig. 2.2.7.1: Definition of materials via element names.](/files/-MCkEYvJX8NkirenlCf3) * **Assignment via the “Assemble” Component:** Use the **“Elem|Id”** input plug to specify the names of the elements to which the material should be attached. Alternatively, a regular expression can be used to select elements. Leaving **“Elem|Id”** empty sets the material for all elements. Materials are not attached directly to elements but to the element’s cross-section. * **Direct Input at the “Cross Section” Component:** As shown in Fig. 2.2.7.2.

Fig. 2.2.7.2: Definition of a material directly at the "Element" component.

Figure 2.2.7.1 illustrates how materials can be defined by element names **“Elem|Id”**: 1. Definition of an isotropic custom material. 2. Definition of an orthotropic custom material. 3. Selection of a material from the material library. {% hint style="info" %} Assignment via the **“Assemble”**-component overrides direct assignment in the cross section. {% endhint %} {% hint style="info" %} Should you not assign a material to your beam or shell elements, the [default material ](/2-getting-started/2-getting-started-1/karamba3d-entities#default-settings)will be used. {% endhint %} # 2.2.8 Retrieve Results ## Visualization

Fig. 2.2.8.1: Three components for visualizing the model: “ModelView”, "ReactionView", “BeamView” and “ShellView”.

Karamba3D offers four components for visualizing a structural model (see fig. 2.2.8.1): | Component | Description | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | | **“ModelView”** | Sets the basic visualization properties such as the scaling factor of displacements, sizes of symbols, and number of displayed load cases. | | **“BeamView”** | Visualizes beams. | | **“ShellView”** | Visualizes shells. | | **"ReactionView"** | Provides enhanced options for visualizing reaction forces at supports. | Each component contains submenus that can be expanded by clicking on the black caption bar. The numerical range of sliders can be adjusted by double-clicking on their black knob. Visualization properties persist with the model until overridden by another downstream visualization component. ## **Results** Structural response properties can be used to inform and optimize the model. Figure 2.2.8.2 illustrates some of the available options: 1. Nodal displacements. 2. Level of material utilization. 3. Cross section forces. 4. Reaction forces.

Fig. 2.2.8.2: Retrieval of numerical results.

## **Disassembling a Structural Model** To modify a model or retrieve details such as cross section types after optimization, Karamba3D allows for the disassembly of models, elements, cross sections, and materials. The components **“Disassemble Model”**, **“Disassemble Element”**, **“Disassemble Cross Section”**, and **“Disassemble Material”** enable detailed dissection of a structural model (see Fig. 2.2.8.3).

Fig. 2.2.8.3: Data retrieval from a model via a cascade of "Disassemble" components.

# 2.3 The Karamba3D Menu Karamba3D integrates a menu entry into the Grasshopper menu bar.

Fig. 2.3.1: Karamba3D menu entry integrated into the Grasshopper menu.

The Karamba3D menu includes the following options: * **Physical Units:** Allows setting the unit system and the length unit for geometry input. When set via the menu, these settings are stored in the Grasshopper definition, overriding individual user settings upon document opening. The definition needs to be recomputed for units changes to take effect. * **Components:** this menu item opens three options: * **View parametric UI:** Toggles visibility of components that can be used to parametrically control how a model gets rendered. * **View WIP Components:** Toggles visibility of work-in-progress (WIP) components. * **Update Obsolete Components:** Replaces outdated Karamba3D components (thjose which are marked by an 'Old' badge)with their updated versions. This applies to components deprecated in version 3.1.51222 and later. * **Settings:** For modification of initial settings used in Karamba3D. See section [2.4](/2-getting-started/2-getting-started-1/2.4-user-settings) for details on how user settings are organized on Karamba3D. * **Set Language for Components:** Selects the language for user interface text. * **Async Execution:** Enable and Disables asynchronous execution of Karamba3D components (see section [2.6 Asynchronous Execution of Karamba3D Components](/2-getting-started/2-getting-started-1/2.6-asynchronous-execution-of-karamba3d-components) for details). * **Legend Number Format Digits:** Provides a quick way for changing the number of decimal places displayed via legends at the BeamView-, ShellView- or ReactionView-components. * **Edit User Settings (show everything):** Opens the default text editor with a temporary copy of the karamba.ini user settings. Save changes via the editor's "save" button to avoid loss. Upon exit, a message box displays user changes. * **Edit User Settings (show overwrites only):** Displays only lines differing from global karamba.ini settings. * **Show Path to File with User Settings:** Shows the path to user karamba.ini settings, typically located under "%appdata%\Karamba". * **Show Document-specific Values:** The unit system (SI vs. Imperial) and length unit settings are stored within the Grasshopper file (see [2.5 Physical Units](/2-getting-started/2-getting-started-1/2.3-physical-units)). This menu option allows you to view the settings associated with the current GH document. * **Clear Settings inside Document:** Removes all document-specific configurations. After clearing, the unit system and length units will be taken from the local user or global settings (see [2.4 User Settings](/2-getting-started/2-getting-started-1/2.4-user-settings)). * **Help:** Provides access to help resources: * **Docs:** Opens the documentation in the default browser. * **Examples:** Offers a choice between opening the examples webpage on Karamba3D.com or the local examples folder. * **Tutorials:** Directs to the tutorials webpage of Karamba3D.com * **API Documentation:** Opens the Karamba3D API documentation. # 2.4 User Settings User setting allow customization of various aspects of Karamba3D: * System of physical units ("SI" or "Imperial"). * Limit distance for snapping together neighboring nodes. * The value of the acceleration of gravity. * Limit inclination for verticality. * Number format and display properties of output values. * Properties of the default materials. * Colors used for displaying rendered calculation results. * ... User settings in Karamba3D are primarily managed through text files named "karamba.ini". These files contain comments, indicated by "#", and variable assignments (see Fig. 2.4.1). Assigning "auto" or "default" to a variable will apply the default values. The shortcut for editing "karamba.ini" user settings is via the Karamba3D menu: **Settings > Edit User Settings**.

Fig. 2.4.1: Snippet from a "karamba.ini" file.

To ensure a flexible and transparent user preference system, Karamba3D employs a multi-step approach for reading settings data, with each step potentially overriding the settings from the previous one: 1. **Default Values:** Lowest priority, hard-coded within Karamba3D. 2. **Installation Folder "karamba.ini":** The "karamba.ini" file located in Karamba3D's installation directory. 3. **Installation Folder "karamba\_user.ini":** If present, the "karamba\_user.ini" file in the installation folder is read next. 4. **User Directory "karamba.ini":** The "karamba.ini" file located in "%appdata%\Karamba" follows. 5. **Grasshopper Document Units:** The unit system (either "SI" or "Imperial") is stored directly in the Grasshopper document. When first saving a new definition unit system and length unit are set according to the user preferences in the "karamba.ini"-files. By default this is "auto" for the unit length and either "SI" or "Imperial" for the units system. Choices set via the Karamba3D menu "Settings"-option overrides these values. # 2.5 Physical Units Karamba3D utilizes two sets of physical units: * **Internal Calculation and Geometry Input:** Units used for internal calculations and reading geometry. * **Component Input and Output:** Units used for the input and output of Karamba3D components. These units can be set independently of each other. Changing units via the Karamba3D menu necessitates a recompute of the definition for the updated units-settings to take effect. Upon installation via the msi-installer, users can specify the family of physical units for input and results. The default option is metric (e.g., meters, centimeters, degrees Celsius, Newtons), but Karamba3D also supports Imperial units (e.g., feet, inches, degrees Fahrenheit, kilopounds). {% hint style="info" %} The units can be changed anytime via the Grasshopper/Karamba3D menu or by editing the “karamba.ini” file (see section [2.3](/2-getting-started/2-getting-started-1/2.4-user-settings)) {% endhint %} Depending on the selected unit family, Karamba3D interprets geometric input as meters or feet by default. The expected physical units for components are displayed in the tooltip that appears when hovering over an input plug. Karamba3D includes databases for predefined cross-sections and materials, with properties specified in SI units. This also applies to physical constants (e.g., "gravity") defined in the **“karamba.ini”** file. Throughout this manual, SI units will be used exclusively for consistency. Any specific differences between using Karamba3D with Imperial and SI units will be mentioned as necessary. ## How to set Unit Preferences For extremely small or large models, default physical units may be impractical. The most convenient way of setting the length-unit for reading in geometry is via the Karamba3D Grasshopper menu under "Physical Units/Geometry Input Units". This sets the basic length unit of the current user and of the the current Grasshopper document. In order to enable the exchange of Karamba3D models between users whose user settings with regards to geometry units and units system (SI or Imperial) are different, these two settings are stored inside of the GH file - see section [2.4 User Settings](/2-getting-started/2-getting-started-1/2.4-user-settings) for details. See section [2.4 User Settings](/2-getting-started/2-getting-started-1/2.4-user-settings) for details. The "karamba.ini" file contains parameters to change the basic physical units used for internal calculations and geometry input from Rhino: "**UnitLength**", "**UnitForce**", and "**UnitMass**" (see Fig. 2.4.1). Possible values for these unit identifiers are listed as comments in the "karamba.ini" file. All input and output values will be converted to and from these units. Units can be mixed, but avoid using both Imperial and SI units simultaneously. When base units are set to "auto" or "default," the unit system determines the default values. ![Fig. 2.4.1: Snippet of the "karamba.ini" file showing basic physical unit settings.](/files/-MgyhAcEHJeLhMWgZxw_) The basic physical units are for internal bookkeeping and geometry input from Rhino. To change the physical units for input and output, use the "CustomUnits" parameter in "karamba.ini" (see Fig. 2.4.2). This parameter expects a list of comma-separated terms in the format "'original unit'>'custom unit'". If an empty list is provided, the default units apply. These new units apply to all Karamba3D components, and you are free to mix SI and Imperial units as needed. To define units for area loads, line loads, line moments, point loads, point moments, material stress, and specific weight, use the following identifiers on the left side of the unit definition: **"AreaLoad"**, **"LineLoad"**, **"LineMoment"**, **"PointLoad"**, **"PointMoment"**, **"MaterialStress"**, and **"SpecificWeight"**. {% hint style="info" %} In version 3.1.60519, the identifiers **"PointLoad"** and **"PointMoment"** are used not only for loads but also for support reactions. In later versions, separate identifiers—**"ReactionForce"** and **"ReactionMoment"**—will be available for defining support reaction units. {% endhint %} ![Fig. 2.4.2: Definition of custom physical units for input and ouput.](/files/-MgyktT_2upx-vKWp_VX) # 2.6 Asynchronous Execution of Karamba3D Components Asynchronous (Async) execution in Grasshopper refers to the ability of components to process data independently and concurrently without blocking the main computational thread. In the traditional, synchronous execution model of Grasshopper, each component computes its outputs sequentially, requiring all upstream components to complete their computations before downstream components can begin. This can result in delays and inefficiencies, particularly when dealing with computationally intensive tasks. In Karamba3D, asynchronous execution can be toggled via the **Karamba3D menu** under **"Settings > Async Execution"**. By default, this option is disabled. Karamba3D's asynchronous components leverage the [`GrasshopperAsyncComponent`](https://github.com/specklesystems/GrasshopperAsyncComponent) framework, developed by [Speckle Systems](https://www.speckle.systems/). This architecture divides the execution process of async components into two distinct stages: * **Data Acquisition**\ During this initial stage, no new computed data is output, which creates challenges for components that iteratively process portions of a Grasshopper definition, such as Galapagos. This limitation makes it necessary to disable async execution for Karamba3D components during looping or optimization runs. * **Data Processing**\ Once the required data is acquired, processing occurs independently, allowing for improved performance in certain contexts. {% hint style="info" %} **Disable async-execution when doing optimization runs (e.g. with Galapagos) or looping.** {% endhint %} #### Async-Capable Components in Karamba3D The following components in Karamba3D support asynchronous execution: * **AssembleModel** * All **Algorithms** components * **ModelView**, **BeamView**, and **ShellView** * **LineResultsOnShells** * **MeshBreps** * **Shell Section** #### Features and Considerations Async components in Karamba3D introduce key enhancements and options: * **Improved Responsiveness**\ Async components run parallel to the UI thread, preventing the interface from freezing during computation. * **Context Menu Options**\ Async-capable components include two additional entries in their context menu: * **Cancel**: Halts the component's execution while it is running. * **Parallel Execution**: Allows the component to process incoming data in parallel. #### Caution on Parallel Execution While parallel execution may enhance performance, Karamba3D's algorithms are already highly optimized for parallel processing. Activating an additional layer of parallelism via "Parallel Execution" in the context menu could result in **over-parallelization**, potentially causing performance degradation rather than improvement. Users are advised to enable this feature judiciously based on specific computational needs. # 2.7 Naming and Selection of Elements Attaching properties to elements, querrying element results or controlling partial model visibility via the ModelView-component depends on element identifiers (Ids). A nifty naming scheme makes it easier to manage complex models by grouping elements into logical parts and hierarchies. ## Definition of Element Names Element names are assigned during creation using the **Create Linear Element** or **Create Surface Element** components. They can later be modified with the **ModifyElement** component. Valid names must start with a letter and may include letters, numbers, or underscores (`_`). Pure numeric names are not allowed because each element already has a default name based on its index in the model. Another default name is the empty string `""`, which means that using `""` as a selection string will select all elements in the model.

Fig 2.7.1: Hierarchical naming scheme for elements.

#### Multiple Names Elements can have multiple names (e.g., their index plus user-defined names). To assign multiple names, separate them with vertical bars:\ `name1|name2|name3`\ This attaches the names `name1`, `name2`, and `name3` to the element. {% hint style="info" %} Since element names needn't be unique multiple names on an elements may be used to categorize the latter: e.g. according to length ranges, cross section properties, joint-conditions,...\ These categories can then be conveniently visualized using a ModelView-component's "View"-input (see section [3.7.1.1 ModelView](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.6.1-modelview)). {% endhint %} #### Hierarchical Naming Schemes A hierarchical naming scheme can be created using dot notation:\ `Level1.Level2.Level3`\ Such an element can be selected using `Level1`, `Level1.Level2`, or `Level1.Level2.Level3`. This is equivalent to the shorthand:\ `Level1|Level1.Level2|Level1.Level2.Level3`. Figure 2.7.1 shows a model with four beam elements where hierarchical naming was used to apply beam loads to different parts of the model. ## Selection of Elements by Name When attaching loads, assigning cross sections, or controlling model visibility in Karamba3D, elements are typically referenced by their **name**. In some cases, you can also provide the element object directly, in which case its **GUID** is used during the model assembly process. Element naming is case sensitive in Karamba3D. **Element naming is case-sensitive** in Karamba3D. Each element has two default names: * An empty string * Its element index (which can be visualized in the *ModelView* component).\ Element indexes correspond to the order in which elements were fed into the *AssembleModel* component. You can reference elements by their IDs in three ways: 1. **Direct name**: Supply the full element name. 2. **Wildcard selection**: Use `*` or `&` in the selection string. For example, `abc*` selects all elements whose name starts with `abc` followed by any characters. 3. **Regular expressions**: Start with `&` and follow C# regex rules. For example, `&^abc\d{3}$` matches names starting with `abc` followed by exactly three digits.\ If you’re new to regex, large language models can help you compose them. For **shell and membrane elements**, the term “element” refers to patches of finite surface elements. Their internal order corresponds to the mesh face order of the original mesh. To reference a single finite element for display, append `/` and the index to the element name (e.g., `abc/0` refers to the first finite element within structure element `abc`).\ See the example file *OptiCroSec\_Shell\_Large.gh* for details. ## Selection of Elements via Component There is the "Select Elements"-component for selecting elements based on their properties. For details see [here](/3-in-depth-component-reference/3.1-model/3.1.16-select-elements). ## Selection of Elements based on Geometry The visibility of model elements can be controlled through the *“View”* input of the *ModelView* component. All previously described selection techniques are applicable here. In addition, geometric inputs such as Breps, planes, surfaces, and base lines can be used. * **Breps:** Elements are displayed if their endpoints lie within the Brep. * **Planes and Surfaces:** Elements are shown if they lie on the respective plane or surface. * **Base lines:** These define vertical planes that are used to determine element visibility. If multiple selection criteria are provided to the *“View”* input, an **OR condition** is applied, meaning an element is visible if it satisfies at least one of the given criteria. {% file src="/files/xKG2sXfGk6ieeodpgynl" %} {% file src="/files/bCIVdbr3quPWq3QJG3ns" %} # 2.8 Quick Component Reference ## License | | | | | -------------------------------- | ----------- | -------------------------------------------------------------------------------------------- | | ![](/files/0JMLm9UeFrpsfjIWFMqS) | **License** | Returns the program version, license information and can be used to manage the license file. | ## Params Karamba3D introduces seven new classes for defining structural models and corresponding containers:
Cross-sectionContainer for cross section objects
ElementContainer for finite elements
Element SetContainer for ordered groups of elements
JointContainer for connectivity conditions between elements
LoadContainer for load objects
MaterialContainer for materials
ModelContainer for models
SupportContainer for supports
## Model This subcategory contains components for assembling a model, converting geometry into finite elements and defining support conditions.
Assemble ModelCreates a finite element model by collecting given entities (points, beams, shells, supports, loads, cross sections, materials, . . . ).
Disassemble ModelDecomposes a model into its components.
Modify ModelChanges the model's nodal positions.
Activate ElementActivates the elements of a model according to the activation list. Uses the soft kill approach for inactive elements.
Create Linear ElementMulti-component for creates beams and truss elements with default properties from given lines, node indices or connectivity diagrams.
  • Line To Beam
Creates elements from given lines.
  • Line To Truss
Creates a truss element from a given line which carries axial loads only.
  • Index To Beam
Creates beam elements base on the indexes of their end-points.
  • Connectivity to Beam
Uses a connectivity diagram to create beam elements.
Mesh to ShellCreates shells with default properties from given meshes. Quad faces are split to triangles.
Modify ElementMulti-component for modifying elements. Works either directly on an element or indirectly as an autonomous agent:
  • Modify Beam (default)
Modifies beams only
  • Modify Shell
Modifies shells only
Disassemble ElementDecomposes elements into their components.
Orientate ElemDecomposes elements into their components:
  • Beam (default)
Sets the local Z-axis of beams according to a given vector and adds a rotation angle DAlpha about the longitudinal axis. Flips beam direction according to a given x-vector.
  • Shell
Sets the local X- and Z-orientation using global coordinates.
Connected PartsReturns groups of interconnected lines of the model.
Make Beam-SetPuts beams designated by their beam identifier into a group.
Dispatch ElementsSelects elements according to a given identifier and puts all incoming elements in two groups: selected or rejected. The identifier may be the element index, name or a regular expression.
Select ElementsSelects elements of a model based on their identifier, colour, cross section, material, length or element type.
Point-MassAttaches a point mass to a node of given index or position. Does not result in additional weight, only translational inertia.
SupportCreates supports at nodes of given node-indexes or node-coordinates. Lets you select translations/rotations which should be zero and the support orientation with respect to the global or a local coordinate system.
## Load The components in this subcategory let one define and manipulate external actions which impact a structure.
LoadsMulti-component for defining loads:
  • Gravity (default)
Creates gravity from a specified direction vector for given load-cases.
  • Point-Load
Creates point loads at points of given index or position.
  • Initial Strain-Load
Sets initial axial strains on beams.
  • Temperature-Load
Imposes a temperature difference on an element with respect to its initial temperature at construction.
  • MeshLoad Const
Creates approximately equivalent point- and line-loads from a constant surface load on a mesh. The constant surface load is defined by one vector.
  • MeshLoad Var
Creates approximately equivalent point- and line-loads from a variable surface load on a mesh. The variable surface load is defined by one vector for each mesh face. The longest list principle applies when the mesh-faces outnumber the load-vectors.
Beam LoadMulti-component for specifying loads which act on beams and trusses
  • Concentrate Point Load
Places a concentrated force- or moment-load on a point along the element axis.
  • Block Load
Uniformly distributed force- or moment-load within an arbitrarily placed interval along the element axis.
  • Gap Load
Imposes a displacement or rotation discontinuity at a given position along the element.
  • Imperfection-Load
Defines imperfections for beams under normal forces.
  • Polylinear Load
Places a poly linear distributed load on an element.
  • Trapezoidal Load
Sets a trapezoidal distributed load on a given interval of the element axis.
Disassemble Mesh LoadSplits a mesh-load into corresponding line- and point-loads
Prescribed DisplacementPrescribes displacements at nodes of given node-indexes or node-coordinates. Select translations or rotations which should be prescribed. For load-cases with no displacements prescribed this will create a support.
Disassemble Load-Case-CombinationOutputs the formula texts, names and factors of the load-cases a load-case-combination contains.
Load-Case-Combination SettingsSpecifies the calculation parameters (e.g. Th.I or Th.II) to be used for analyzing a load-case-combination.
Load-Case-CombinatorCreates load-case-combinations based on existing load-cases and provided combination rules (e.g. "ULS=1.35*G+1.50*Q")
## Cross Section
Cross SectionsMulti-component for creating cross sections:
  • Box-Profile (default)
Creates rectangular, trapezoid and triangular hollow cross sections.
  • Circular Hollow Profile
Creates circular hollow cross sections.
  • I-Profile
Creates I-shaped cross sections.
  • Shell Const
Lets you set the height and material of a shell with constant cross section.
  • Shell Var
Lets you set the height and material of each face of a shell.
  • ShellRC Std Const
A standard reinforced concrete cross section consists of four layers of orthogonal reinforcement. This component allows to define such a cross section which is constant throughout a shell.
  • ShellRC Std Var
Same as above, lets one set the reinforced concrete cross section properties for each shell face separately.
  • Spring-Cross Section
Defines the spring stiffness of an element.
  • Trapezoid-Profile
Creates filled rectangular, trapezoid and triangular cross sections.
Disassemble Cross Section Retrieves properties of a cross section.
Beam-Joint AgentCrawls around in the model and adds joints to beams on the basis of geometric relations. Is of type cross section.
Beam-JointsAdds hinges at the end-points of beams. Is of type cross sections.
Eccentricity on BeamSets the eccentricity of a cross section relative to the element axis in global coordinates.
Eccentricity on Cross SectionSets the eccentricity of a cross section relative to the element axis in local beam coordinates.
Modify Cross SectionMulti-component for modifying cross sections. Works either directly on a cross section object or indirectly as an autonomous agent:
  • Modify Beam Cross Section
Modifies beam cross sections only.
  • Modify Shell Cross Section
Modifies shell cross sections only.
Cross Section Range SelectorLets you select cross sections by country, shape, family or maximum depth or width.
Cross Section MatcherReturns for a cross section the best fitting cross section contained in a given list. The matched cross section is equal or better in all mechanical aspects at minimum weight.
Cross Section SelectorLets you select cross sections by name, regular expression or index from a list of cross sections.
Generate Cross Section TableConverts a list of cross sections into a string which can be streamed as a csv-file and used as a cross section table.
Read Cross Section Table from FileReads cross section data from a csv-file.
## **Material**
Material PropertiesSets the characteristic parameters of an isotropic or orthotropic material.
Material SelectionLets you select a material by name, regular expression or index from a list of materials.
Read Material Table from FileReads a list of materials from a table given in csv-format.
Disassemble MaterialOutputs the physical properties of a material.
## **Algorithms**
AnalyzeCalculates the deflections of a given model using first order theory.
AnalyzeThIICalculates the deflections of a given model including the effect of axial or in-plane forces.
Analyze Nonlinear WIPHandles calculations involving large deformations. Is work in progress: the speed of convergence will be improved in future releases. Currently it works best for beams, but can also handle shell structures.
Large Deformation AnalysisDoes an incremental geometrically non-linear analysis for loads in load case zero. Return displacements only, no stresses of cross section forces.
Buckling ModesCalculates the buckling-modes and buckling load-factors of the given model under normal forces .
Eigen ModesCalculates the eigenmodes of the given model according to the special eigenvalue problem.
Natural VibrationsCalculates the natural vibrations of the given model.
Optimize Cross SectionIteratively selects optimum cross sections for beams, trusses and shells.
BESO for BeamsOptimizes the topology of beams in a structure by using Bi-directional Evolutionary Structural Optimization.
BESO for ShellsOptimizes the topology of shells in a structure by using Bi-directional Evolutionary Structural Optimization.
Optimize ReinforcementPerforms reinforcement design for shells. It uses linear elastic cross section forces and the assumption of zero tensile concrete strength for determining reinforcement quantities.
Tension/Compression EliminatorRemoves beams or trusses under axial tension or compression. By default compression members will be removed.
## Results
Model ViewLets you inspect the general properties of the model.
Deformation-EnergyRetrieves deformation energies of the elements of the model.
Nodal DisplacementsReturns nodal displacements: translations in global x-, y-, and z-direction; rotations about the global x-, y- and z-axis.
Principal Strains ApproximationApproximates the principal strain directions from the model deformation at arbitrary points.
Reaction ForcesReturns reaction forces and moments at supports.
Utilization of ElementsMulti-component that returns the utilization of elements. “1” means 100%:
  • Utilization of Beams (default)
The utilization of beams is calculated according to EC3 (see section A.4).
  • Utilization of Shells
Returns the maximum Van Mises stress in each face of the shell.
Beam ViewLets you inspect beam properties: section forces, cross sections, displacement, utilization and stresses. Is to be plugged into the definition after the “ModelView”-component.
Beam DisplacementsReturns displacements along elements: translations in global x-, y-, and z-direction; rotations about the global x-, y- and z-axis.
Beam ForcesRetrieves section forces along beams and trusses.
Shell ViewLets you inspect shell properties: displacement, utilization, principal stresses and Van Mises stress. Is to be plugged into the definition after the “ModelView”-component.
Line Results on ShellsMulti-component for generating line results on shells:
  • Force Flow (default)
Computes flow lines for forces in given direction at user defined positions.
  • Isolines
Creates lines that connect points of same value for selected shell results (e.g. principal stresses, displacement, utilization, cross section thickness) at user defined positions. Also returns values and can thus be used for probing the shell state.
  • PrincMoment
Returns the principal moment lines that originate from user defined points on shells.
  • PrincStress
Outputs the principal stress directions in the center of each shell element.
Results Vectors on ShellsMulti-component for generating vector results in each element of a shell:
  • PrincStress (default)
Outputs the values of first and second principal stress on a given layer in the center of each shell element.
  • PrincForces
Outputs the first and second principal normal forces and moments in the center of each shell face as vectors.
Shell forcesOutputs the values of the local or principal normal forces and moments in the center of each shell element.
## Expor**t** / Import
Export Model to SAVExports a model to a Structural Analysis Format (SAF)-file.
Export Model to DStVExports a model to RStab5, RStab6, RStab7, RStab8 or Robot by creating a DStV-file.
Export Model to JSON / BSONExports to model to a JSON or BSON file.
Import Model from JSON / BSONImports a model from a JSON or BSON file.
Export Model to CSVExports a model to Comma-Separated Value (CSV)-file
## Utilities
Closest PointsConnects each node of one set to a given number of nearest neighbor nodes or neighbors within a specified distance of another set.
Closest Points Multi-dimensionalPerforms a multidimensional nearest neighbor search on two sets of vectors.
Cull CurvesInputs a data tree of straight lines and thins them out so that no lines in different branches are closer than a given limit distance.
Detect CollisionsCounts the number of intersections between the model and a given mesh.
Get Cells from LinesCreates closed cells from a graph and vertices on a user supplied plane.
Line-Line IntersectionIntersects given lines and returns resulting end-points and pieces.
Local VectorTransforms a vector from the global to a local coordinate system given by a plane.
Line-Mesh IntersectionReturns the points where given lines intersect given meshes.
Mesh BrepsTakes multiple breps and generates a unified mesh from them. The algorithm takes account of common edges and insertion points. This lets one define positions for supports or point-loads on shells.
Principal States TransformationTransforms given principal vectors of stresses, moments or in-plane forces to an arbitrary direction.
Remove Duplicate LinesEliminates identical lines.
Remove Duplicate PointsEliminates identical points.
Simplify ModelChanges a model by straightening the connecting elements between nodes that connect to more than two neighbor nodes.
Element FeltingFelts elements of a model by connecting them at their mutual closest points.
MapperApplies mappings (like Simple Stitch) to a model.
Interpolate ShapesInterpolates between a base geometry (0.0) and given shape(s) (1.0).
StitchMulti-component for defining modes of connection between sets of beams:
  • Simple Stitch (default)
Connects beam sets by a preset number of elements.
  • Stacked Stitch
Connects beam sets by a preset number of elements that do not intersect each other.
  • Proximity Stitch
Connects beam sets by a preset number of elements whose maximum inclination can be controlled via min/max offset-limits from their starting point.
Surface to TrussFills surfaces with different types of trusses.
User Iso-LinesCreates iso-lines on a model based on user supplied nodal values.
User Stream-LinesCreates stream-lines on a model based on user supplied vectors at the nodes.
# 3.0 Settings The subsection **“Settings”** of Karamba3D contains one component: * **"License"**: for checking the license status. # 3.0.1 License The "License"-component outputs details regarding the version and build number of the installed Karamba3D plug-in. The output also contains the license type and date of expiration of the license (see fig. 3.0.1.1). For questions regarding licenses see section [4.1.3: Licensing](/troubleshooting/4.3.-miscellaneous-problems/licensing). ![Fig. 3.0.1.1: The License-component returns information regarding version number ans license](/files/-MgzgPsLVF3CLyeTVLC4) # 3.1 Model The subsection **“1.Model”** of Karamba3D contains components for handling the basic aspects of a structural model. Read on to learn more about all aspects of creating a model. # 3.1.1 Assemble Model To calculate the behavior of a real-world structure, its geometry, loads, and supports must be defined. The **“Assemble”** component gathers all the necessary information and creates a structural model from it (see Fig. 3.1.1.1).

Fig. 3.1.1.1: The “Assemble”-component gathers data and creates a model from it.

{% file src="/files/8BlAD8VhMeC6a9pxc4LB" %} If beams are defined by node indexes, they will refer to the list of points provided at the **“Pts”** input plug: the first node in the list has index zero, the next one index one, and so on. The **“Pts”** input can also be used to give the model nodes a specific order. The value at the **“LDist”** input plug defines the distance below which points will be merged into one. This helps in dealing with inaccurate geometry. The default limit distance is 5 mm. {% hint style="info" %} By default, elements with coincident nodes get rigidly connected. {% endhint %} Snapping together of nodes does not apply to points provided via the **“Pts”** input plug. This can be used for defining zero-length springs, such as the bolt connecting the two pieces of a scissor mechanism. In such cases, duplicate points can be provided via the **“Pts”** input. Elements connecting to these points do so in an alternating fashion: the first element connects to the first duplicate node, the next to the second, and so on. The actual connection between the elements can be made via a spring with zero length, as shown in Fig. 3.1.1.2. The local axes of zero-length spring elements correspond by default to the global coordinate system. To define zero-length elements, provide duplicate points at the **“Pts”** input of the **“Assemble”** and **“LineToBeam”** components. Elements attach to these nodes in an alternating fashion.

Fig. 3.1.1.2: Zero length spring coupling the two parts of a scissor structure.

{% file src="/files/04uekB3xnjNP1h6iyfL4" %} Cross sections of elements and materials can be defined either upon creating an element or at the **“Assemble”**-component. The latter option overrides the former and assigns cross sections and materials via element identifiers. Using regular expressions for selecting identifiers of elements provides a flexible means of attaching cross sections and materials to different parts of a model. The **“Mass”** output plug renders the mass of the structure in kilograms and includes user-specified point masses. **“COG”** represents the position of the center of gravity. When plugged into a panel, the model prints basic information about itself, including the number of nodes, elements, and so on. At the start of the list, the characteristic length of the model is given, calculated as the distance between opposing corners of its bounding box. # 3.1.2 Disassemble Model It is sometimes necessary to take apart existing models in order to: 1. Reassemble them in different configurations. 2. Retrieve the results of, for example, a cross-section optimization. The **“DisassembleModel”**-component can be used for decomposing a structural model into its components (see Fig. 3.1.2.1 and Fig. [2.2.8.3](/2-getting-started/2-getting-started-1/setting-up-a-structural-analysis/2.2.8-retrieve-results#disassembling-a-structural-model)). Resulting loads, supports, and elements reference the nodes they connect to by position, regardless of whether they were initially defined using coordinates or node indexes. This allows parts of an old model to be reused and reassembled in a new model where the node indexes have changed. At the **“CroSec”**- and **“Material”**-output only those cross sections and materials show up which were directly fed into the **“Assemble”**-component. In order to get all cross sections, it is necessary to disassemble the model elements. The cross section materials result from disassembling the cross sections. In general the order of the output of elements, supports, materials, cross sections, loads and load case combinations determines the input-order. The ordering of nodes corresponds to how the first occurred in the provided list of elements. For imposing an order on the nodes one needs to provide a list of positions at the "**AssembleModel**"-component's "**Pts**" input which can be found in the "Options" submenu.

Fig. 3.1.2.1: A model is decomposed into its components and reassembled. This allows to change properties existing models.

{% file src="/files/WZFfLUWc6Fmwpp9ZC82F" %} # 3.1.3: Modify Model If you need to change the nodal positions of an existing model, the **“ModifyModel”** component is useful. The **“Pt”** input expects the list of new points to be used as the model's new nodal positions (see Fig. 3.1.3.1). This can be used, for example, to impose imperfections based on the structure's first buckling mode.

Fig. 3.1.3.1: The “ModifyModel”-component changes the nodal positions of model.

{% file src="/files/8sEzuiXJ70a6f1KhUNOL" %} # 3.1.4: Connected Parts When creating a model based on imprecise geometry or using a generative process, elements may not be connected to each other as desired. The **“Connected Parts”**-component (see fig. 3.1.4.1) takes a model as input and determines its connected parts. It considers beams and trusses only. Connected groups get listed in a data tree in descending order of group size. ![ Fig. 3.1.4.1: The “Connected Parts”-component.](/files/-MCkEV60Fopr1njRvWUl) {% file src="/files/2qOnw7JMWLtMWMpmSGDV" %} # 3.1.5: Activate Element The activation state of an element can be controlled with the **“Activate Element”**-component (see fig. 3.1.5.1). This component expects a model and a list of boolean values as input. The list of true/false values will be mapped to the activation status of the elements in the model. **“True”** corresponds to active, **“False”** to inactive. Section [3.5.9](/3-in-depth-component-reference/3.5-algorithms/3.5.9-beso-for-beams) shows, how the **“Activate Element”**-component enables one to view the solution history of the iterative **“BESO for Beams”**-algorithm. {% hint style="info" %} Karamba3D sets elements inactive by giving them a very weak material with zero weight. {% endhint %} {% file src="/files/tHBgnO6t4opBHYxv1tZQ" %}

Fig. 3.1.5.1: Setting the activation state of all elements of a model with a list of boolean values.

{% file src="/files/yuaE4paqAdt2ARG8Aq02" %} # 3.1.6 Create Linear Element The "Create Linear Element" is a multi-component for creating beam or truss elements. Vie the drop-down list users may chose between the following options: * LineToBeam: converts curves into straight beam elements. * LineToTruss: converts curves into straight truss elements. * IndToBeam: creates beams from node indexes for starting and end node. * ConToBeam: Takes a conectivity diagram and creates beams from it. The above four options will be further explained in the next chapters. {% file src="/files/lAhvDDUqQaf2qhpsTnXo" %} # 3.1.6.1 Line to Beam The **“LineToBeam”** component converts lines into beam elements. Fig. 3.1.6.1 illustrates how the component takes two lines as input, determines their connections, and outputs beams and a set of unique points representing their endpoints. Lines with identical endpoints are automatically removed. The **“LineToBeam”** component accepts straight lines, polylines, and splines as geometric input. Polylines are exploded into segments, and splines are divided based on the parameters **"ToPAng"**, **"ToPTol"**, and **"ToPMinL"** - see the description below for their meaning. All coordinates are in meters (or feet for Imperial units). {% embed url="" %} For cross-section design, the buckling length assumed for individual elements is crucial. By default, if **“SetBkl”** is "True", the distance between the endpoints of a line, polyline, or spline is used as the initial buckling length assumption for all created elements. An automatically assumed value for the buckling length is marked with a negative sign but is taken as an absolute value in the design procedures. This assumption can be overridden via a ["ModifyBeam"-component](/3-in-depth-component-reference/3.1-model/3.1.10-modify-element#modify-beam) by the user by supplying a positive buckling length. In case that the simplified buckling length calculation done by Karamba3D (see section [3.6.8: Optimize Cross Section](/3-in-depth-component-reference/3.5-algorithms/3.5.8-optimize-cross-section)) leads to a larger value than the initial assumption then the larger value is applied. A User defined positive buckling length always wins over any assumptions. {% embed url="" %} The **“Color”** input allows defining a color for rendering elements. To display the colors, activate the **“Elements”** button in the **“Colors”** submenu of the **“ModelView”** component and ensure the **“Cross section”** option in the **“Render Settings”** submenu of the **“BeamView”** component is enabled.

Fig. 3.1.6.1.1: The “LineToBeam” component converts two lines into beams.

{% file src="/files/Exa0hMHCWnNlWcvX66M1" %} Elements can have non-unique names via the **“Id”** input, accepting a list of strings as identifiers. The default is an empty string. Each beam has a default name: its zero-based index in the model. Identifiers help group beams for modification or display. To assign multiple names to an element, use the notation '&"id1"|"id2"|"id3"|...' or shorter '\&id1|id2|id3|...'. Cross-sections can be attached to elements with the **“CroSec”** input. Cross-section definitions via the **“Assemble”** component override these settings. A click on the **“Options”** submenu heading reveals additional input-options of the **“LineToBeam”**-component:
InputProperty
InputProperty
“Pts”The order in which points appear in the output node list is random by default. However, it is sometimes advantageous to identify certain points by their list index to apply loads or define supports. This can be achieved by feeding a list of coordinates into the “Points” plug. They will be placed at the beginning of the output node list. For example, to ensure the endpoints of the structure in Fig. 3.1.6.1 have index 0 and 1, input a list of points with coordinates (0/0/0) and (4/0/0).
“New”If this plug is “False”, only lines that start and end at one of the points given in the input points list will be added to the structure.
“Remove”If this option is “True”, the "LineToBeam" component checks for lines that overlap and merges such duplicates into one. This prevents an error that is hard to detect visually: two lines on the same spot mean double member stiffness in the structural model. Alternatively, apply the “Remove Duplicate Lines” component from the Karamba3D utilities section to the list of incoming lines to ensure a one-to-one correspondence between lines and elements.
“LDist”Sets the limit distance for two points to be merged into one. Points supplied via lines are considered identical if their distance is less than that specified in “LDist”. The default value of “LDist” is 5 mm. Snapping nodes does not apply to points supplied via the “Pt” input plug. The mechanism for attaching duplicate nodes to elements is identical to that used by the “Assemble” component (see section 3.1.1).
“Z-Ori”The default orientation of beams and trusses is described in section 3.1.14. The “Z-Ori” input allows defining a non-standard direction for the local Z-axis.
“Bending”Allows switching off the bending stiffness of beams, turning them into trusses. For details, see section 3.1.10.
"SetBklL"Set Buckling Length: If "True" (the default), the buckling length in local Y- and Z- as well as for lateral torsional buckling is set as the distance between the endpoints of the input curve. If this length is smaller than the automatic estimate based on the connectivity of the element's endpoints, it will be replaced by the larger value.
"ToPAng"To Polyline Max Angle: For converting splines into polylines: Maximum angle (0 to pi) between tangents at adjacent vertices.
"ToPTol"To Polyline Tolerance: For converting splines into polylines: If tolerance = 0, the parameter is ignored. This parameter controls the maximum permitted distance from the curve to the polyline.
"ToPMinL"To Polyline Min Edge-length: For converting splines into polylines: If maxEdgeLength = 0, the parameter is ignored. This parameter controls the maximum permitted edge length in the base unit for geometry input.
Beams that meet at a common point are by default connected rigidly in the structural model like they were welded together. See section [3.3.6](/3-in-depth-component-reference/3.4-joint/3.3.6-beam-joints) on how to define joints at the end of beams. The **“Info”** output-plug informs about the number of removed nodes and beams. Beams come with several default properties to be immediately useful. These can be seen in the top right string-output of Fig. 3.1.6.1: **“active”** means that a beam will be included in the structural model. The default cross-section is a circular hollow profile with a diameter of 114 mm and a wall thickness of 4 mm. The default material is steel of grade “S235” according to Eurocode 3. {% file src="/files/dl47ewXcouDh9jTCfM09" %} {% file src="/files/oDcSJAnindSkMbkF7XuB" %} # 3.1.6.2 Line to Truss This is a conveninent way of defining linear elements with axial stiffness only. The same can be achieved by using the **"Line to Beam"** component and setting **"Bending"** to "False". # 3.1.6.3 Connectivity to Beam In Grasshopper, meshing algorithms can generate topological connectivity diagrams. The **“Connectivity to Beam”** component allows these diagrams to be directly converted into beam structures (see Fig. 3.1.6.3.1).

Fig. 3.1.6.3.1: The “Connectivity to Beam”-component turns connectivity diagrams into sets of beams.

The input-plugs **“Z-Ori”**, **“Color”**, **“Id”** and **“CroSec”** have the same meaning as for the **“LineToBeam”**-component (see section [3.1.6](/3-in-depth-component-reference/3.1-model/3.1.6-create-linear-element/3.1.6-line-to-beam)[.1](/3-in-depth-component-reference/3.1-model/3.1.6-create-linear-element/3.1.6-line-to-beam)). # 3.1.6.4: Index to Beam Sometimes the initial geometry is already given as a set of points and two lists of node indexes, with one entry for each start and end point of beams respectively. In such cases, it would be cumbersome to convert this information into geometric entities only to feed it into the **“LineToBeam”** component, which reverses the previous step. The **“IndexToBeam”** component (see Fig. 3.1.6.4.1) accepts a pair of lists of node indexes and produces beams with default properties. This approach speeds up model generation considerably, as there is no need to compare nodes for coincident coordinates.

Fig. 3.1.8.1: The “IndexToBeam”-component lets you directly define the connectivity information of beams.

The **“IndexToBeam”** component allows for the definition of zero-length elements, which is useful when you want to connect elements that touch but should not be rigidly connected (think of a scissor – see section 3.3.3 about springs). The input-plugs **“Z-Ori”**, **“Color”**, **“Id”** and **“CroSec”** have the same meaning as for the **“LineToBeam”**-component (see section [3.1.6](/3-in-depth-component-reference/3.1-model/3.1.6-create-linear-element/3.1.6-line-to-beam)[.1](/3-in-depth-component-reference/3.1-model/3.1.6-create-linear-element/3.1.6-line-to-beam)). # 3.1.7 Create Surface Element The **“Create Surface Element”** component allows creating surface elements from meshes. The options available in the drop-down list are: * **“MToShell”**: Convert mesh to shell element. * **“MToMembr”**: Convert mesh to membrane element. Refer to the following sections for detailed information on these components. # 3.1.7.1: Mesh to Shell The **“MeshToShell”** component converts a triangle or quad mesh into a group of shell or membrane elements (see Fig. 3.1.9.1). Quads are automatically decomposed into triangles. Shell patches are rigidly connected when some of their nodes have the same index. Colors can be attached to shells via the **“Color”** input. To enable the display of shell element colors, activate **“Elements”** in the **“Colors”** submenu of the **“ModelView”** component. Additionally, ensure **“Cross section”** is selected in the **“Render Settings”** submenu of the **“ShellView”** component. Each patch of shells can be given an identifier via the **“Id”** input for later reference when attaching custom material or cross-section properties. By default, shells have a thickness of 1 cm and steel as their material. Use the **“CroSec”** input to change these properties. Clicking on the **“Options”** submenu header reveals additional inputs: **“Pts”** and **“LDist”** serve the same purpose as in the **“LineToBeam”** component (see section 3.1.6). Additionally, mesh faces with an area smaller than $$LDist^2 \cdot 0.1$$ are automatically removed.

Fig. 3.1.9.1: The “MeshToShell”-component turns meshes into shells.

{% file src="/files/4zCGl25hw760SeWg6tfH" %} The shell elements used in Karamba3D resemble the TRIC-element devised by Argyris and coworkers (see [\[1\]](/appendix/bibliography), [\[2\]](/appendix/bibliography) for details). They are faceted (i.e. flat) elements. Karamba3D neglects transverse shear deformation in case of shell elements. {% embed url="" %} ## Shells and Membranes For very thin shells, the bending stiffness can be neglected relative to the in-plane stiffness, resulting in membrane elements with three translational degrees of freedom (DOFs) per node. If t stands for the shell thickness, its bending stiffness is proportional to t³ while the in-plane stiffness varies with t. This discrepancy leads to significantly different magnitudes of entries in the element stiffness matrices, causing numerical problems in the solution procedure. Membrane elements result from the **“MeshToShell”** component when the **“Bending”** input is set to **“False”**. Flat assemblies of membrane elements have kinematic modes in the transverse direction unless stabilized via positive$$N^{II}$$-values. ## Drilling Degrees of Freedom In Karamba3D shell elements do not have bending stiffness with respect to nodal rotations about the shell normal. In the case of curved surfaces, drilling degrees of freedom are blocked since the elements connecting to a node do not lie in a plane. For flat surfaces this is not the case. therefore the "Analysis" component will report a rigid body mode. You can either ignore this warning or add a rotational support perpendicular to the plane at an arbitrary node of the slab. # 3.1.7.2: Mesh to Membrane This is a convenient component for generating membranes. Setting **“Bending”** to **“False”** in the **“Mesh to Shell”** component achieves the same result. {% embed url="" %} # 3.1.8: Modify Element **“Modify Element”** is a multi-component that can be applied to shell, beam, and truss elements. Use the drop-down list at the bottom of the component to select the type. By default, Karamba3D assumes the cross-section of beams to be steel tubes with a diameter of 114 mm and a wall thickness of 4 mm. Use the **“Modify Element”** component with **“Element Type”** set to **“Beam”** to set the beam properties as needed. Fig. 3.1.8 shows how this can be done. There are two methods for using the **“Modify Element”** component: 1. Insert it in front of the **“Assemble”** component and let element objects flow through it (see, for example, the modification of beams in Fig. 3.1.10.1). By default, the **“Modify Element”** component leaves all incoming elements unchanged. Several **“Modify Beam”** components can act consecutively on the same beam. 2. Create a stand-alone element agent that can be fed into the **“Elem”** input of the **“Assemble”** component. The **“ShellId”** or **“BeamId”** input plugs let you select the elements to be modified. Use regular expressions to specify groups of elements.

Fig. 3.1.8: Modification of the default element properties: usage as flow-through-component for beams, and as an agent for shells.

{% file src="/files/JICetmPhu2HlupIsxkEU" %} {% file src="/files/A1hWhksBxqxtMxEBxIEb" %} {% file src="/files/k2dWcW1OwxkaufTERhWh" %} {% file src="/files/R6PsjDxrlmwh2CoBAGFT" %} ## **Modify Beam** These element properties can be modified: ### Activation Status of Beams When the **“Active”** input is set to false, the corresponding beam is excluded from further calculations until **“Active”** is reset to true. See section [3.1.5](/3-in-depth-component-reference/3.1-model/3.1.5-activate-element) for an alternative way of setting a beam's activation state. ### Bending Stiffness Beams resist normal forces and bending moments. Setting the **“Bending”**-input of the **“ModifyElement”**-component to **“False”** disables the bending stiffness and turns the corresponding beam into a truss. There are reasons for this adjustment: * Connections between beams that transfer bending and normal forces are typically more expensive than those that carry normal force only. The design of connections heavily depends on the material used: rigid bending connections in wood are harder to achieve than in steel. However, rigid connections add stiffness to a structure and reduce its deflection. Using truss elements instead of beams is a safer approach. * For slender beams, i.e., beams with a small diameter compared to their length, the effect of bending stiffness is negligible compared to axial stiffness. Consider a thin wire that is easy to bend but hard to tear by pulling. * Eliminating bending stiffness reduces computation time by more than half for each node with only trusses attached. * Karamba3D bases deflection calculations on the initial, undeformed geometry. Some structures, like ropes, are form-active, meaning the deformed geometry and the axial forces in the rope provide equilibrium. This effect is not accounted for in Karamba3D's first order theory (Th.I.) calculations and leads to large doeformations for rope-like beams. Using a truss instead of a beam-element for first order analysis can circumvent this issue. Alternatively, reduce the rope's specific weight to zero or start from a slightly deformed rope geometry and apply external loads in small steps, where each step's initial geometry results from the previous step's deformed geometry (see section [3.5.4](/3-in-depth-component-reference/3.5-algorithms/3.5.4-analyze-large-deformation)). Trusses only take axial forces and do not prevent nodes from rotating. Karamba3D automatically removes rotational degrees of freedom for nodes connected only to trusses. When a beam with bending enabled connects to a node, the node retains its rotational degrees of freedom. Be mindful of this when the **“Analysis”** component turns red and reports a kinematic system. Transferring only axial forces means a truss restricts a node's movement in one direction. A node not attached to a support has three translational degrees of freedom, requiring three truss elements not in the same plane to be fixed in space. ### Height and Thickness of Cross-sections **“Height”** (equivalent to the outer diameter D for circular tubes) and wall thickness of a cross-section influence a beam's axial and bending stiffness. Karamba3D expects both input values in centimeters. The cross-section area is linear in both diameter and thickness, whereas the moment of inertia grows linearly with thickness and depends on D³ for full rectangular sections and on D² for I-profiles and box sections. Therefore, increasing a beam's height (or diameter) is more effective for insufficient bending stiffness than increasing its wall thickness. ### Local and Global Eccentricity of the Beam Axis The **“EcceLoc”** and **“EcceGlo”** input plugs set the eccentricity of the beam axis with respect to the connection line between its endpoints. Both expect a three-dimensional vector. **“EcceLoc”** refers to the local coordinate system, and **“EcceGlo”** refers to the global coordinate system. Beam eccentricities can also be defined via the **“Eccentricity on Beam”** component (see section [3.3.7](/3-in-depth-component-reference/3.3-cross-section/3.3.7-eccentricity-on-beam-eccentricity-on-cross-section)). ### Orientation of the Beam This input allows defining the orientation of a beam, working similarly to the orientate-beam component (see section [3.1.14](/3-in-depth-component-reference/3.1-model/3.1.14-orientate-element)). ### Buckling Property for Cross Section Optimization Buckling can be turned off for cross-section optimization, simulating pre-tensioned slender elements without actually pretensioning them. The necessary pretension force is roughly the negative value of the largest compressive axial normal force of all load cases. ### Buckling length in local beam directions For cross-section optimization, it is necessary to know a beam’s buckling length. Karamba3D approximates it using the algorithm described in section [3.5.8](/3-in-depth-component-reference/3.5-algorithms/3.5.8-optimize-cross-section). For system buckling cases, this approximation may not be safe. The **“BklLenY”**, **“BklLenZ”**, and **“BklLenLT”** input plugs allow specifying the buckling length of a beam for its local Y- and Z-axes, as well as for lateral torsional buckling. These values override those from Karamba3D's buckling length calculation when specified. The **“lg”** value sets the distance of transverse loads from the center of shear of the cross section, defaulting to zero. Positive values mean the loads point towards the shear center, acting destabilizing for lateral torsional buckling. The **“lg”** property influences the beam's utilization concerning lateral torsional buckling according to Eurocode 3. ### Second Order Theory Normal Force $$N^{II}$$ Axial normal forces influence the stiffness of a beam in second order theory (Th.II) calculations. Compressive forces lower, and tensile forces increase its bending stiffness. For example, a guitar string vibrates at a higher frequency (i.e., is stiffer) under increased tension. In Karamba3D, the normal force impacting stiffness ( $$N^{II}$$) is independent of the normal force causing stresses in the cross-section ($$N$$). This allows superimposing second order theory results safely by choosing $$N^{II}$$as the largest compressive force $$N$$of each beam. {% file src="/files/cmtyOhGFT9uLhiQKKcBm" %} ## **Modify Shell** ### Height Sets a uniform cross section height throughout the shell. ### Second Order Theory Normal Force $$N^{II}$$ As with beams, $$N^{II}$$for shells specifies the in-plane normal force which impacts stiffness in case of second order theory calculations. It is a force per unit of length assumed to be of same magnitude in all directions. {% file src="/files/H9bSllXrvzLiAm6lEsCq" %} # 3.1.9: Point-Mass Karamba3D can calculate the natural vibration modes and frequencies of structures (see section [3.6.7](/3-in-depth-component-reference/3.5-algorithms/3.5.7-natural-vibrations)). To ensure accurate results, the inertia properties of a structure need to be correctly modeled. The masses of elements (e.g., beams, trusses, shells) are automatically included. All other items must be added via point masses. {% hint style="info" %} Note that masses defined with the **“Point-Mass”** component do not have weight but only inertia. They also do not contribute to the mass of the model as output by the **“Assemble”** component. {% endhint %} Therefore, they only affect the calculation of natural frequencies. The **“Point-Mass”** component expects a mass in kilograms at its **“Mass”** input plug (see Fig. 3.1.9.1). A vector supplied at **“SFacs”** specifies mass multipliers for the global X-, Y-, and Z-directions. In Fig. 3.1.9.1, the inertia of the mass acts only in the Z-direction. Nodes where masses are to be applied can be identified by supplying node indexes or positions (similar to point loads) to the **“Pos|Ind”** input plug. Point masses are displayed as green spheres, with diameters calculated from the volume as mass divided by density. The default density is for steel and can be specified at the **“rho”** input plug.

Fig. 3.1.9.1: Vibration mode of beam with point mass in the middle

{% file src="/files/ZJmujjfipbwiKCnXjfoo" %} # 3.1.10: Disassemble Element When you need detailed information about a beam or shell element, use the **“DisassembleElement”** component (see Fig. 3.1.10.1). The component contains several subsections that can be expanded by clicking on the dark menu header. ![ Fig. 3.1.10.1: A beam decomposed into its individual parts](/files/-MCkEW3vNx5HN13yqS5H) {% hint style="info" %} The output of "BklLenY", "BKlLenZ" and "BklLenLT" may contain negative values: A negative sign indicates that the corresponding length-value was automatically calculated and not set by the user (see section [3.6.8](/3-in-depth-component-reference/3.5-algorithms/3.5.8-optimize-cross-section) regarding the assumptions used for the automatic calculation of the buckling length).\ In all calculations the absolute values for the buckling length will be used. {% endhint %} {% file src="/files/WNddiTyPspMtV8z2M8Vp" %} {% file src="/files/UbW7dokzDs5jthNVqnPp" %} {% file src="/files/LKPpHzS1f9bdnryeFvQy" %} # 3.1.11: Make Element-Set The **“Make Element-Set”** component provides a practical way to group different elements (trusses or beams) under one identifier (see Fig. 3.1.11.1). Element sets do not need to be disjoint. The **“ElemIds”** plug expects a list of strings with element identifiers, element indexes, other element-set identifiers, or a regular expression. Regular expressions must begin with "&". **“Set Id”** expects a string that serves as the identifier of the new set of elements.

Fig. 3.1.11.1: Element-sets can be used to group beams

{% file src="/files/m4AFYGjQX7ojZhdsUKZH" %} Element sets can be used for defining geometric mappings. In this context, an element set consisting of beams or truss elements represents a polygon of straight segments. The order of the elements in the set is defined by the order in which they were entered into the set. Such polygons can be split at any position (see section [3.9.15](/3-in-depth-component-reference/3.8-utilities/3.8.15-connecting-beams-with-stitches)). **“MinSLen”** (minimum segment length) allows you to set the minimum length that may result from such a split. If segments would be smaller than this minimum length, the intersection point snaps to its nearest neighbor. To visually group a structure, element sets can be assigned different colors. These colors appear when **“Cross section”** is enabled in the **“BeamView”** component’s **“Render Settings”** (see section [3.7.2.1](/3-in-depth-component-reference/3.6-results/3.7.2-results-on-beams/3.6.7-beamview)) and the **“Elements”** option in the **“Colors”** submenu of the **“ModelView”** component is enabled. The identifier of an element set can be used anywhere an element identifier is required. To be registered with the model, element sets need to be fed into the **“Set”** input plug of the **“Assemble”** component. {% file src="/files/H2hIWzTb4tdYQkDAPLOD" %} {% file src="/files/s9QMlw51Bvlec9oivY8o" %} {% file src="/files/vwhmOsmtumALE9soOxdW" %} # 3.1.12: Orientate Element The **“Orientate Element”** component allows for the orientation of beams and shells by selecting the element type from the drop-down list under **“Element Type”**. ## **Orientate Beam** In Karamba3D the default orientation of the local coordinate system of a beam or truss follows these conventions: * The local X-axis (red) is the beam axis, pointing from the starting node to the end node. * The local Y-axis (green) is perpendicular to the local X-axis and parallel to the global XY-plane. This specifies the local Y-axis uniquely unless the local X-axis is perpendicular to the XY-plane, in which case the local Y-axis is chosen to be parallel to the global Y-axis. The default criterion for verticality is that the Z-component of the unit vector in the axial direction is larger or equal to a specified value, which can be changed in the ["karamba.ini"](/2-getting-started/2-getting-started-1/2.4-user-settings) file via the **“limit\_parallel”** property under **Settings**. * The local Z-axis (blue) is derived from the local X- and Y-axes, forming a right-handed coordinate system. * ```

Fig. 3.1.14.1: Controlling the orientation of local beam coordinate system

``` {% file src="/files/7Ek2d0SimnfSeWyt1uaF" %} The local coordinate system affects the direction of locally defined loads and the orientation of the element’s cross section. Use the **“Orientate Beam”-**component to set the local coordinate system (see fig. 3.1.14.1): * The **“X-axis”** input plug accepts a vector. The local X-axis will be oriented such that its angle with the given vector is less than 90 degrees, allowing for consistent orientation of a group of beams. * The local Y-axis lies in the plane defined by the local X-axis and the vector plugged into the **“Y-axis”** input. If the Y-axis is parallel to the beam axis, it is not applicable. * If no vector is supplied at the **“Y-axis”** input, or if the given Y-axis is not applicable, the local Z-axis of the beam lies in the plane defined by the local X-axis and the vector plugged into the **“Z-axis”** input. * **“Alpha”** represents an additional rotation angle (in degrees) of the local Z-axis about the local X-axis. To control the orientation of a beam, the **“Orientate Beam”** component can be applied in two ways: 1. **Flow-through**: Plug it between a **“LineToBeam”** component and an **“Assemble”** component. The changes will be applied to all beam elements passing through it. For shell elements, the output is **“Null”**. 2. **Agent**: Specify beams by identifier via the **“BeamId”** input and plug the resulting beam agent directly into the **“Elem”** input of the **“Assemble”** component. This method allows for the use of regular expressions to select elements (see section [3.1.13](/3-in-depth-component-reference/3.1-model/3.1.15-select-beam)). {% file src="/files/91bHBk0XMfdlI4McAFBp" %} {% file src="/files/kirXWCyShucMzlo7UHCV" %} {% file src="/files/v6FcImgyNKuMCNkrafro" %} ## **Orientate Shell** For shells the default orientation of their local coordinate systems can be seen in fig. 3.1.14.2. The following convention applies: The local x-axis is parallel to the global x-direction unless the element normal is parallel to the global x-direction. In that case the local x-axis points in the global y-direction. The local z-axis is always perpendicular to the shell element and its orientation depends on the order of the vertices of the underlying mesh face: If the z-axis points towards ones nose, the order of the face vertices is counter-clockwise (See fig. 6.17 in \[12] for an unforgettable way of remembering the right-hand rule of rotation.). ![ Fig. 3.1.14.2: Default orientation of the local shell coordinate systems](/files/-MCkEa0QGVJRBkOqFJYi) The **“Orientate Shell”**-component lets one control local x- and z- directions of the faces which make up a shell: **“X-Oris”** and **“Z-Oris”** inputs expect lists of direction vectors, one for each mesh face. In case the number of vectors does not match the number of faces the longest list principle applies. Infeasible directions (e.g. a prescribed z-vector which lies in the plane of an element) get ignored. Regarding the application of the **“Orientate Shell”**-component the same two options (**“flow-through”** or **“agent”**) exist as for the **“Orientate Beam”**-component.

Fig. 3.1.14.3: User defined orientation of the local shell coordinate systems

{% file src="/files/ySoPS9c2VU4Bz69Rw3Aq" %} {% file src="/files/IgmxLuKWul6Oy37A4Ywg" %} # 3.1.13: Dispatch Elements AAll structural elements in Karamba3D can be given identifiers, or names. Names are case-sensitive and must start with a letter or underscore. After the initial letter, numbers and letters may follow. Names do not need to be unique; two elements can have the same name without causing issues in Karamba3D. Each element has a default identifier: its index. This is why an integer number is not allowed as an element identifier. Fig. 3.1.13.1 shows how a list of elements can be split into two data trees using their identifiers. The **“Dispatch Elements”** component expects a list of elements in **“Elems”** and a list of identifiers or regular expressions in **“Id”**. Regular expressions must be prefixed by a “&” and represent a powerful selection tool. In Fig. 3.1.13.1, three use cases are shown: * **“&.\[1-2]”**: The “.” matches any character; “\[1-2]” matches one character in the range of “1” to “2”. This is equivalent to “\[12]”. * **“\&b.”**: Matches any identifier that starts with “b” followed by any character. * **“&.\[13]”**: Matches any identifier that starts with any character followed either by “1” or “3”. ![Fig. 3.1.13.1: Elements can be selected by using their identifiers.](/files/-MjnozcZXiGCm-UQ00Cg) {% file src="/files/NtAu2VXiYcluD9QbBzPy" %} There are two output plugs on the **“Dispatch Elements”** component: **“SElem”** returns the selected elements that match the selection criteria, and **“RElem”** returns the rest. The entries in the **“SElem”** and **“RElem”** output data retain their positions in the original list of elements. Rejoining them results in the original order of elements. # 3.1.14: Select Elements Use the **“Select Elements”** component to filter elements based on specific properties. The selected elements can then be used to retrieve results, calculate their mass, surface area, volume, or generate meshes (see the **“Element Query”** component). Fig. 3.1.14.1 shows how this works: the input plugs **“ElemIds”**, **“Colors”**, **“CrosSecs”**, **“Materials”**, **“LenInter”**, and **“ElemTypes”** can be supplied with lists of element identifiers, colors, cross sections, materials, length intervals, and type indexes. The values in each input plug form criteria via **“OR”**. For example, in Fig. 3.1.14.1, the selected elements may be either purple or red. The individual input plugs are connected via **“AND”**: in the image below, the selected element must be named **“Membrane\_D”**, be red or purple, and be either a membrane or shell, and so on. For shells and membranes, the length refers to the diagonal of their axis-aligned bounding box. For 1-D elements, it is simply their length. The element types are indexed starting with zero. Right-click on the component icon and select **“Expand ValueLists”** to make the value-list input appear. ![Fig. 3.1.14.1: Selection of elements via identifiers, colors, cross sections, materials, size and type.](/files/-MjnvMuPa9Cmg61MWDsx) {% file src="/files/d5aIcaHngEOLnd5Q5Aoi" %} {% file src="/files/o4dCI3KDzoCxv82DYspL" %} {% file src="/files/hXNDIx48Fm8ff2CDtgDl" %} {% file src="/files/ULvNnImkpj9E7sq5wMNl" %} {% file src="/files/J6zEUsdk7OhZ528eyvDk" %} # 3.1.15: Support Without supports, a structure would have the potential to move freely in space. This is undesirable for most buildings. Therefore, it is essential to have enough supports so that the structure cannot move without deforming, i.e., exhibits no rigid body modes. When defining supports for a structure, remember that in three-dimensional space, a body has six degrees of freedom (DOFs): three translations and three rotations (see Fig. 3.1.15.1). The structure must be supported in such a way that none of these DOFs are possible without invoking a reaction force at one of the supports. Otherwise, Karamba3D either refuses to calculate the deflected state or renders very large displacements. Sometimes, results are obtained from movable structures due to the limited accuracy of computer calculations, which leads to round-off errors. It is a misconception to think that if there are no forces in one direction (e.g., in a plane truss), there is no need for corresponding supports. The possibility of displacement is what matters. ![Fig. 3.1.15.1: Metaphor for the six degrees of freedom of a body in three-dimensional space.](/files/-MCkERBi-R4LXw9qywEI) Errors in defining support conditions are easy to detect with Karamba3D. Section 3.6.6 shows how to calculate the eigenmodes of a structure. This type of calculation works even for movable structures: rigid body modes, if present, correspond to the first few eigenmodes. Fig. 3.1.15.2 shows a simply supported beam. The **“Support”**-component takes as input either the index or the coordinates of the point to which it applies.

Fig. 3.1.15.2: Define the position of supports by node-index or position.

{% file src="/files/WKsguzRZhRsLaHrcGBhc" %} By default the coordinate system for defining support conditions is the global one. This can be changed by defining a plane and feeding it into the **“Plane”**-input plug of the **“Support”**-component. Reaction forces and support stiffness aleays apply to the local coordinate system. The component features six small radio button circles that indicate the type of fixation. The first three correspond to translations along the global x, y, and z axes, while the last three represent rotations about these axes. A filled circle signifies a fixed degree of freedom, meaning it is either zero or assigned a predefined value via a **"PointDisplacement"** load (refer to section [3.2.1](/3-in-depth-component-reference/3.2-load/3.2.1-loads#point-displacement)). The state of each circle can be toggled by clicking on it. Additionally, the supported degrees of freedom can be defined parametrically using the “Dofs” input, which expects a list of integers from '0' to '5', corresponding to Tx through Rx. To generate a ValueList component with these options, right-click the component and select **“Expand ValueLists”**, as illustrated in Fig. 3.1.15.2. To model different soil conditions, translational and rotational stiffness values can be provided via the "Ct" and "Cr" input plugs, respectively. These inputs require vectors whose X, Y, and Z components correspond to the stiffness values in the local support coordinate system. It is important to note that specifying a rigid support overrides the definition of a flexible support with a spring stiffness. For example, in Fig. 3.1.15.2, dark green arrows represent fixed supports, while light green arrows indicate flexible supports. If a support movement needs to be imposed on a flexible support degree of freedom, a point load must be added, calculated as the displacement multiplied by the stiffness in that direction. The string output of the component lists the node index or nodal coordinate, an array of six binaries corresponding to its six degrees of freedom, as well as translational and rotational spring stiffnesses. Supports cause reaction forces. These can be visualized by activating **“Reactions”** in the **“Display Scales”** section of the **“ModelView”**-component (see section[ 3.7.1.1](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.6.1-modelview)). They appear as arrows with numbers in green (representing forces) and purple (representing moments). The numbers either mean$$kN$$in case of forces or $$kNm$$ when depicting moments. The orientation of the moment arrows corresponds to the screw-driver convention: The orientation of the moment arrows follows the screw-driver convention: they rotate about the axis of the arrow counterclockwise when viewed such that the arrowhead points toward the observer. From the support conditions in Fig. 3.1.15.2, one can see that the structure is a simply supported beam: green arrows symbolize locked displacements in the corresponding direction. The translational movements of the left node are completely fixed. On the right side, two supports in the y- and z-directions block rotations about the global y- and z-axes. The only degree of freedom left is the rotation of the beam about its longitudinal axis, which is blocked at one of the nodes. In this case, it is the left node where a purple circle indicates the rotational support. ![Fig. 3.1.15.3: Influence of support conditions – undeformed and deflected geometry.](/files/-MCkERBmpLAKFfQd_pWf) The displacement boundary conditions can significantly influence the structural response. Fig. 3.1.15.3 shows an example of this: on the left, all translations are fixed at supports; on the right, one support is movable in the horizontal direction. When calculating the deflection of a chair, support its legs in such a way that no excessive constraints exist in the horizontal direction; otherwise, you underestimate its deformation. The more supports applied, the stiffer the structure and the smaller the deflection under given loads. To achieve realistic results, introduce supports only when they reliably exist. By default the size of the support symbols is set to approximately $$1.5m$$. The slider with the heading **“Support”** on the **“ModelView”**-component lets you scale the size of the support symbols. Double click on the knob of the slider in order to set the value range. {% file src="/files/83vRAmjjwT4nfcbNikDe" %} {% file src="/files/EzAqJ9Dl2Xn3QWsqbS8R" %} {% file src="/files/jw9G2JVELseeyhA0CQVh" %} # 3.1.16: Support Agent Sometimes it is more convenient to define the locations of supports using geometric relationships rather than specifying node coordinates or node indices directly. This is where the *Support Agent* components are useful.

Fig. 3.1.16.1: Definition of supports via a Support Agent-component.

Figure 3.1.16.1 shows a Support Agent component. The inputs **Plane**, **Ct**, **Cr**, and **Dofs** have the same meaning as in the Support component described in section [3.1.15: Support](/3-in-depth-component-reference/3.1-model/3.1.16-support). These inputs allow you to define geometric conditions for placing supports: * **ToElemIds**: IDs of elements whose nodes may receive supports. If left empty, all elements in the model are considered eligible. Regular expressions may be used for refined selection. * **ToGeom**: A list of geometric objects—such as points, planes, curves, breps, or meshes—at which supports should be placed. * **InGeo**: A list of closed geometric objects—such as curves, breps, or mesh volumes—inside which supports may be added. When multiple inputs are provided, the placement conditions are combined using logical **AND**. {% file src="/files/hFQXj3N5Cp9thVNuUa7u" %} # 3.1.17: Disassemble Support The Disassemble Support component breaks down an incoming support, exposing its properties for for further processing and recomposition as yet another support.

Fig. 3.1.17.1: The properties of a support get exposed via a Disassemble Support component.

Figure 3.1.17.1 illustrates the disassembly process. Before model assembly, node indexes are undefined, indicated by the value “-1” in the Node Index output (“Ind”). When used after model assembly and in combination with a Disassemble Model component, “Ind” returns the index of the node to which the support is attached. {% file src="/files/ZijpQoRGRn2JKsMawjN2" %} # 3.2: Load This chapter contains information regarding defining loads, disassembling mesh loads and setting prescribed displacements for supports. # 3.2.1: General Loads Currently, Karamba3D offers the following general types of loads: gravity, point-load, point-displacement, imperfection, pretension, temperature loads, constant mesh loads, variable mesh loads, and prescribed displacements at supports. Additional options exist for beam and truss elements (see section on Beam Loads). The types of loads described in this section apply to all types of elements. An arbitrary number of point loads, mesh loads, etc., and one gravity load can be combined to form a load case, and any number of load cases may exist. Fig. 3.2.1.1 shows the definition of loads using the **“Loads”** multi-component. Each load-component features an "LCase" input-plug which serves to define the load-case to which the corresponding load belongs to. The default value is "LC0". See section [3.2.5.1](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations/3.2.5.1-load-case-combinator) for load case naming conventions. At the bottom of the **“ModelView”** component (see section 3.6.1), there is a drop-down list (unfold it by clicking on the **“Result Selection”** menu header) that can be used to select individual load cases for display. Select **“–all–”** to view all existing load definitions of all load cases simultaneously. Use the force slider to scale the size of the load symbols (double-clicking on its knob allows you to change the value range and its current value).

Fig. 3.2.1.1: Simply supported beam with six loads.

{% file src="/files/6nJwqDlYeT286m2G4rLk" %} ## **Gravity** When you place a **“Loads”** component on the canvas, it defaults to the setting described below. Each load case may contain zero or one definition for the gravity vector. This allows you to simulate effects such as earthquakes by applying a certain amount of gravity in a horizontal direction. For example, in Vienna, which experiences medium earthquake loads, this equates to approximately 14% of gravity that a building must withstand horizontally. In areas with severe earthquake loads, this can rise to 100%, although the value also depends on the stiffness properties of the structure and underlying soil. Gravity applies to all active elements in the structural model for which the specific weight "gamma" (see section 3.4.1) is not zero. The gravity vector defines the direction in which gravity shall act. A vector of length one corresponds to gravity as encountered on Earth When working in SI-units Karamba3D assumes a value of $$10m/s^2$$ for the acceleration of gravity. In case of Imperial units $$g = 9.8066352 m/s^2$$ is used. Otherwise the conversion from pound mass to pound force does not work. The value of $$g$$ can be set by selecting "Karamba3D/Settings/Edit User Settings" in the Grasshopper menu. {% file src="/files/brx398ZZT2ZvJP1ohSdn" %} ## **Point-Load** The **“Point-Load”** component allows you to define loads on nodes. These loads can be attached by node index or coordinate. To find out the index of a specific node, enable the **“node tag”** checkbox in the **“ModelView”** component. Provide a corresponding list of items into the **“Pos|Ind”** plug, similar to the **“Support”** component. See section 3.1.6 for information on how to predefine the index of specific nodes or node positions. Point loads can be either forces or moments. Input a force or moment vector into the **“Force”** or **“Moment”** input plug. Its components define the force or moment in the global x, y, and z directions. When set to **“True”**, the boolean input **“Local?”** makes loads and moments follow the nodal rotations in large displacement calculations (see section [3.5.4](/3-in-depth-component-reference/3.5-algorithms/3.5.4-analyze-large-deformation)). Plugging a point load into a panel component provides the following information: node index or position where the load is applied, force vector, moment vector, the number of the load case to which it belongs, and whether the load is tied to the nodal coordinate system. Be cautious with nodes where only truss or membrane elements are attached, as these nodes do not possess rotational degrees of freedom. A moment load will therefore have no effect and will be automatically removed from the structure. For more information on loads and some typical values, see section [A.2.3](/appendix/a.4-background-information/a.4.3-tips-for-designing-statically-feasible-structures). {% file src="/files/rt4CYEE9JqCwei0NhMzJ" %} {% file src="/files/x4ZCYkecIdy7tZCIOU8F" %} ## **Point-Displacement** Supports as described in section [3.1.16](/3-in-depth-component-reference/3.1-model/3.1.16-support) specify displacement boundary condition at nodes: They set the corresponding displacement degree of freedom of a node to zero. In addition to this a **“Point-Displacement”**-load lets you preset arbitrary displacements at supports. Fig. 3.2.1.2 shows a beam with prescribed, clockwise rotations at both endpoints. {% hint style="info" %} The term “displacement” as used throughout this manual includes translations and rotations. {% endhint %} As fig. 3.2.1.2. shows a **“Point-Displacement”** always needs to be accompanied by a corresponding **“Support”**-definition - otherwise a warning on model assembly occurs. Supports where displacement conditions apply can be selected via node-index or nodal coordinates. In order to find out the index of a specific node enable the **“node tag”**-checkbox in the **“ModelView”**-component. Input-plug **“LCase”** lets you set the index of the load-case in which displacements shall have a specified value. The default value is “LC0”.

Fig. 3.2.1.2: Deflection of a beam under predefined displacements at its end-supports.

{% file src="/files/BrbCOG5eUw47ALwnNQVk" %} The **“Trans”**- and **“Rot”**-input-plugs expect vectors. They define nodal translations and rotations in the coordinate system defined by the nodal support. Translations are to be given in meter (or feet), rotations in degree. The X-component of the rotation vector describes a rotation about the coordinate systems X-axis. A positive value means that the node rotates counterclockwise if the X-axis points towards you. Analog definitions apply to rotations about the Y- and Z-axis. Karamba3D is partly based on the assumption of small deflections. Thus, be aware that large, prescribed displacements and rotations give rise to incorrect results in case of geometric linear calculations. For approximating effects due to large displacements see e.g., section [3.5.4](/3-in-depth-component-reference/3.5-algorithms/3.5.4-analyze-large-deformation). Displacements can only be prescribed if the corresponding displacement degree of freedom is removed from the structural system. This means you have to activate the corresponding button in the Conditions-section of the **“Support”**-component. The first three buttons stand for translations the last three for rotations. {% hint style="info" %} Only those components of the **“Trans”**- and **“Rot”**-vectors take effect which correspond to activated supports. {% endhint %} ## **Initial Strain-Load** Karamba3D allows you to define initial strains. Fig. 3.2.1.3 shows a beam with both ends fixed, subject to a positive initial constant strain and curvature. The unit of dimension of the pretension which gets fed into the **“Eps0”** plug is $$mm/m$$. {% hint style="info" %} A positive value means that the element elongates. {% endhint %} ![ Fig. 3.2.1.3: Member under initial strains fixed at both ends and support reactions.](/files/-MCkEaSYA1_oYgeDNapB) Applying initial strain to an element is not the same as applying a pair of opposite forces or moments at its endpoints: In case of initial strain, the axial force in the element depends on its boundary conditions: If the structure to which it connects is very stiff then the resulting axial force will be $$N = -\epsilon \_0 \cdot A \cdot E$$. In fig. 3.2.1.3 the supports are rigid, the elements cross section $$A = 25 cm^2$$, Young’s Modulus $$E = 21000 kN/cm^2$$ and $$\epsilon \_0 = 0.00015$$. This results in an axial force of $$N = -78.75 kN$$ and shows up as horizontal support reactions. When the rest of the structure does not resist, then a pretension-load merely results in lengthening or shortening the corresponding element. The **“Kappa0”**-input is a vector of curvature values with respect to the local element axes. A positive component value signifies an anti-clockwise rotation about the corresponding axis. The input plug **“ElemIds”** defines the elements where the load acts and **“LCase”** the load-case. {% file src="/files/cXMsSAVMWrTDZAS1HrA7" %} {% file src="/files/3ttiquL3FkQRAtmw4eNn" %} {% file src="/files/t1nMWAkcHcuv59mvgZ01" %} {% file src="/files/hiNlJcVrOUPOsihaZS6N" %} {% file src="/files/qzxW4MPHKycemdHTp9qt" %} *Additional examples can be found in the Grasshopper main tab under Karamba3D > Help > Examples > Local Examples > Loads.* ## **Temperature-Load** The definition of temperature loads works analogously to defining pretension loads (see section [3.2.1](/3-in-depth-component-reference/3.2-load/3.2.1-loads#initial-strain-load)). The coefficient of thermal expansion (see section [3.4.1](/3-in-depth-component-reference/3.4-material/3.4.1-material-properties)) characterizes the response of a material to temperature changes.\ "T" represents a uniform temperature change over the cross section, "$$\Delta$$T" a temperature gradient over the cross section. The input vector refers to the local element coordinate system and specifies changes about the corresponding axes. ![ Fig. 3.2.1.4: Temperature load on a member which is fixed at both ends](/files/-MCkEaS_R2NRIYOf4Ad7) ## **Mesh-Load: Const and Variable** A **Mesh Load** can be used to apply area loads to a structure—such as wind pressure on a façade, occupancy loads on a floor slab, or additional dead weight on a roof. The advantage of Karamba3D’s mesh loads is that the loaded surface—any arbitrary Grasshopper mesh—does *not* need to be part of the finite element model itself. Instead, the load defined on the mesh is transferred to the structural model using a shortest‑distance–based algorithm. If you want to know exactly how that works, read on; otherwise, feel free to skip the remainder of this paragraph. To derive nodal loads and distributed beam loads from surface loads, the following steps are performed: 1. **Face Resultants**\ Karamba3D first calculates the resultant load acting on each face of the input mesh. This load is then evenly distributed among the face’s three or four corner vertices. 2. **Transferring Vertex Loads to Structural Nodes**\ Next, these vertex loads are mapped to the structural nodes. For this purpose, auxiliary “helper” nodes are created along beam axes at intervals equal to one‑third of the mesh’s average edge length. Each mesh vertex transfers its load to the nearest structural node or helper node. If several nodes lie within the LDist radius specified in the Assemble component, the vertex load is split among them according to the inverse of their distances from the vertex. 3. **Converting Helper Loads into Beam Loads**\ The loads collected by the helper nodes along each beam are grouped into segments. Loads within each segment are summed and converted into equivalent trapezoidal distributed loads. A coarse mesh can yield a poor local load distribution. In Fig. 3.2.1.6, for example, the closest points from the vertices are the beam’s end nodes and the middle helper node, which results—one load per element—in a uniform line load. It is important to note that this method for converting mesh loads into nodal and element loads does *not* consider bending moments caused by offsets between mesh vertices and structural nodes. The approach implicitly assumes that the load‑receiving surface is centrally placed and rigid in bending. As a consequence, bending moments caused by overhanging or cantilevered surfaces are not captured. ### Mesh The **“MeshLoad”** component is used to transform surface loads into equivalent node or element loads. This allows for the definition of live loads on floor slabs, moving loads on bridges (see the example **“Bridge.ghx”** in the examples collection on the Karamba3D website), snow on roofs, wind pressure on facades, etc. The mesh where the load is applied and the underlying structure do not need to be connected. The mesh needs to be fed into the **“Mesh”** input plug. ### Vec There are two types of mesh loads: * **“MeshLoad Const”**: for loads that are constant throughout the mesh. * **“MeshLoad Var”**: for setting specific load values for each face of the mesh. These two variants differ in the data structure expected at the input **“Vec”** and **“Vecs”** respectively: either a single vector for specifying a constant load or a list of vectors. In the latter case, the list items are applied to the mesh faces based on the longest list principle. In what follows, the **“MeshLoad Const”** variant will be depicted, but the information applies to **“MeshLoad Var”** as well. Fig. 3.2.1.6 (left side) shows a simply supported beam and a mesh consisting of two rectangular faces. Each face covers one half of the beam and has a width of 1 m perpendicular to the beam axis. With a distributed load of 1 kN/m² in the negative global Z-direction, a uniformly distributed load of 2 kN/m results.

Fig. 3.2.1.6: Simply supported beam with line-loads from a mesh load.

### Pos To define structure nodes where equivalent point loads may be generated, plug a list of their coordinates into the **“Pos”** plug. These need to correspond to existing nodes; otherwise, the **“Assemble”** component turns red. Offending nodes will be listed in its run-time error message. By default, all points of the structure are included. Uncheck **“Point loads”** to avoid point loads. ### ElemIds With the **“ElemIds”** input plug, groups of elements can be specified on which equivalent loads shall be generated. As shown in figures 3.2.1.7. and 3.2.7.2. this can be used to impose the span-direction of the load-application. By default, all beams of the model are included. To exclude beam loads, uncheck the **“Line loads”** button in the **“Generation”** submenu.

Fig. 3.2.1.7: A mesh-load which acts on all four boundary beams named "YLines" and "XLines".

Fig. 3.2.1.8: The same mesh-load as in fig. 3.2.1.7. this time actiong only on the beams identified as "XLines".

The figures 3.2.1.7 and 3.1.2.8. show a similar setting as in fig. 3.2.1.6. The difference lies in the refined mesh with more vertices along the beam axis. ### LCase Set the **“LCase”**-input to the name of the load case in which the surface load shall act. ### Orientation The right side of fig. 3.2.1.7 shows what data the **“MeshLoad const”**-component collects: The input-plug **“Vec”** expects a vector which specifies the surface load. Its physical unit is kilo Newton per square meter $$kN/m^2$$. The orientation of the load-vector depends on the checkbox selected under **“Orientation”** (see also fig. 3.2.1.8): * **"local to mesh”**: The local coordinate system for loads corresponds to that given in section [3.1.12](/3-in-depth-component-reference/3.1-model/3.1.14-orientate-element). The local x-axis is parallel to the global x-direction unless the mesh-face normal is parallel to the global x-direction, in which case the local x-axis points in the global y-direction. The local z-axis is always perpendicular to the mesh-face, with its orientation depending on the order of the vertices. A surface load with components only in the Z-direction acts like wind pressure or suction. * **“global”**: The force-vector is oriented according to the global coordinate system. This makes the surface load behave like additional weight on the mesh plane. * **“global proj.”**: The force vector is oriented according to the global coordinate system, with the surface load distributed over the area resulting from projecting the mesh faces to global coordinate planes. This simulates the action of snow load. ![ Fig. 3.2.1.8: Orientation of loads on mesh: (a) local; (b) global; (c) global projected to global plane.](/files/-MCkEaSl5Yc1PDDOYQ5B) ### Generation By default, the **“MeshLoad const”**-component creates point- and line-loads. The radio-buttons in the submenu **“Generation”** can be used to disable the first or the latter.\ The **"Loads/Elem"**-input lets you control the number of equivalent trapezoid loads created per beam from the mesh-load. If the value is too large with respect to the resolution of the loaded mesh dicontinuous load patterens may arise. However, this does not influence the resultant load per beam, only the local load distribution. {% hint style="info" %} Starting with Karamba3D version 3.1.60309, the behavior of the MeshLoad component has changed slightly compared to earlier releases—and this affects MeshLoad components in older definitions as well. When the *LineLoads* option is enabled, no point loads are generated at the element endpoints anymore. Instead, those endpoint forces are now incorporated directly into the element’s line loads. {% endhint %} {% embed url="" %} {% file src="/files/LGp6L7vNPt9w0w8PueWE" %} {% file src="/files/KCzbVXYAycmv0Md4B4Y6" %} # 3.2.2: Beam Loads The group of loads described in this section works on beams and - with some limitations - on truss elements. The latter are considered as shear rigid with hinges at their ends: Beam-loads on trusses transform into transverse forces at their end-points.\ All beam load-components feature the "BeamID"- and "LCase"-input-plug: * "BeamId" determines the element on which to apply the load. A regular expression like '&"id1"|"id2"|...' selects multiple elements. * "LCase" specifies the name of the load's load-case. The parameter "t" serves to specify the load-position along elements: t=0 refers to the starting point, t=1 to the end-point. Karamba3D offers these types of beam-loads: ## Concentrated Load Use the 'Concentrated'-option to specify forces and moments at arbitrary positions along the element. Vectors 'Force' and 'Moments' let one set the direction and size of the corresponding external loads. Fig 3.2.2.1 shows a cantilever with a span of 3m under a concentrated transverse load of 1kN. The load sits at a distance of 0.75 x 3.00 = 2.25m from the supports and causes a linear bending moment diagram. The radio buttons in the sub-menu 'Orientation' determine the reference coordinate system of the 'Force'- and 'Moment'-vectors: either local to the element or global.

Fig 3.2.2.1: Cantilever beam with concentrated transverse load: support reactions and My-diagram

{% file src="/files/UfQJeYqcbo1tv4OEf1WH" %} {% file src="/files/TsLptDHII8178Z9Saebp" %} ## Block Load Fig. 3.2.2.2 shows the application of uniformly distributed transverse loads an on a cantilever beam. The span of the cantilever is two meters. The loads act between t0=0.25 and t1=0.75. With the default values t0=0 and t1=1 distributed block-loads cover the whole beam length. The graphical output in fig. 3.2.2.2 shows the support reactions well as the bending-moment-diagram (in orange) for My. In combination with the radio buttons in sub-menu "Orientation" the vectors at the input-plugs "Force" and "Moment" sets the external loads to be applied - see fig. 3.1.2.8 for the meaning of the different types of orientation.

Fig. 3.2.2.2: Cantilever beam with constant transverse load: support reactions and My-diagram

There are limitations for distributed rotational loads: In case they rotate about the element's local Y- or Z-direction they need to be specified over the whole length. This does not apply to distributed torsional moments when the Orientation is set to 'Local to element'. The input-plug **“BeamId”** receives the identifier of the beam on which the load shall act. Multiple beams can be specified via a regular expression (e.g. '&"id1"|"id2"...'). See section [3.1.6](/3-in-depth-component-reference/3.1-model/3.1.6-create-linear-element/3.1.6-line-to-beam) for how to attach identifiers to beams. By default beams are named after their index in the FE-model. There are three options for the orientation of the load: **“local to element”**, **“global”** and **“global proj.”**. Their meaning corresponds to the options available for mesh-loads (see fig. 3.2.1.8). The input-plug **“LCase”** which designates the load case defaults to “0”. {% file src="/files/0aDBMlfsxsmnjuJfL3YH" %} {% file src="/files/72kMOoVvhEURFE2UL7ZP" %} {% file src="/files/WQnjQSbgGr4bf6bSbFDy" %} {% file src="/files/pkrRIJO83nxTc88gHgT2" %} {% file src="/files/nDzSMXWZgRFm4hLYOWVJ" %} ## Gap Load With Gap-loads it is possible to prescribe rotation or displacement discuntinuities at arbitrary element-positions. When using unit vectors, the resulting displacement shapes represent influence lines (see e.g. ). Fig 3.2.2.3 shows a fully fixed beam under a translational gap load of 0.1m in local z-direction. The displaced shape shows, that in order to maximize the shear force Vz at the location of the gap-load one should place transverse external loads either to the left or right side of the gap only.

Fig. 3.2.2.3: Fully fixed beam with gap-load wz=0.1[m]

{% file src="/files/6PgtI2SZR3qkkKQpRiyi" %} {% file src="/files/rCaU7mdlW6e5W4szv0sh" %} {% file src="/files/wDmacmNQsZFta7fiRqqG" %} ## Imperfection There exists no such thing as an ideally straight column positioned perfectly vertical. The deviation of a real column from its ideal counterpart is called imperfection. This term comprises geometric and material imperfections. The **“Imperfection”** variant of the **“Loads”** multi-component allows to specify geometric imperfections (see fig. 3.2.2.4). **“psi0”** takes the vector of the initial inclination of the beam axis about the axes of the local element coordinate system in radians. With **“kappa0”** one can specify the initial curvature. A positive component of curvature means that the rotation of the middle axis about the corresponding local coordinate axis increases when moving in longitudinal beam direction. Small inclinations and curvatures are assumed.

Fig. 3.2.2.4: Imperfection Load

\ In fig. 3.2.2.4 one can see displacements and reaction forces of an initially straight beam with a second order theory normal force of $$N^{II} = 10 kN$$, an initial inclination of $$0.1 rad$$ about the local y-axis and an initial curvature of $$0.1 rad/m$$. Imperfection loads do not add directly to the beam displacements. They act indirectly and only in the presence of a normal force $$N^{II}$$. An initial inclination $$\psi\_0$$ causes transverse loads $$\psi\_0 \cdot N^{II}$$ at the elements endpoints. An initial curvature $$\kappa\_0$$ results in a uniformly distributed line load of magnitude $$\kappa\_0 \cdot N^{II}$$ and transverse forces at the elements endpoints that make the overall resultant force zero. For details see e.g. [\[10\]](broken://pages/-MCkEPufKvmRk8DHQDJm). {% file src="/files/BeIdeUfq0FTdgdYSn0Lt" %} ## Polylinear Load Distributed loads consisting of an arbitrary number of linear segments can be defined via the "Polylinear" option (see fig. 3.2.2.5). The input-plug "Dir" specifies the direction of the load. The vector supplied there gets scaled to unity and has no impact on the load magnitudes. The latter get set by lists of values connected to the "Force" or "Moment" inputs. For each value supplied there needs to be a corresponding location parameter "ts". In case there are more location parameters than force or moment-values the longest list principle applies like in fig. 3.2.2.5. ![Fig. 3.2.2.5: Cantilever beam under poly-linear transverse distributed load](/files/-MgoaLxnxqzA-0e1Kpj8) In case of subsequent identical t-values and different corresponding load-values a step in the distributed load results. {% file src="/files/25y6JtOWHeyqu0VszhvB" %} ## Trapezoidal Load The 'Trapezoidal'-option makes it more convenient to specify trapezoidal loads as compared to 'Polylinear'. Teh parameter input is simlar to that of block-loads. The four parameters t0, t1, t2 and t3 specify the trapezoids shape. ![Fig. 3.2.2.6: Cantilever beam under trapezoidal transverse distributed load](/files/-MgoeRFPJ3VXaje65MKy) {% file src="/files/hsKfScRK9HnBnZ4VA9br" %} # 3.2.3: Disassemble Mesh Load The procedure for distributing mesh-loads on a structure can be computationally intensive. The “Disassemble Mesh Load” component allows for freezing a mesh-load, enabling the return of point- and element-loads for reuse with another structure or for exporting models to SAF (refer to Figure 3.2.3.1 and Section 3.8.3). Point loads are defined using their position, while element loads refer to their elements via element index. To reuse the latter, the corresponding element indexes of the new and old model need to match. From the list of loads provided via the **“Load”** input plug, mesh loads associated with the load case specified in the **“LCase”** input plug are disassembled. An empty string means selection of all load cases, and regular expressions starting with "&" enable flexible selection. **Outputs:** * **Pload:** Outputs point-loads. * **ELoad:** Outputs beam-loads. * **Mesh:** Outputs the mesh underlying the disassembled MeshLoad. * **Load:** Outputs all loads not of type MeshLoad or not belonging to the selected load-case.

Fig. 3.2.3.1: The “Disassemble Mesh Load”-component splits mesh-loads into point- and element-loads, returns the mesh and the list of loads which are not of type MeshLoad.

{% file src="/files/o0nYIv3jlI9oTeCqyAeC" %} {% file src="/files/ZBrTbtrXvg2cWX6DpaP4" %} # 3.2.4 Load-Case-Combinations The proper set up of loads is decisive for real world structural design. Most of the time when buildings collapse, they do so not because of a wrong number behind a comma but because someone forgot about a load. What makes it hard to write about load scenarios is the fact that there is no 100% uniform terminology when it comes to the more detailed aspects of describing them. In Karamba3D there are three levels for describing load scenarios: 1. Loads 2. Load-cases 3. Load-case-combinations **Loads:** These are what you get of a Loads-component. This can be a point-load defined on node of the structure, a beam-load or a distributed load on a shell. Each load can specify a load-case to which it belongs. By default, that is "LC0" which stands for load-case zero. \ **Load-cases:** The 'Assemble'-component constructs the load-cases on the basis of the given loads. Load-cases specify sets of loads that belong together and occur at the same time. An AND-relation exists between the loads of a load-case. Be aware that misspelling a load-case name at a load-component does not entail an error message but the creation of a new load-case. Loads in a load-case may be scaled with a value to e.g., reflect a given probability of occurrence. By default, this factor is unity. **Load-case names:** A valid load-case name may include letters, digits, and the underscore character (\_). Additional characters such as '+', '-', '#', '!', or '"' can also be used starting from the second character, but this requires specific handling: * **Combination Expressions:** When utilizing load-case names containing these special characters in a combination expression, they must be enclosed in single or double quotation marks (`'` or `"`). * **Export to Formats (e.g., SAF):** During export, certain special characters are automatically transformed. For instance, '+', '-', and '\*' are replaced with "plus," "minus," and "x," respectively, with underscores used to separate these terms from the rest of the name. Load-cases with names beginning with an underscore ("\_") are excluded from the default set of load-cases. As a result, these load-cases are not automatically included in calculations performed by the Analysis component when no specific load-case is selected at the corresponding input plug. **Load-case-ordering:** When managing a list of load cases and load-case combinations, arranging them by importance simplifies the workflow. The order in which results are selected in the "**ModelView"** component or when disassembling a model follows the sequence in which the loads and load-case combinations are provided to the "**Assemble"** component. In some cases, it is beneficial to predefine this order using a list of load-case names: When a string is entered into a load container, it creates a dummy load. While this dummy load does not carry an actual load, it serves as a placeholder to establish the desired load-case order within the model. **Load-case-combinations:** They express an OR-relation between several load-cases. They do not occur at the same time. {% hint style="info" %} The components ["Analyse"](/3-in-depth-component-reference/3.5-algorithms/3.5.1-analyze), ["Analyse ThII"](/3-in-depth-component-reference/3.5-algorithms/3.5.2-analyzethii) and ["Export Model To SAF"](/3-in-depth-component-reference/3.7-export/3.8.3-export-model-to-saf) by default act on all load-cases and load-case-combinations present in the model. In order to exclude a load-case or load-case-combination from this default list, append "\_" at the beginning or end of the load-case or load-case-combination name. {% endhint %} Variable loads potentially form many different patterns, so load-case-combinations may comprise large numbers of load-cases. When doing e.g., cross section optimization one needs to consider in the worst case all load-cases in all points of the structure since the governing loads can be different for different locations. In practice this formidable task reduces when dealing with well-behaved materials like steel and structures where the effect of loads can be computed separately and then linearly superimposed. Currently Karamba3D does not fully utilize the latter possibility of reducing computational effort in case of linear calculations: It sets up a load-vector for each load-case. Further improvements will be realized via result combinations in the next release of Karamba3D.\ \ The following chapters present the components that Karamba3D provides for setting up, managing and querying load-case-combinations. {% file src="/files/nQ6fq3IJX8RNpGa7tn1l" %} Example which demonstrates how to exclude load-cases from the default selection. {% endfile %} {% embed url="" %} # 3.2.5.1 Load-Case-Combinator The "Load-Case-Combinator"-component takes a list of strings which contain combination rules and transforms them into load-combinations (see Fig. 3.2.5.1). The names are expanded until no further substitution is possible.

Fig. 3.2.5.1.1: Creation of Load-Combinations via the 'Load-Combination'-component.

The "**Load"**-output consists of a "Load-Combinations"-object which (along with others) can be plugged into the "Load"-input of the "Assemble"-component on model setup. Its text representation lets the user check whether the expanded rules conform what is intended. The load-combinations are listed alphabetically by their names. A load-case-combinations object may contain several combinations whose names get output at the "**Names"** output-plug. For each of these the "**Nums"**-output delivers the number of load-cases contained in each load-case-combination. ### Syntax of load combination rules A quick guide to the syntax involved in formulating load case combinations shows up when one lets the mouse-pointer hover over the 'Rules'-input. Here the long version: * Combination rules consist of a combination's name on the left-hand side and equals sign and a combination expression. * If a combination name shows up multiple times on the left-hand side, the corresponding expressions are combined via an OR-relation. * Spaces may be introduced for better readability but do not have any effect. * Everything that follows "#" is a comment (see fig. 3.2.5.1). * Lines may be empty (see fig. 3.2.5.1.4)

Fig. 3.2.5.1.2: Two rules with plus and minus operators.

#### Combination expressions * Combination expressions on the right-hand side of a rule consist of a series of load-case- or load-combination-names. Each of these may be prefixed by a factor. * Combination names and references to these may occur in any order. In fig. 3.2.5.1.4 "s" could have been defined after "ULS". Circular references lead to an error message. * A factor in front of a name may be a number or an expression which consists of braces and two numbers separated by "|". The latter symbolizes a factor which can be the first or the second number. This allows to express variable loads via "(0|number) \* name" (see fig. 3.2.5.1.2). In the context of combination via '&' the first number plays the role of the upper limit; the second number sets the lower limit.

Fig. 3.2.5.1.3: Combination via leading factor permutation.

#### Combination operators Expressions get evaluated from left to right. The factored names can be linked via these operators listed in ascending priority: * "|" corresponds to "or". * "+" and "-" symbolize addition and subtraction. * "&" combines terms using permutated leading factors (see fig. 3.2.5.1.3). The numbers in front of a name are interpreted as upper and lower limits. In case of factors with only one number it is assumed to be the upper and lower value. In each resulting load-case one of the terms enters first with its upper value, the others join the load-case with their lower value as multiplication factor. * Braces "(" and ")" can be used to override the default priority of operators (see fig. 3.2.5.1.4).

Fig. 3.2.5.1.4: Braces can be used to group operator.

#### Simpified Regular Expressions On the right-hand side of a combination expression simplified regular expressions may be used. They end with "$" or "\*" and match all names that are identical up to the "$" or "\*" respectively. So "wind$" matches for example "windNorth" and "windSouth" but not "wWest". All items that match get combined in an OR-relation. Simplified regular expressions either match names of load-cases or load-case-combinations. The latter take precedence over the former. Since load-case names are only known at the time of model assembly the matching of simplified regular expressions for load-case names takes place at that stage. The application of simplified regular expressions allows to categorize actions via their names and to formulate generally applicable combinations rules. In fig. 3.2.5.1.5 the load-cases "w11", "w22", "s11" and "s22" play the role of load-cases that could have been supplied via load-components. "w" and "s" use regular expressions to catch all load-cases that start with "w" and "s". In case input lines 0 to 3 would be missing in Fig. 3.2.5.1.5. the output on the left side would contain "w$" and "s$" and their resolution into load-case names would be postponed to the model assembly stage.

Fig. 3.2.5.1.5: Simplified regular expressions can be used to formulate generally applicable combination rules.

{% file src="/files/wOXUfMenwXSdyz3jV4Pi" %} # 3.2.5.2 Disassemble Load-Case-Combinaton Many result components when queried for the minimum or maximum result for a load-case-combination at a specific position return the index of the corresponding load-case within the load-case-combination. This index can be used in combination with the "**Disassemble Load Case Combination**"-component to retrieve information regarding the load-case in question.

Fig. 3.2.5.2.1: Retrieval of information about a load-case within a load-case-combination via the 'Disassemble Load Casse Combination'-component.

{% file src="/files/su1fPHlmoF5Kr2Uantk4" %} Figure 3.2.5.2.1 shows the component in action: After providing a model which contains the load-case-combination (LCC) in question its name may set via the "**LCCName**" input plug or selected via the drop-down menu at the bottom. The former overrides the latter.\ Load-cases within a load-case-combination are indexed starting at zero. Supplying "3" to input "**LCInd**" thus results in retrieval of the fourth load-case. On the output side the model emerges unchanged, "**LCText**" outputs the textual representation of the load-case in question, "**LCNames**" the load-case names of which it is composed, "**LCFactors**" the factors with which they enter the load-case. # 3.2.5.3 Load-Case-Combination Settings The "Load Case Combination Settings"-component lets you specify the way Karamba3D analyzes load-case combinations. The name of the load-case combination to which the settings apply can be supplied via the "**LCase**" input-plug and defaults to "LC0". Regular expressions starting with '&' and simplified regular expressions ending with '$' allow to select multiple load-case combinations at once.

Fig. 3.2.5.3.1: Options for small displacement calculation with and without update of N^{II}-forces.

### Type of Calculation The component's drop-down menu serves to select the way how a load-case combination shall be processed by components further down the data-stream. With nothing specified, the "[Analyze"-component](/3-in-depth-component-reference/3.5-algorithms/3.5.1-analyze) performs for load-combinations small displacement calculations without iteratively updating second order theory forces (called $$N^{II}$$). Here some explanations in case you are not familiar with the concept of first and second theory calculations in structural computations: * Small displacement calculations imply that the impact of transverse displacements on the elongation of elements and thus axial force can be neglected. This assumption normally holds if a structure's maximum displacement is roughly less than halve the cross-section height. * Under the small displacement assumption equilibrium of forces in a structure can be calculated formulated for the undeformed or deformed structure. The former approach is called first order theory (Th. I) the latter second order theory (Th. II). Second order theory covers effects like buckling of beams and shells or stiffening of ropes via pre-tension. Compressive axial (think of beams) or in-plane normal forces in shells soften a system and increase existing bending moments, tensile forces stiffen a system and reduce bending moments (see also [\[10\]](/appendix/bibliography)). The contribution of second order theory effects to the system stiffness is called the geometric stiffness. The influence of compressive forces on displacements and cross section forces may be neglected as long as their absolute value is less than 10% of the buckling load. * Karamba3D differentiates between normal forces $$N$$which cause stresses in the cross-section and $$N^{II}$$-forces which cause second order theory effects and impact a structure's stiffness.\ At first sight this concept seems weird. How can there be two kinds of normal forces in the same beam? Well, in reality there can’t. In a computer program it is no problem: stresses get calculated as $$\sigma = N/A$$ and $$N^{II}$$is used for determining second order effects only. The advantage is that in the presence of several load-cases one can chose for each element the largest compressive force as $$N^{II}$$. This gives a lower limit for the structure's stiffness. A re-evaluation of the load-cases using these $$N^{II}$$-values leads to a structural response which is too soft. However, the different load-cases may then be safely superimposed. On can use the **“NII”** button in submenu **“Tags”** of the **“ModelView”**-component to display $$N^{II}$$-forces #### The Small Displacements Option Selecting the 'Small Disp.' option in the drop-down menu (see fig. 3.2.5.3.1) tells the ["Analyze"-component](/3-in-depth-component-reference/3.5-algorithms/3.5.1-analyze) to perform a single calculation step for the load-case-combination without updating $$N^{II}$$. The input-plug 'InitialNII' determines whether user-defined $$N^{II}$$-values shall be considered or not. It defaults to true. Use 'Modify Element'-components (see section [3.1.8: Modify Element](/3-in-depth-component-reference/3.1-model/3.1.10-modify-element)) for specifying initial $$N^{II}$$-values and thus setting an initial geometric stiffnesses. #### The Small Displacements Th. II Option This option lets the 'Analyze'-component apply an iterative procedure for updating the $$N^{II}$$-values based on the normal forces $$N$$. In case of statically indeterminate systems these two quantities influence each other. However, in case of reasonably stable structures their values rapidly converge. These input-values can be provided: | **"InitialNII"** | True if the initial value of $$N^{II}$$from element definitions shall be used in the first equilibrium iteration. In case of MaxIter > 1 the initial $$N^{II}$$ values get replaced by the current normal forces. | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **"CombiNII"** | If set to **True**, the minimum normal force across all load cases is used for each element, resulting in a single stiffness matrix applied to all load cases. This approach can lead to overly conservative results. If set to **False**, a separate stiffness matrix is computed for each load case based on its corresponding normal force, producing less conservative results but requiring greater computational effort. | | **"NoTenNII"** | Tension forces increase a structure’s stiffness. When **NoTenNII** is set to **True**, the value of $$N^{II}$$ is restricted to negative values by default. The upper limit of $$N^{II}$$ can be adjusted to any value via the **niiLt0Limit** parameter in *karamba.ini*. | | **"NoComNII"** | Compressive forces decrease a structure’s stiffness. For membranes, this can cause wrinkling and thus local buckling. When **NoComNII** is set to **True**, $$N^{II}$$ is restricted to positive values by default. The lower limit of $$N^{II}$$ can be customized via the **niiGt0Limit** parameter in *karamba.ini*. | | **"RTol"** | The determination of $$N^{II}$$ is an iterative process. The value of **“RTol”** is the upper limit of resultant displacement-, force- or $$N^{II}$$-increments divided by the corresponding absolute value. | | **"MaxIter"** | Supply here the maximum number of iterations for determining $$N^{II}$$. The default is 50. In case **“RTol”** cannot be reached within the preset number of iterations the component turns orange. | Setting "**CombiNII**" to true (the default) or false impacts the character of results reached and speed of calculation. These are the advantages and liabilities of enabling "**CombiNII**": * Using the minimum $$N^{II}$$of all load-cases results in a lower limit of the geometric stiffness. Thus, the structure behaves too soft. The resulting cross section forces and displacements will be overestimated. * As compared to the more precise procedure available with 'CombiNII' set to 'false', convergence of $$N^{II}$$ will be faster: The stiffnessmatrix needs to be assembled and solved only once per iteration step for the load-case-combination as a hole. The more precise procedure with individual $$N^{II}$$-values necessitates a separate stiffness matrix for each load-case. * With 'CombiNII' enabled, the load-case results may be linearly superimposed since they are based on the same system stiffness. # 3.2.5.4 Load-Case Properties The Load-Case Properties component can be used to define load-cases independently of loads. Besides the load-case name its action type, load type and load duration can be specified. In order to simplify the selection of these properties ValueLists can be automatically created via the component's right-click context menu under "Expand ValueLists".

Fig. 3.2.5.4.1: The Load-Case Properties components with expanded ValueLists.

Currently the ActionType, LoadType and LoadDuration properties are only used for export via SAV-files (see [3.8.3 Export Model to SAF](/3-in-depth-component-reference/3.7-export/3.8.3-export-model-to-saf)). In case of load-case combinations the durations of the combinations are derived from those of the load-cases they contain. Fig. 3.2.5.4.2 shows how load-cases of different duration get combined. After model assembly the load-case with the shortes duration determines the duration of the combination it is contained in.

Fig. 3.2.5.4.2: The load-case with the shortest duration determines the duration of the combination it is contained in.

The duration of load-case combinations can be retrieved via scripts and will be used in the future for code checking procedures based on different national building codes. {% file src="/files/ldxZEKg6gg6vqaflPcS0" %} # 3.3: Cross Section Karamba3D offers cross section definitions for beams, shells and springs. They can be generated with the “Cross Sections” multi-component. Use the drop-down list on the bottom to chose the cross section type. The dimensions of each cross section may be defined manually or by reference to a list of cross sections (see section [3.3.10](/3-in-depth-component-reference/3.3-cross-section/3.3.10-cross-section-selector)).

Fig. 3.3.1: Cantilever with four different kinds of cross sections

Cross sections can be plugged directly into the components for creating elements (**“LineToBeam”**, **“MeshToShell”**, …). Alternatively when fed into an **“Assemble”**-component (see fig. 3.3.1) they act on the elements whose identifiers match the string given via **“Elem|Id”**. In case an element is provided at the **“Elem|Id”**-input, its identifier is used for attaching the cross section to elements. A cross section added via the **“Assemble”**-component overrides a cross section provided directly at an element-creation-component. The indirect cross section specification through the **“Assemble”**-component has the advantage that elements can be specified using regular expressions. Upon assembly all element identifiers are compared to the **“Elem|Id”** entry of a cross section. In case of a match the cross section is attached to the element. An empty string – which is the default value – signifies that the cross section shall be applied to all elements. If two cross sections refer to the same element then that which gets processed later by the assemble-component wins. It makes no sense to attribute beam cross sections to shells and vice versa – Karamba3D ignores any such attempts. {% file src="/files/u5zQvqZAHs4L036LiSV6" %} {% file src="/files/c0rqpKNdrLvtuC04u9cQ" %} # 3.3.1: Beam Cross Sections Karamba3D offers five basic types of beam cross section: * circular tube – the default * hollow box section * filled trapezoid section * I-profile * ```

Fig. 3.3.1: Cantilever with four different kinds of cross section

``` {% file src="/files/kNy08lF1S3IMW8GmAwF8" %} Fig. 3.3.1 shows a cantilever with cross section properties defined directly at the **“LineToBeam”**-component. Without eccentricities defined, the beam axis always coincides with the centroid of a cross section. Changing e.g the upper flange width of an I-section therefore results in a slight movement of the whole section in the local Z-direction. In case the position of e.g. the upper side of a cross section needs to be fixed, specify an eccentricity. This can be done either via a specific component (see section [3.3.7](/3-in-depth-component-reference/3.3-cross-section/3.3.7-eccentricity-on-beam-eccentricity-on-cross-section)) or through the input-plug **“Ecce-loc”**. Provide a vector there in order to move the cross sections relative to the beam axis. The given eccentricity is relative to the local coordinate system of the beam. The resulting position of the centroid can be retrieved from the **“Disassemble Cross Section”**-component (see section [3.3.4](/3-in-depth-component-reference/3.3-cross-section/3.3.4-disassemble-cross-section)). Apart from the input-plugs that define the cross section geometry, the **“Elem|Id”**- and the **“Ecce-loc”**-input there are: | | | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **“Family”** | Each cross section belongs to a family. When doing cross section optimization (see section [3.5.8](/3-in-depth-component-reference/3.5-algorithms/3.5.8-optimize-cross-section)), Karamba3D selects only profiles that belong to the same family as the original section. Families can be composed of arbitrary section types | | **“Name"** | The identifier of a cross section – need not be unique. Enable **“CroSec names”** in **"ModelView"**s **“RenderSettings”**-submenu in order to view them. | | **“Color”** | Lets one define a color for a cross section. In order to see it enable **“Cross sections”** in submenu **“Colors”** of the **“ModelView”**-component and activate **“CroSec section”** in submenu **“Render Settings”** of the **“BeamView”**-component. | | **“Material”** | Sets the material of the cross section. Indirect material assignments via the **“Assemble”**-component override direct definition of the cross section material. | # 3.3.2: Shell Cross Sections In Karamba3D there are four different kinds of shell cross sections: | | | | ----------------------- | --------------------------------------------------------------------------------------------------------------- | | **"Shell Const”** | For shells with constant thickness and material over all mesh faces. | | **“Shell Var”** | Lets one specify the thickness and material of each face of the shell-mesh individually. | | **“ShellRC Std Const”** | This allows to specify a standard (Std) reinforced concrete(RC) cross section which is constant over the shell. | | **"ShellRC Std Var”** | The same as above but lets one choose the reinforced concrete properties differently for each element. | ## **Constant and Variable Shell Cross Sections** The components **“Shell Const”** and **“Shell Var”** only differ in the data structures expected at the inputs **“Material(s)”** and **“Height(s)”**. In case of **“Shell Const”** these are data items. The **“Shell Var”**-variant expects two lists. The descriptions below refer to the **“Shell Var”**-component. Fig. 3.3.2.1 shows a shell consisting of two elements. Triangular meshes form the basis for defining a shell geometry (see section [3.1.9](/3-in-depth-component-reference/3.1-model/3.1.7-create-surface-element/3.1.9-mesh-to-shell)) and specify the sequence of faces (i.e. shell elements). The list of element thicknesses in fig. 3.3.2.1 corresponds to that order. Be aware of the fact that meshes containing quads will be automatically triangulated. In case that there are more mesh faces than thickness specifications, the last item ($$6cm$$ in this case) acts as the default value. The same holds for the supplied list of materials. Make sure to graft the **“Materials”**- and **“Heights”**-input when you want to define a list of shell cross sections. Otherwise one cross section results where one would expect several. For the **“Shell Const”** definition no data tree manipulation is necessary in such a case.

Fig. 3.3.2.1: Shell made up of two elements with different thicknesses

{% file src="/files/zhTH68NlpFtzPOwLHDB9" %} When rendering the shell cross sections (see fig. 3.3.2.1) thicknesses get linearly interpolated between the nodes. The cross section height at each node results from the mean thickness of shell elements attached to it. The input-plugs **“Family”**, **“Name”**, **“Color”** and **“Materials”** have the same meaning as described in section [3.3.1](/3-in-depth-component-reference/3.3-cross-section/3.3.1-beam-cross-sections). ## **Constant and Variable Reinforced Concrete Shell Cross Sections** The design of reinforced concrete cross sections in Karamba3D is based on linear elastic cross section forces. The **“Optimize Reinforcement”**-component takes these and computes the necessary reinforcement assuming cracked concrete cross sections. Thus defining reinforced concrete cross sections does not alter the mechanical behavior of the structure. They rather serve as input to the reinforcement design procedure. Similar to shell cross sections there exist two variants of components for reinforced cross sections: | | | | ----------------------- | -------------------------------------------------------------------------------------------------------------- | | **“ShellRC Std Const”** | For shells with constant height, material and reinforcement. It saves the user thoughts about data trees. | | **“ShellRC Std Var”** | This component allows to specify different heights, materials and reinforcement for each face of a shell mesh. | Further below variant two will be explained. The **“ShellRC Std Const”**-component works similar to the variable-variant. The only difference are the data structures expected at the inputs.

Fig. 3.3.2.2: Shell made up of two elements with different properties

{% file src="/files/AAC6zKssWQDy463TIa4W" %} Fig. 3.3.2.2 shows the definition for a reinforced concrete shell with two faces with different thicknesses, materials and reinforcement definitions. The geometry corresponds to that of fig. 3.3.2.1. A standard reinforced concrete cross sections consists of five layers: Layer zero is the concrete cross section. The layers one to four correspond to reinforcement. The top layer (with respect to where the local z-axis points to) comes first, the bottom layer last. Their orientation with respect to layer zero is 0°, 90°, 90° and 0°. Besides the standard inputs of cross sections (**“Family”**, **“Name”**, **“Elem|Id”** and **“Color”**) the **“ShellRC Std Var”**-component offers these: | | | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **“Materials-Concr”** | Expects a list of materials to be used for the concrete cross section. The items of this list get mapped to the shell elements according to the longest list principle. “C30/37” according to Eurocode 2 represents the default concrete. | | **“Heights”** | Heights of the concrete cross sections for each shell face. The longest list principle applies. The default height is$$20cm$$. | | **“Materials-Reinf”** | List of materials to be used as reinforcement for each element – by default “BSt 500” according to Eurocode 2 with a characteristic strength of $$50 kN/cm^2$$. Again the longest list principle applies. | | **“Areas”** | Expects a data-tree with a maximum of four entries per branch. The values define the minimum reinforcement for each layer. The physical unit is centimeter. Thus the areas of the reinforcement bars need to be divided by their mutual distance in order to arrive at an equivalent plate thickness. The layer thicknesses default to $$0cm$$. | | **“Covers”** | Input here a data-tree with four values per branch. These specify the position of the reinforcement layers with respect to the upper and lower side of the concrete cross sections. Positive values give the distance from the upper, negative values the distance from the lower side towards the interior. Without any input the covers default to $$3.5cm$$, $$4.5cm$$, $$-4.5cm$$ and $$-3.5cm$$. | | **“Dirs”** | Reinforcement layers can be given an angle with respect to the local shell coordinate system. A positive value rotates in anti-clockwise direction about the local z-axis. A value of zero – which is the default – aligns the first and last layer with the local x-axis. The angle of rotation can be specified for each shell face individually. | With the input-plug **“LayerInd”** of the **“ShellView”**-component one can select specific layers for visual inspection and results retrieval. {% file src="/files/xlkKeJ963ZsCCtgev2k1" %} {% file src="/files/6ExqQCz4F1dcieYME1B3" %} # 3.3.3: Spring Cross Sections Springs allow you to directly define the stiffness relation between two nodes via spring constants. Each node has six degrees of freedom (DOFs): three translations and three rotations. Using the **“Cross Sections”** multi-component with **“Cross Section”** set to **“Spring”** lets one couple these DOFs by means of six spring-constants. A relative movement $$u\_{i,rel}$$ between two nodes thus leads to a spring force $$F\_i = c\_i \cdot u\_{i,rel}$$. In this equation $$u\_{i,rel}$$ stands for a relative translation or rotation in any of the three possible directions x, y, z, $$c\_i$$ is the spring stiffness. In Karamba3D the latter has the meaning of kilo Newton per meter $$kN/m$$ in case of translations and kilo Newton meter per radiant $$kNm/rad$$ in case of rotations. The input-plugs **“Ct”** and **“Cr”** expect to receive vectors with translational and rotational stiffness constants respectively. Their orientation corresponds to the local beam coordinate system to which they apply. In case of zero-length springs this defaults to the global coordinate system but can be changed with the **“OrientateBeam”**-component. In case one wants to realize a rigid connection between two nodes the question arises as to which spring stiffness should be selected. A value too high makes the global stiffness matrix badly conditioned and can lead to a numerically singular stiffness matrix. A value too low results in unwanted relative displacements. So you have to find out by trial and error which value gives acceptable results. ![Figure 3.3.3.1: Spring fixed at one end and loaded by a point load on the other](/files/-MCkEYcQDpy36YTnQ_XN) Fig. 3.3.3.1 shows a peculiarity one has to take into account when using springs: They are unaware of the relative position of their endpoints. This is why the load on the right end of the spring does not evoke a moment at the left, fixed end of the spring. {% file src="/files/96yTkaiLPt2NywHTdr5a" %} {% file src="/files/E4qXkd21pBCCvm94vUHB" %} {% file src="/files/GZlrhwklafcWq4hI2LN0" %} {% file src="/files/vWwjXiDUg3HUMavGpqfs" %} # 3.3.4: Disassemble Cross Section In some cases (e.g. after optimizing cross sections) it may be necessary to retrieve the properties of a cross section. Use the **“Disassemble Cross Section”**-component for that (see fig. 3.3.4.1). Unfold the component sub-sections by clicking on the dark section headers. ![Fig. 3.3.4.1: “Disassemble Cross Section”-component - Properties of a given cross section can be retrieved ](/files/-MCkE_ZXe0qPhNxeGu7r) {% file src="/files/BuPHI48ACpDp7AhqVG3W" %} # 3.3.5: Eccentricity on Beam and Cross Section ![Fig. 3.3.5.1: Beam positioned eccentrically with respect to the connection line of its two end-nodes](/files/-MCkEZ3j78u2dzaBKvN-) Cross section forces of beam and truss elements relate to the line that connects the cross section centroids. When a cross section changes, chances are high that also the position of its centroid shifts. In case of elements predominantly loaded by bending moments, such a shift can normally be neglected. In the presence of normal forces however – e.g. when considering columns – changes in the centroid position lead to additional bending moments that may be decisive for a members cross section design. In Karamba3D there exist two components that can be used to take care of eccentricities (see fig. 3.3.5.1): One works on beams, the other on cross sections. When both variants of definition coincide for an element, then the eccentricities get combined. This enables one to define families of cross sections of different size with e.g. the position of their upper sides at one level. The definition of a local eccentricity for cross sections with a **“Eccent-CroSec”**-component is straight forward: The **“EcceLoc”**-input plug expects a vector that defines the offset with respect to the local beam axes. Values are in centimeters. **“x”** represents the longitudinal beam axis, **“y”** is horizontal or parallel to the global Y-axis, **“z”** points vertically upwards (see section [3.1.14](/3-in-depth-component-reference/3.1-model/3.1.14-orientate-element#orientate-beam)). Cross sections with eccentricities can be stored in cross section tables using the **“Generate Cross Section Table”**-component and thus be made reusable in other projects. The **“Eccent-Beam”**-component has one additional input-plug as compared to the cross section variant: **“EcceGlo”** lets one define beam eccentricities ($$cm$$) with respect to the global coordinate system. {% file src="/files/tmyVpR7bSkMvlFooCmp7" %} {% file src="/files/STfIAQAopeTq40yLrA29" %} {% file src="/files/ReVdcmgugfp5XMalyeK7" %} # 3.3.6: Modify Cross Section In Karamba3D cross section properties fall into four categories: | | | | ----------------- | ---------------------------------------------------------------------------------------------------------------- | | **“General”** | parameter which set the name, family, color, material and element identifier | | **“Geometry”** | properties that determine the cross section size and eccentricity | | **“Deformation”** | these parameters influence the elastic behavior of a structure | | **“Resistance”** | properties which are used by cross section design procedures in order to determine the load-bearing capabilities | The meaning of the input-values in the menu sections "Deformation" and "Resistance" are given in the help-texts associated to each input-plug. The **“Modify Cross Section”**-component allows to change these properties. Two operation modes exist for this component: **Flow through:** When a Cross section is provided as input, the result on the left side is the same cross section by default. Only those properties get changed, for which values are supplied as input. **Agent:** The cross sections which shall be modified can be selected via the **“Elem-Ids”**-input. It is possible to apply regular expressions. The resulting cross section agent is of type **“Cross Section”** and gets active when being plugged into an **“Assemble”**-component.

Fig. 3.3.6.1: ModifyCroSec Component

{% file src="/files/tdMr8t041hKiD7a3G6Kt" %} Fig. 3.3.6.1: the definition of a simply supported beam under uniform load. A **“Modify CroSec”**-component can be used to impose shear rigidity in local z-direction on a cross section. Now the calculated maximum displacement coincides with the result of the formula without shear effects. Textbook formulas for calculating the maximum displacement of such a system usually neglect the influence of shear-deformations. In order to make a cross section nearly rigid in shear the **“Modify Cross Section”**-component is used to set the shear area $$A\_z$$ to a very large value. In case the height or thickness of a cross section is changed along with deformation- or resistance parameters, the evaluation proceeds from top to bottom: First, all parameters get updated according to the new cross section dimensions, these may then be overwritten by new values for deformation of resistance properties. The drop-down list at the bottom of the component allows to switch between beam- and shell-cross sections. {% file src="/files/q9ebbWhlQTzGSWPvjOlL" %} # 3.3.7: Cross Section Range Selector The cross section library that comes with Karamba3D contains roughly 22 000 profiles. In order to reduce the amount of information the list can be shortened by applying selection criteria on it using the **“Cross Section Range Select”** component (see fig. 3.3.7.1). The input-plugs **“maxH”** and **“maxW”** let you limit the list according to maximum cross section height and width. The submenu which unfolds when clicking on the black **“select”**-bar offers further options for narrowing the search: country of origin, general shape, family and cross section name.

Fig. 3.3.7.1: Selection of a range of cross sections from among a given list

In case one does not supply a list of cross sections at the **“CroSec”** input-plug, the cross section table that comes with Karamba3D is used by default. # 3.3.8: Cross Section Selector The component **“CroSecSelect”** deals with selecting cross sections by name or index from a list of cross sections. Provide the name(s) or index(es) of desired cross sections in the **“Name|Ind”**-plug. Cross section names are not case sensitive. All characters coming after “#” count as remark. It is possible to use regular expressions for selection (these start with “&”). List indexes start from zero. **“CroSecSelect**” lets you specify beams via the **“Elems|Ids”**-plug which shall be assigned a specific cross section. The **“Assemble”**-component sets the cross-sections of these elements accordingly. Alternatively, cross sections can be directly plugged into the element-creation-components. In case one does not supply a list of cross sections at the **“CroSec”**-input-plug, the cross section table that comes with Karamba3D is used by default. ![Fig. 3.3.8.1: Cantilever with four different cross sections taken from the standard cross section table](/files/-MCkEZArx42Z-xJ-GSOe) Sadly there is no standard for the exact naming of cross sections which results in slight deviations for one and the same cross sections in different finite element programs. A "IPE80" is sometimes seen to be written as "IPE 80", "IPE-80", and so on. In the context menu of the Cross Section Selector -component it is possible to activate a fuzzy name search option (see fig. 3.3.8.2). For a given input name the component then returns the cross section whose name has the shortest Levenshtein-distance to the input.

Fig. 3.3.8.2: Fuzzy search option in the context menu of the Cross Section Selector-component.

{% file src="/files/rdkNFawM8vFdOuyk7JVv" %} {% file src="/files/TyOvrvTl6mBLQg9RIYup" %} {% file src="/files/4khIpmbgMxv9EyA18H5r" %} # 3.3.9: Cross Section Matcher Use the **“Cross Section Matcher”**-component in case you want to find the first profile from a given list that provides equal or higher resistance compared to a given custom profile (see fig. 3.3.9.1). The **“CSMatch”**-component takes a cross section and a list of cross sections as input. Traversing the list starting from the first element it proceeds until an appropriate profile is found which is returned as the result. ![Fig. 3.3.9.1: The “Cross Section Matcher”-component returning a standard profile for a custom profile](/files/-MCkEYiQqTg_NMb_INjE) {% file src="/files/sM25aRPSIDxKZV2y7vhn" %} # 3.3.10: Generate Cross Section Table ![Fig. 3.3.10.1: The “Cross Section Matcher”-component returning a standard profile for a custom profile.](/files/-MCkE_6TyU3jltVZZ8JG) {% file src="/files/1RghPqs86pta6G6YqKxS" %} An entry in a cross section table consists of a row which contains: * "country": country of origin * “family”: name of the group to which the cross section belongs (see section [3.3.1](/3-in-depth-component-reference/3.3-cross-section/3.3.1-beam-cross-sections)) * “name”: name of the specific cross section (see section [3.3.1](/3-in-depth-component-reference/3.3-cross-section/3.3.1-beam-cross-sections)) * a “shape” field which defines the basic cross section type: * “I”: I-section * “\[]”: hollow box section * “V”: trapezoid, filled section * “O”: circular tube * "S”: spring * “Sh”: shell * geometric properties which are used for drawing the cross section * area, moments of inertia, etc. that define the cross section's mechanical behavior. Can be independently defined from the cross section geometry {% hint style="info" %} A **“#”** in the first column means that the corresponding row serves as a comment. {% endhint %} The **“GenCSTable”**-component takes a cross section (or a list of cross sections) as input and returns the equivalent table of data as a string. The physical units used for output are always metric. When plugged into a panel the information can be streamed to a file which then constitutes a valid cross section table. Karamba3D reads the data of cross section tables only once. So in order that changes in a table take effect, restart Grasshopper. It is possible to save the table data in different formats via the component's context menu (right-click on the component icon to make it appear). The menu item "Save cross section table to file" leads to a "save"- dialog where the drop down list "Save as type" allows to select between bin-, dat- and csv-format. The binary format (.bin) is recommended for large tables since it loads fast. However bin-files are not readable in text editors. # 3.3.11: Read Cross Section Table from File ![Fig. 3.3.11.1: List of cross sections generated from the standard cross section table](/files/-MCkE_lZW00kbrOMuwVR) Predefined cross sections stored in a csv- or bin-database can be used to generate lists of cross sections via the **“ReadCSTable”**-component (see fig. 3.3.11.1). It works along the same lines as the **“ReadMatTable”** (see section [3.4.3](/3-in-depth-component-reference/3.4-material/3.4.3-read-material-table-from-file)) component. When given no path to a valid table **“ReadCSTable”** uses the list of cross sections comes with Karamba3D and is situated in “…/Grasshopper/Libraries/Karamba/CrossSectionValues.bin”. This table contains definitions for a range of standard steel profiles. Depending on the given file extension the data is expected to be either in binary format (“.bin”) or comma separated values (“.csv”). The former has the advantage of fast processing, the latter can be viewed and extended using a text editor or OpenOffice. In csv-files “#” is used to mark the rest of a line as comment. The physical units are always assumed to be metric – irrespective of the user settings at installation. In case of an entry in a csv-file in the first column which is not a “#”, the cross section properties get calculated based on the geometric dimensions of the cross section. In case of a deviation between the given and the calculated values of more than 10 % a warning is output at the **“Info”**-plug. When opening the Karamba3D installation folder (double-click on the Karamba3D desktop icon for that) you will find three differently named cross section tables: “CrossSectionValues.bin” and “CrossSectionValues\_sortedForHeight.bin” contain cross sections sorted according to increasing height. In “CrossSectionValues\_sortedForWeight.bin” the area and thus weight per unit of length determines a cross sections relative position within a family. When doing cross section optimization (see section [3.5.8](/3-in-depth-component-reference/3.5-algorithms/3.5.8-optimize-cross-section)) those two sorting options lead to different results. Depending on external requirements they result in structures of minimum cross section height or structural weight. # 3.4: Joint Joints help to set the connectivity between structural elements. # 3.4.1: Beam-Joints A structure usually consists of a large number of load bearing elements that need to be joined together. When rigidly connected, such a joint has to transfer three section forces (one axial force, two shear forces) and three moments (one torsional and two bending moments). Depending on the type of material such full connections are sometimes (e.g. for wood) hard to achieve, costly and bulky. A solution to this problem consists in introducing hinges.

Fig. 3.4.1.1: Beam fixed at both supports with a fully disconnected joint at one end

{% file src="/files/81Vz9E8ZtmObovO3LVIJ" %} Fig. 3.4.1.1 shows a beam under dead weight with fully fixed boundary conditions at both end-points. At the right end the joint (which is in fact no joint any more) completely dissociates the beam from the support there. The result is a cantilever. The symbols for joints resemble that for supports: pink arrows represent translational joints, white circles symbolize moment hinges. In Karamba3D joints are realized by inserting a spring between the endpoint of a beam and the node to which it connects. This necessitates sufficient support conditions at the actual nodes to prevent them from freely moving around. See for example the right node in fig. 3.4.1.1 which has to be fully fixed – otherwise the system would be kinematic. The **“Beam-Joint”**-component allows to define hinges at a beam’s starting- and end-node. A list of beams or beam-identifiers lets you select the beams where the joint definition shall apply. By default or in case of an empy string provided at 'ElemIds' the component applies to all beams in the model. Filled circles mean that the corresponding degrees of freedom represent joints. **“T”** stands for translation, **“R”** for rotation. Feed the resulting cross-section into the **“Joint”**-plug of the **“Assemble”**-component. The orientation of the axes of the joints corresponds to the local coordinate system of the beam they apply to. Sometimes the stiffness of connections lies between fully fixed and zero. With the input-plugs **“Ct-start”** and **“Cr-start”** it is possible to set the stiffness of the hinge in translation $$(kN/m)$$ and rotation$$(kNm/rad)$$ respectively at the start of the element. **“Ct-end”** and **“Cr-end”** provide the same functionality for the end-point. In order to make the definition of hinges accessible to optimization the input-plugs **“Dofs-start”** and **“Dofs-end”** can be used to set hinges at the beams endpoints with a list of numbers. Integers in the range from 0 to 5 signify degrees of freedom to be released in addition to those specified manually with the radio-buttons. {% file src="/files/GIO5Q8nQHKXIao9vy8M4" %} {% file src="/files/7zEjqThBm8bqWsHWoRHL" %} {% file src="/files/W5K6A9CEreZBxSf1TeWe" %} {% file src="/files/CS0KuHJK5mC3zlIX5KHM" %} Additional examples can be found in the Grasshopper main tab under Karamba3D > Help > Examples > Local Examples > Joints. # 3.4.2: Beam-Joint Agent ![Fig. 3.4.2.1: Defining a hinge based on geometric relations using a “Beam-Joint Agent”-component](/files/-MCkE_VrLfIVuI4O-B3r) {% file src="/files/DjMVzk5xVoJeu2nI6lEo" %} The **“Beam-Joint Agent”**-component creates hinges on beams based on geometric relations. Fig. 3.3.2.1 shows three different but equivalent possibilities for defining a joint. The element or the group of elements where the joint(s) shall be placed is set by providing a list of element identifiers at the **“AtElemsIds”** input-plug. Upon assembly, the beam-joint agent tests the model-elements and places hinges when **all** of the following conditions - in case specified by the user - apply: * The node on the at-element connects to an element whose identifier is listed in the **“ToElemIds”** input. * The node on the at-element connects to a node which has a number listed in the **“ToNodeInd”** input. * The node on the at-element lies on one of the geometric items supplied in **“ToGeom”**. This can be points, curves, planes, breps or meshes. The tolerance for two geometric items touching in space is **“LDist”** as defined on model assembly (see section [3.1.1](/3-in-depth-component-reference/3.1-model/3.1.1-assemble-model)). The meaning of **“Ct”**, **“Cr”** and **“Dofs”** is analogous to that of the Beam-Joints-component featured in section [3.4.1](/3-in-depth-component-reference/3.4-joint/3.3.6-beam-joints). {% file src="/files/ogdEogKLIqWaFIQZHEy4" %} {% file src="/files/ipLFxsjpPRYHo0Nu2YZN" %} {% file src="/files/z4eqjRTfKe1ahVzLrmVq" %} # 3.4.3: Line-Joint The **"Line-Joint"** component allows the definition of linear hinges within or at the boundaries of shell patches. **Figure 3.4.3.1** illustrates an example with two shell patches, **"A"** and **"B,"** each composed of two shell elements. Patch **"A"** is fully fixed on one side and connected to **"B"** via a linear joint, represented by a purple cylinder. **Shell "B"** can rotate around the joint’s **X-axis**, indicated by the red arrow. A line joint introduces additional degrees of freedom (DOFs) at the connected vertices—one for each hinge DOF.

Fig. 3.4.3.1: Line-joint symbolized by a purple cylinder between two shell patches "A" and "B"

{% file src="/files/9owso7cfBfkoGniBPBQh" %} ## Inputs for Defining Non-Rigid Shell Connections: The "Line-Joint"-component provides these inputs to specify the non-rigid connections between shells: * **"J-Curve"**: A line-like curve lying on the nodes of the shell that are part of the joint. The nodes do not have to be the endpoints of the curve. The curve's direction defines the joint’s **X-axis**. * **"Elem|Id"**: Specifies the shell patch or its identifier where the joint should be placed. If left empty (default), the joint can be attached to all shells in the model. * **"Y-Ori"**: Defines the local **Y-axis** of the joint, pointing towards the shell patch to which the joint is attached. When **"Joints"** is enabled in the **"ModelView"** component, the **Y-axis** appears as a green arrow on the hinge line. The size of the axes can be adjusted using the **"Local Axes"** slider in **"ModelView"**. * By default, **"Y-Ori"** is a zero-vector, which is sufficient in most cases, such as for naked edges or surfaces without additional attachments. Explicit **Y-orientation** is only needed in more complex scenarios where multiple placement options exist. * The shell where the line-joint is placed is indicated by a **purple cylinder**. If multiple line joints with **zero rotational stiffness in the X-direction** are present along a line, at least one surface must remain without a joint. Otherwise, a rigid rotation of the DOFs at the joint line may occur. * If the **Y-direction** of the joint changes along its length, specify its direction at the **start point**, and it will be automatically updated across elements. * **"Z-Ori"**: If the joint’s **Y-axis** is parallel to the joint-line direction, the right-handed local coordinate system is defined by the **X-direction** of the joint line and the **Z-orientation**. The joint is attached to the elements that the **Y-axis** points toward. When displayed in **ModelView**, the **Z-axis** appears as a blue arrow. Explicit joint orientation is generally only necessary for geometrically complex connections. * **"DAlpha"**: Specifies the maximum angle **(in degrees)** between a mesh face and **Y-Ori** for the joint to be applied. * **"Ct"**: A vector defining the **translational spring stiffness** of the line joint. Values only apply if the corresponding DOF is set to **hinged** in the **"Dofs"** input or via the **"Joint Definition"** submenu radio buttons. * **"Cr"**: A vector for **rotational spring stiffness**, functioning similarly to **"Ct"**. In complex setups with multiple line joints, assigning a small stiffness for **rotation around the local X-axis** helps prevent rigid body modes at the connection nodes without significantly affecting the structural response. * **"Dofs"**: A list of DOF indices to be released, in addition to those selected via checkboxes in the **"Joint Definition"** submenu. The DOF indices are as follows: * **0: Tx** (Translation in X) * **1: Ty** (Translation in Y) * **2: Tz** (Translation in Z) * **3: Rx** (Rotation about X) * **4: Ry** (Rotation about Y) * **5: Rz** (Rotation about Z) * Use a **"ValueList"** component for convenient selection or enable **"Expand ValueLists"** in the component’s context menu. The **radio buttons** under **"Joint Definition"** indicate which DOFs are released when enabled. To visualize the joint’s **local coordinate system**, enable **"Joints"** in the **"Display Scales"** submenu of **"ModelView"**. The **"Local Axes"** slider in the same submenu allows for scaling the displayed arrows. {% embed url="" %} {% file src="/files/4f9mU97dmapJOyumOOw1" %} {% file src="/files/FzGxTpiRJVct7XvyfUk7" %} # 3.5: Material There are two ways for defining materials in Karamba3D: Either select a material by name from a list of materials (see section [3.4.2](/3-in-depth-component-reference/3.4-material/3.4.2-material-selection)) or set mechanical material properties manually (see below). {% hint style="info" %} The Appendix (see section [A.2.1](/appendix/a.4-background-information/a.4.1-basic-properties-of-materials)) contains additional information on mechanical properties of materials. {% endhint %} Materials constitute a property of cross sections. There are two ways of attaching materials to cross sections: 1. In order to directly assign a material to a cross section, plug it into the corresponding cross section creation component. This is overridden by indirect material definitions via the **“Assemble”** component as described below. 2. Materials (like cross sections) may be plugged into the **“Assemble”** component. They know about the elements (or element sets) they apply to by their **“Elems|Ids”** property: This is a list of strings containing element identifiers (see section [3.1.6](/3-in-depth-component-reference/3.1-model/3.1.6-create-linear-element/3.1.6-line-to-beam)) or regular expressions that match a group of element identifiers (element-ids). Upon assembly each element-id is compared to all **“Elems|Ids”** entries of a material. In case they match the material is attached to the element. An empty string – which is the default value – signifies that the material shall be applied to all elements. # 3.5.1: Material Properties The component **“MatProps”** lets one directly define isotropic and orthotropic materials. Use the dropdown menu at the bottom of the component to chose between ortho- and isotropic materials. ## **Isotropic Material Properties** ![Fig. 3.5.1.1: Definition of the properties of two isotropic materials via the “Material Properties” component](/files/-Mgu6Ps56ZRCVP4aeA57) {% file src="/files/wdiJR6qZ6uXAt0ckZDyx" %} In Fig. 3.5.1.1 selection of the second material from the resulting list can be made (bottom right component) or selection from the default material table (top right component). Material isotropy means that the material’s behaviour does not change with direction. Karamba3D uses the following parameters to characterize an isotropic material (see fig. 3.5.1.1): | | | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Family"** | Family name of the material (e.g. “steel”); is used for selecting materials from a list. | | **"Name"** | Name of the material (e.g. “S235”); serves as identification when selecting materials from a list. | | **"Elem\|Id"** | An element with an identifier, a string containing an identifier or a regular expression that depicts the elements that shall have the specified material. | | **"Color"** | Color of the material. In order to see it, enable **“Materials”** in submenu **“Colors”** of the **“ModelView”**-component, then enable **“Cross section”** in submenu **“Render Settings”** of the **“BeamView”**- and/or **“ShellView”**-component. | | **"E"** | Young’s Modulus ($$kN/cm^2$$): characterizes the stiffness of the material. | | **"G12"** | In-plane shear modulus ($$kN/cm^2$$): In case of isotropic materials the following constraint applies: $$E/3\
v\_{12} ​is the in-plane lateral contraction coefficient (also called Poisson’s ratio): In casev\_{12}=-1(the default) the approximate formula of Huber \[8] is applied to v\_{21}​ calculated from​E\_1, E\_2 and G\_{12}:
v\_{12}​=\frac{E\_1}{2.G\_{12}}​​−\sqrt{\frac{E\_2}{​E\_1}}​​ ​

| | **"G31"** | Transverse shear modulus in the first direction ($$kN/cm^2$$) | | **"G32"** | Transverse shear modulus in the second direction ($$kN/cm^2$$) | | **"gamma"** | Specific weight ( $$kN/m^3$$ ) | | **"alphaT1"** | Coefficient of thermal expansion in the first direction ( $$1/°C$$ ) | | **"alphaT2"** | Coefficient of thermal expansion in the second direction ( $$1/°C$$ ) | | "**ft1"** | Tensile strength of the material ($$kN/cm^2$$) in the first direction - a positive value | | "**ft2"** | Tensile strength of the material ($$kN/cm^2$$) in the second direction - a positive value | | **"fc1"** | Compressive strength of the material ($$kN/cm^2$$) in the first direction - a negative value | | **"fc2"** | Compressive strength of the material ($$kN/cm^2$$) in the second direction - a negative value | | **"t12"** | Shear strength ($$kN/cm^2$$) between first and second material direction. | | **"F12"** | Tsai-Wu interaction coefficient | | **"S-Hypo"** | Index of the strength hypothesis to be used. Use 'Expand ValueLists' from the components context menu for selecting between these options: 0: Von Mises, 1: Tresca, 2: Rankine, 3:TsaiWu | {% embed url="" %} {% file src="/files/YYuZl1AjJvExdoJYRWve" %} {% file src="/files/JjUHGyGD14Ox1enTRegi" %} # 3.5.2: Material Selection The **“Material Selection”**-component in the menu subsection **“Material”** lets you select a material by family, name or index from a given list of materials (see fig. [3.4.1.1](/3-in-depth-component-reference/3.4-material/3.4.1-material-properties#isotropic-material-properties) or fig. [3.4.3.2](/3-in-depth-component-reference/3.4-material/3.4.3-read-material-table-from-file)). Input the list of materials via the plug **“Mat”**. In case no list of materials is supplied, the material table that comes with Karamba3D is used. The input-plug **“Name|Ind”** expects either the zero-based list index of the selected material or its name. The names of materials are not case sensitive. A “#” in a material name means that the rest of the line is a comment. “&” starts a regular expression – in that case material names are case sensitive. For quick access materials may be selected via the drop down lists **“Family”** and **“Name”**, which unfold when clicking on the components **“Select”** bar. These two entries serve as additional criteria which act on the list of materials selected through the **“Name|Ind”** input. The inputs **“Elem|Id”** and **“Color”** have the same meaning as in the **“Material Properties”**-component (see section[ 3.4.1](/3-in-depth-component-reference/3.4-material/3.4.1-material-properties)). Any element identifiers already present in a material get overwritten by the values input via **“Elem|Id”**. Without a color supplied at input **“Color”** the original material color persists. {% file src="/files/Nq31HUfTCjFMDodoEGkb" %} # 3.5.3: Read Material Table from File ![Fig. 3.5.3.1: Partial view of the default data base of materials](/files/-Mgya3izvOQUBiQCJyJF) Karamba3D comes with a table of predefined materials. The csv-file “Materialproperties.csv” resides in the Karamba3D installation-folder. By default the **“ReadMatTable”**-component takes this file and creates a list of materials from it. These are available at the output-plug “Material”. The data-base currently holds properties for: * steel * wood * hardwood * coniferous timber * glulam timber * aluminum * concrete * lightweight concrete * reinforcement steel There exist different types of steel, concrete etc.. The generic term “concrete” for example will result in the selection of an everyday type of concrete - a C25/30 according to Eurocode 2. More specific descriptions may be given: Have a look at the data-base in order to get an overview. Material properties specified via table are assumed to be in SI units. They get automatically converted when used in the context of Imperial units. ![Fig. 3.5.3.2: List of materials resulting from the “ReadMatTable”-component](/files/-Mgyb91OMJGApipznXWe) Fig. 3.5.3.1 shows examples of how to define isotropic materials via table. SI units are used irrespective of user settings. Automatic conversion ensures compatibility with Imperial units. In case of orthotropic materials, the item in column “D” needs to be set to something different from “iso”. The order of orthotropic material parameters which follow from column “E” onward correspond to that of the **“Material Property”**-component: $$E\_1$$, $$E\_2$$, $$G\_{12}$$,$$\nu\_{12}$$,$$G\_{31}$$, $$G\_{32}$$,$$\gamma$$,$$\alpha\_{T1}$$,$$\alpha\_{T2}$$,$$f\_{t1}$$,$$f\_{t2}$$,$$f\_{c1}$$, $$f\_{c2}$$, $$t\_{12}$$, $$F\_{12}$$, **"S\_Hypo"** and **“Color”**. The extension .csv stands for “comma separated value”. The file can be opened with any text editor and contains the table entries separated by semicolons. It is preferable however to use OpenOffice or Excel (both can read and write csv-files): They render the data neatly formatted (see fig. 3.5.3.1). Make sure to have a “.” and not a “,” set as your decimal separator. In some countries “.” is used to separate thousands which then needs to be adapted as well. The setting may be changed under Windows via “regional settings” in “system settings”. All lines in the table that start with “#” are comments. Feel free to define your own materials. The file path to the materials data-base can be changed in two ways: first right-click on the component and hit **“Select file path to material definitions”** in the context menu that pops up. Second plug a panel with a file path into **“Path”**. Relative paths are relative to the directory where your definition lies. # 3.5.4: Disassemble Material ![Fig. 3.5.4.1: The “Disassemble Material”-component gives access to all material properties](/files/-MCkEUbyeMi1xQ1doBk1) In case one wants to retrieve the parameters which define a material, the **“Disassemble Material”**-component does the job (see fig. 3.5.4.1). It can be applied to isotropic and orthotropic materials alike. In order to be valid for both types of materials, the outputs **“E1/2”**, **“G31/2”**, **“alphaT1/2”** and **“fy1/2”** return lists of numbers instead of single items. For isotropic materials these lists contain one member only. In case of orthotropic materials two numbers are present, corresponding to the first and second material direction respectively. {% file src="/files/ZPsks0nAJmFs6qlCnkPg" %} # 3.6: Algorithms Karamba3D offers various options for analyzing a structural model. The following sections provide detailed explanations of all the algorithm components available. # 3.6.1: Analyze With geometry, supports and loads defined, the structural model is ready for processing. The **“Analyze”**-component computes the mechanical response for each load case and adds this information to the model.

Fig. 3.6.1: Deflection of simply supported beam under single load in mid-span and axial, compressive load

Fig. 3.6.1 shows the definition of a beam with two load-cases "LC*A" and "LCB".* A transverse load in mid-span acts in both load-cases. "LCA" features an additional axial compression load of 60kN, *"LC\_B"* a tensile axial load of same size. In the absence of additional definitions with regards to the calculation types of the load-cases via a ["Load-Case-Combination Options"-component](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations/3.2.5.3-load-case-combination-settings) the "Analyze"-component performs by default a first order theory calculation. This results in the same maximum displacement of 17.7cm for both load-cases. The "Analyze"-component outputs not only the maximum nodal displacement (in centimeter) but also the maximum resultant force of the calculated load-cases (in kilo Newton) and the structure's internal deformation energy - section [3.6.2](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.6.2-deformation-energy) contains details on work and energy. These values can be used to rank structures in the course of a structural optimization procedure: the more efficient a structure, the smaller the maximum deflection, the amount of material used and the value of the internal elastic energy. Real structures are designed in such a way that their deflection does not impair their usability. See section [A.2.3](/appendix/a.4-background-information/a.4.3-tips-for-designing-statically-feasible-structures) for further details. Maximum deflection and elastic energy both provide a benchmark for structural stiffness, yet from different points of view: The value of elastic energy allows to judge a structure as a whole; The maximum displacement returns a local peak value. The **"LoadCases"**-input lets one select the load-case-combinations and load-cases to be considered in the analysis. By default all load-cases and load-case-combinations get computed. The hint in section [Load-Case-Combinations](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations) explains how load-cases and load-case-combinations can be excluded from the default list. Fig. 3.6.3 shows the same basic system as before. This time a ["Load Case Combination"-component](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations/3.2.5.3-load-case-combination-settings) sets the load-cases analysis type to second order theory (Th. II). At the component's "LCase"-input the simplified regular expression "LC$" selects all load-cases with names starting with "LC". Setting "CombiNII" to false lets the "Analyze"-component compute the $$N^{II}$$for each load-case individually. The second order normal forces $$N^{II}$$soften the system when compressive, stiffen it when tensile. Therefore the maximum displacements and elastic energies of "LC*A" and "LC*B" differ. Setting "NoTenNII" of the ["Load Case Combination"-component](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations/3.2.5.3-load-case-combination-settings) to "true" would have resulted for "LC\_B" in the same maximum displacement as in the example above since this options disregards the stiffening effect of normal forces. For "CombiNII" equal to true the minimum normal force of both load-cases (N = -60kN) would have been used as $$N^{II}$$. Thus both load-cases "LC*A" and "LC*B" would have rendered a maximum displacement of 26.7cm.

Fig. 3.6.3: Deflection of simply supported beam under single load in mid-span and axial, compressive load based on second order theory small displacement calculation.

{% file src="/files/hVLlyHXfNuUeylpfk9FN" %} In order to view the deflected model use the [**“ModelView”**-component](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.6.1-modelview) (see section [3.6.1](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.6.1-modelview)) and select the desired load-case using the **"Load Case Selector"**-component. Looking at fig. 3.6.2 and fig. 3.6.3 one notices that only beam center axes are shown. In order to see beams or shells in a rendered view, add a [**“BeamView”**](/3-in-depth-component-reference/3.6-results/3.7.2-results-on-beams/3.6.7-beamview)- or [**“ShellView”**](/3-in-depth-component-reference/3.6-results/3.7.3-results-on-shells/3.6.11-shellview)-component after the [**“ModelView”**](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.6.1-modelview). See sections [3.6.7](/3-in-depth-component-reference/3.6-results/3.7.2-results-on-beams/3.6.7-beamview) and [3.6.11](/3-in-depth-component-reference/3.6-results/3.7.3-results-on-shells/3.6.11-shellview) for details. # 3.6.2: AnalyzeThII The "Analyze ThII"-component exist for convenience. Second order theory analysis can also be specified per load-case-combination via the ["Load-Case-Combination Settings"-component](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations/3.2.5.3-load-case-combination-settings) and calculated by an ["Analyze"-component](/3-in-depth-component-reference/3.5-algorithms/3.5.1-analyze). Section [3.2.5.3](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations/3.2.5.3-load-case-combination-settings) contains details regarding second order theory calculations. In Karamba3D distinction is made between normal forces $$N$$ which cause stresses in the members and normal forces $$N^{II}$$ which result in second order effects (see also [\[10\]](/appendix/bibliography)). At first sight this concept seems weird. How can there be two kinds of normal forces in the same beam? Well, in reality there can’t. In a computer program it is no problem: stresses get calculated as $$\sigma = N/A$$ and $$N^{II}$$ is used for determining second order effects only. The advantage is, that in the presence of several load-cases one can chose for each element the largest compressive force as $$N^{II}$$. This gives a lower limit for the structure's stiffness. A re-evaluation of the load-cases using these $$N^{II}$$ values leads to a structural response which is too soft. However the results of different load-cases may then be safely superimposed. Use the **“AnalyzeThII”**-component for automatically determining the normal forces $$N^{II}$$ from cross section forces $$N\_{x} \cdot N ^{II}$$influences a structure's stiffness which in turn impacts the distribution of cross section forces $$N\_x$$. Thus an iterative procedure with repeated updates of $$N^{II}$$-forces needs to be applied.

Fig 3.6.2: Deflection of simply supported beam under single load in mid-span and axial compressive load

{% file src="/files/3yb7XtE96JcgOzg8B5FB" %} Fig. 3.6.2 shows the same system as in fig. [3.5.1](/3-in-depth-component-reference/3.5-algorithms/3.5.1-analyze). This time with results according to first and second order theory. When comparing the transverse deflections in load-case two one can see that the maximum deflection increased from $$0.24\[m]$$ to $$0.28\[m]$$ due to the effect of the axial compressive load. The **“AnalyzeThII”**-component features the following input-plugs: | | | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **"Model"** | Model to be considered | | **"LCases"** | List of names of load-case or load-case-combination from which to take the normal force $$N^{II}$$ which cause second order theory effects. By default the minimum normal force of all load-cases is considered. The hint in section [Load-Case-Combinations](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations) explains how load-cases and load-case-combinations can be excluded from the default list. | | **"InitialNII"** | The initial value of $$N^{II}$$ can be specified at the element level by using a ModifyElement-component. If **"InitialNII"** is **"True"** these values get used during the first iteration of the ThII-Analysis | | **"CombiNII"** |

If set to True, the minimum normal force across all load cases is used for each element, resulting in a single stiffness matrix applied to all load cases. This approach can lead to overly conservative results.
If set to False, a separate stiffness matrix is computed for each load case based on its corresponding normal force, producing less conservative results but requiring greater computational effort.

| | **"NoTenNII"** | Tension forces increase a structure’s stiffness. When **NoTenNII** is set to **True**, the value of $$N^{II}$$ is restricted to negative values by default. The upper limit of $$N^{II}$$ can be adjusted to any value via the **niiLt0Limit** parameter in *karamba.ini*. | | **"NoComNII"** | Compressive forces decrease a structure’s stiffness. For membranes, this can cause wrinkling and thus local buckling. When **NoComNII** is set to **True**, $$N^{II}$$ is restricted to positive values by default. The lower limit of $$N^{II}$$ can be customized via the **niiGt0Limit** parameter in *karamba.ini*. | | **"RTol"** | The determination of $$N^{II}$$ is an iterative process. The value of **“RTol”** is the upper limit of displacement increments from one iteration to the next. | | **"MaxIter"** | Supply here the maximum number of iterations for determining $$N^{II}$$. The default is 50. In case **“RTol”** can not be reached within the preset number of iterations the component turns orange. | | **"NoTenNII"** | Tension forces increase the stiffness of a structure. Setting **“NoTenNII”** to **“True”** limits $$N^{II}$$ to negative values. | The normal forces $$N^{II}$$ get attached to the model and will be considered in all further analysis steps. They impact the results of the **“Analyze”**-, **“Buckling Modes”**-, **“Natural Vibrations”**- and **“Optimize Cross Sections”**-components. For imperfection loads $$N^{II}$$-forces have a direct impact on the applied loads. Use the **“NII”** button in submenu **“Tags”** of the **“ModelView”**-component to display $$N^{II}$$-forces. # 3.6.3: Analyze Nonlinear WIP Linear structural behavior implies that if the external loads are scaled by a factor, the physical response quantities (displacements, cross-section forces, stresses, etc.) also scale by that factor. This property allows for the superposition of different loads, eliminating the need to recalculate the model for each possible combination of external loads. In real structures, the assumption of linear behavior is an approximation, though a good one in many cases. There are two major sources of non-linearity: * **Material Non-Linearity**: This occurs when the stress-strain relationship of the material is not linear (e.g. concrete that cracks, steel that yields, …). * Geometric non-linearity: Takes effect when * lateral displacements get so large, that their effect on the axial (in case of e.g. beams) or in-plane (think of shells) deformation can not be neglected any more, * a nodal rotation $$\alpha$$ reaches such a value, that the difference between $$\alpha$$ and $$\tan(\alpha)$$ gains importance. {% hint style="info" %} The **“Analyze Nonlinear WIP”**-component lets one deal with geometric non-linearity. It is work-in-progress. This means that especially for shells the algorithms may not converge within acceptable time for some structures. If however a result is returned, then it is sound. {% endhint %} With the **“Analyze Nonlinear WIP”**-component one can chose from three variants of iterative solution algorithms. Each of these has different benefits and liabilities which will be explained below. The algorithms are based on the assumption of small strains, but allow arbitrarily large displacements. The target of all three algorithms is to find a displacement state, where the external loads and the internal forces are in equilibrium. Starting from a known initial displacement state, one has to guess how the structure deforms under the given loads. This guess leads to a second displacement state where the internal and external forces usually do not match. The remaining imbalance forms the basis of a next prediction regarding the change of displacements and so on. Equilibrium is reached when the residual-force or change of displacements falls below a given threshold. The three algorithms offered by the **“Analyze Nonlinear WIP”**-component differ in how they predict the displacement increments. ## **Dynamic Relaxation** ![Fig. 3.5.3.1: Dynamic relaxation method option of the “Analyze Nonlinear WIP”-component.](/files/YRefFSq6sLdJ7R4k9WFw) {% file src="/files/7FQgI31ocTwKCw35Dfk5" %} Fig**.** 3.5.3.1 shows a cantilever beam with a bending moment load about the local y-axis at its tip. It consists of 20 beam elements. For calculating its response the **“DynamicRelaxation”**-option is used. This algorithm predicts the next move of a structure based on the direction of the residual forces acting on each node. It is a robust procedure which converges to equilibrium quite reliably but sometimes needs a large number of iterations to do so. This component offers the following input-plugs: | | | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Model"** | Structure to be analyzed. | | **"nLoadSteps"** | Number of load-cases which shall act as load-steps. The default is 1. When setting it to e.g. 2 it means that the algorithm starts with finding equilibrium for load-case 0. After that, the loads of load-case 0 remain in place and the loads of load-case 1 are added in order to arrive at the final stage. This allows to model a loading history. The remaining load-cases get added to the final stage separately and under the assumption of small displacements. In the case of an active bending structure the first load-cases serve as those which cause the deformed structure, whereas the rest of the load-cases constitute additional actions on the deformed configuration like wind- or live-load. The scaling factor for displacements in the **“Display Scales”** submenu of the **“ModelView”**-component acts only on the loading-steps for which small displacements are assumed. The large deformation share of the total displacements does not get scaled and is displayed in real size. | | **"nLoadIncs"** | Number of increments per load-case (the default is 5). External loads get applied in several steps. In case of structures with nearly linear behaviour, the number of increments can be set to a small number. For highly non-linear problems a larger value can be advantageous. The smaller the load-increments, the easier it is for the algorithm to find equilibrium. The number of iterations usually decreases with increasing number of load-steps (and thus decreasing step size). The overall performance can however suffer if the number of load-steps is set to a number which is too high for the given type of structural behaviour. | | **"maxEquiIter"** | Sets the maximum number of equilibrium iterations per load-increment and thus sets a limit on computation time. It defaults to 200. | | **"EquiTol"** | Tolerance for the iterative change of residual forces and displacements relative to their incremental change in the current load-step. The default value is $$1E-7$$. | | **"maxLimitIter"** | The range of problems which can be tackled using the dynamic relaxation (DR) algorithm as implemented in Karamba3D is limited to stable structures. In case of phenomena like buckling or snap-through, equilibrium states may exist beyond the point of initial instability. They are however hard to reach due to their often large distance from the last known stable configuration. In such a case the DR-algorithm does not converge to an equilibrium state within the maximum number of equilibrium iterations. It then tries to close in on the point of assumed instability by halving the load-increment which led to divergence. By proceeding in this manner, the so called limit load can be determined with arbitrary precision. **“maxLimitIter”** sets an upper limit on the number of limit-load-iterations which is equal to 200 by default. Sadly, divergence can also be caused by numerical problems in the algorithm. Thus the limit-load-factor as determined by the **“Analyze Nonlinear WIP”**-component constitutes only a lower limit estimation. | | **"LimitTol"** | Sets the minimum load-increment threshold for calculating the limit-load. | | **"StepSizeFac"** | A factor for scaling the predicted displacement increments of the DR-algorithm. | During a non-linear calculation lots of things can happen. In order to get an idea about why and where something went wrong, the DR variant of the **“DynamicRelaxation”**-option produces the following output: | | | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Model"** | Structure with calculated displacements, stresses and internal forces. | | **"Disp"** | Maximum displacement reached in centimeter. | | **"Energy"** | Deformation energy stored in the structure in $$kN m$$ . | | **"Info"** |

Details regarding the solution process. It outputs five columns of text:

  • “Factor”: The factor of the loads of the current load-step.
  • “Step”: The current load-step
  • “Iter”: Counts the number of iterations for the current load-increment.
  • “Disp.Err”: Outputs the ratio of the sum of iterative changes of the nodal displacements with respect to the change of displacements of the first iteration in the current load-increment
  • “Force.Err”: Outputs the ratio of the sum of iterative changes of the residual forces with respect to the current load-increment.
| | **"Lambdas"** | Informs about the load-factors for which equilibrium could be reached. | ## **Newton-Raphson Method** In practice, dynamic relaxation(DR) procedures are used for highly non-linear problems like numerical crash-tests of cars, bolts being shot into a wall, …. The reason is, that implementing non-linear effects as DR code is relatively easy. This ease of implementation comes at the cost of high computational effort: Many iterations are necessary to reach equilibrium with acceptable accuracy. The way out of this is to invest more effort in a better prediction of the displacement increments. In DR-methods the residual forces at the nodes form the basis of predicting the next position of a node. Methods like the Newton-Raphson- or Arc-Length-method use a stiffness matrix for producing displacement predictions. There the computational cost per iteration is higher, but the number of iterations can be made much smaller as compared to DR-methods. With a consistent stiffness matrix quadratic convergence can be achieved under optimal conditions. This means that for the iterative displacement- and force-errors the number of zeros after the decimal separator doubles in each iteration. For the **“Analyze Nonlinear WIP”**-component this is not yet the case and one reason for the “work in progress”-label. Details on the Newton-Raphson- or Arc-Length methods can be found in [\[6\]](broken://pages/-M9XuRDLyIWACDdqcL2-) on page 102 ff. and 214 ff.**.** ![Fig. 3.5.3.2: Newton-Raphson method option of the “Analyze Nonlinear WIP”-component](/files/bmXL1axjNgL6sJMk1NnT) {% file src="/files/z6JLiUSdRWuq6NjpaQhY" %} Fig. 3.5.3.2 shows the same cantilever beam as before, this time analyzed with the **“NewtonRaphson”**-option. The Newton-Raphson variant of the **“Analyze Nonlinear WIP”**-component comes with nearly the same input- and output-plugs as the DR-version. The only difference is the missing **“StepSizeFac”**-input. Since Newton-Raphson procedures have the same limitation with respect to unstable structures as DR-methods, an interval halving strategy for closing in on limit-points is applied as before. ## **Arc-Length Method** ![Fig. 3.5.3.3: Arc-Length method option of the “Analyze Nonlinear WIP”-component](/files/uUw0TOOC5JVgRY5jRgqR) {% file src="/files/Mea57cSOLhk11zJpK8jl" %} For many structures reaching a first point of instability is not yet the end of the story. Especially thin plate and shell structures show large load bearing reserves when considering their post-buckling behavior. The Arc-Length-method can be used for these kinds of situations. Fig. 3.5.3.3 shows the calculation of a truss structure which snaps through from an unstable state to a stable post-buckling configuration. The first two inputs of the **“Arclength”**-component have the same meaning as before. Here a description of how the rest of the input-plugs controls the solution process: | | | | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"IniLoadFac"** | The displacement of the structure under the external load multiplied by **“IniLoadFac”** serves as a first estimate for the target deformation increments. | | **"MaxEquiIter"** | The maximum number of iterations per load increment. | | **"TargetEquiIter"** | Sets the number of increments to be used in each increment. Is used to scale the load-increments accordingly. | | **"EquiTol"** | The tolerance for out of balance forces and displacement changes from one iteration to the next. | | **"MaxLoadInc"** | Maximum number of load iterations. | # 3.6.4: Large Deformation Analysis Before the advent of digital modelling people like Heinz Isler, Antoni Gaudi or Sergio Musmeci helped themselves with physical models for generating curved geometries. A popular method was to use the shape of meshes or elastic membranes hanging from supports. ![Fig. 3.6.4.1: Structure resulting from large deflection analysis with the “LaDeform”-component](/files/-MCkEYlznB7XhZNIp3Wy) In Karamba3D the behaviour of hanging models can be simulated with the help of the **“Analyze Large Deformation”**-component. Fig. 3.6.4.1 shows a geometry derived from an initially flat mesh under evenly distributed point-loads. The algorithm behind the **“Analyze Large Deformation”**-component handles geometric non-linearity by an incremental approach only: All external loads get applied in steps. After each step the model geometry updates to the deflected state. The more and the smaller the steps, the better the approximation of geometric non-linearity. This purely incremental method however incurs an unavoidable drift from the exact solution. For form-finding this error is negligible in most cases. The methods available under the **“Analyze Nonlinear WIP”**-component (see section [3.5.3](/3-in-depth-component-reference/3.5-algorithms/3.5.3-analyze-nonlinear-wip)) do not suffer from this lack of accuracy, since they apply an incremental-iterative approach. Yet they normally require more computational effort to arrive at a similar shape as the algorithm behind the **“Analyze Large Deformation”**-component.

Fig. 3.6.4.2: Catenary resulting from point loads that do not change their direction when displaced

Fig. 3.6.4.2 shows a simply supported beam under the action of uniformly distributed point loads. Due to its slenderness axial stiffness by far outweighs bending stiffness. Thus the deflected shape corresponds to a rope under self weight. The **“LaDeform”** component has three input-plugs: | | | | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Model"** | Structure to be deformed. **“LaDeform”** uses load-case 0 for calculating the deflected shape. | | **"Inc"** | Number of increments for applying the loads. | | **"MaxDisp"** |

Maximum displacement to be reached in meter. When supplied with a value, the incremental deflection in each step is scaled to . This enables Karamba3D to handle problems with overly large deflections at the beginning of the incremental procedure. Think of an initially straight rope: Due to its negligible bending stiffness it tends to deform tremendously in the first loading step.

With no value supplied in “MaxDisp” external loads get incremented proportionally in each step. Aside from cases like mentioned above this results in an approximation of the structure's real deflections under the given loads.

|

Fig. 3.6.4.3: Pneumatic form resulting from point loads that rotate along with the points they apply to

{% file src="/files/yFAhNnEiJmVBiIAgEt9o" %} In fig. 3.6.4.2 the point loads are defined with respect to the global coordinate system: The input-plug **“Local?”** at the point-load component is set to “False”. Fig. 3.6.4.3 shows what happens if one changes that property to “True”: The point-loads co-rotate with the points they apply to. This leads to a pneumatic shape. The same happens for locally defined line-loads. The two output plugs of the **“LaDeform”**-component supply the deflected model and the maximum deflection reached in the calculation. The local coordinate system of each element gets updated along with its positions. By default an elements local Y-axis is taken parallel to the global X-Y-plane. If an element reaches a vertical position however, its default coordinate system flips – the Y-axis is then taken parallel to the global Y-axis. This may lead to unwanted results when using line-loads which flip along with the local coordinate system. It is possible to avoid this by defining local axes via the **“OrientateBeam”**-component. The deflected model contains no information regarding internal forces or stresses. The reason for this is that, owing to the purely incremental approach, these properties would be utterly inaccurate. {% file src="/files/AT1dUKHtWhlmZ1FatGQK" %} {% file src="/files/z1Qb94eFKlSDZn08tQMU" %} {% file src="/files/la3WB67Jyyf9mO40djy9" %} {% file src="/files/YIoVT6SiNrXoLBhWJW6b" %} *Additional examples can be found in the Grasshopper main tab under Karamba3D > Help > Examples > Local Examples > Algorithms.* # 3.6.5: Buckling Modes

Fig. 3.6.5.1: Beam and shell model of a cantilever: shape and load-factors of the first buckling mode

Axial forces in beams and trusses, as well as in-plane forces in shells, alter the element response under transverse load. Tension increases stiffness, while compression reduces it. Slender columns or thin shells may fail due to buckling before the stresses in the cross-section reach the material strength, making stability analysis crucial in structural design. When performing cross-section optimization with the **“Optimize Cross Section”** component, the design formulas applied account for buckling, based on the buckling length of the members. By default, local buckling of individual elements is assumed. Global buckling, which occurs when a structural sub-system consisting of several elements (such as a truss) loses stability, can be checked with the **“Buckling Modes”** component (see Fig. 3.6.5.1). For calculating buckling modes there need to be second order normal forces $$N^{II}$$ present in the system. These can be defined directly via a "Modify Element"-component or calculated through a secon order theory analysis. The **“Buckling Modes”**-component expects these input parameters: | | | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Model"** | Structure with second order normal forces $$N^{II}$$ defined. These forces can either be taken from a second order theory calculation (like in fig. 3.5.5.1 for the shell elements) or specified via a **“Modify Element”**-component (like in fig. 3.5.5.1 for the beam elements). | | **"FromInd"** | Index of the first buckling mode to be determined. The default is 1. This is also normally the only buckling shape of interest, since it corresponds to the mode of failure. | | **"NModes"** | Number of buckling modes to be calculated. The default is 1. | | **"LCasesNII"** | Names of the load-cases from which the largest compressive force $$N^{II}$$ is chosen for each element. By default all calculated load-cases are considered. In case no calculated results are present the user-defined NII-values are used (see "ModifyElement"-component in section [3.1.8](/3-in-depth-component-reference/3.1-model/3.1.10-modify-element)). | | **"MaxIter"** | The determination of the buckling modes is an iterative procedure. **“MaxIter”** sets the maximum number of iterations. | | **"Eps"** | Represents the convergence criteria. For convergence the iterative change of the norm of the displacements needs to fall below that value. | The inputs **"MaxIter"** and **"Eps"** control the accuracy of the Eigen Modes calculation. The default values work in most cases. The model which comes out on the right side lists the computed buckling-modes as result-cases of the load-case-combination "BucklingModes". The buckling shapes get scaled, so that their largest displacement component has the value 1. **“BLFacs”** returns the buckling load factors which are assumed to be non-negative. When multiplied with those factors the current normal forces $$N^{II}$$ would lead to an unstable structure. The buckling load factors are listed in ascending order. The calculation of buckling factors assumes small deflections up to the point of instability. This may not always be the case. {% file src="/files/jXVJpcnKoiWp7kLBFgo5" %} # 3.6.6: Eigen Modes

Fig. 3.6.6.1: Left: 8th eigen-mode with strain display enabled. Right: EigenMode-component in action

Karamba3D's **“EigenMode”** component allows the calculation of eigenmodes and corresponding eigenvalues of structures (see Fig. 3.6.6.1). The input parameters include a model, the index of the first eigenmode to be computed, and the number of desired eigenmodes. By setting the **“ThII?”** input to **“true”** (default is **“false”**), the effect of second-order forces can be considered. The **“LCasesNII”** input defines the load cases from which the most compressive second-order theory force is selected. If **“ThII?”** is **“true”** and **“LCasesNII”** is empty, all calculated load cases are considered. If there are no calculated load cases, user-defined $$N^{II}$$-values are used. The inputs **"MaxIter"** and **"Eps"** control the accuracy of the Eigen Modes calculation. The default values work in most cases. The output model lists the computed eigenmodes as result cases of load-case combination **“EigenModes”**. These can be superimposed using the **“ModelView”** component for form-finding or structural optimization. The determination of eigenshapes can be time-consuming for large structures or many modes. The number of different eigenmodes in a structure equals the number of degrees of freedom. For beams, there are six degrees of freedom per node; for nodes with only trusses attached, there are three degrees of freedom. Fig. 3.6.6.2 shows the first nine eigenmodes of a triangular beam mesh fixed at its lower corners, with the undeformed shape in the upper left corner. Higher-index eigenmodes exhibit more folds. Eigenvalues represent a measure of the structure's resistance to deformation into the corresponding eigenform. Values of zero or nearly zero indicate rigid body modes. If the **“Analyze”** or **“AnalyzeThII”** components report a kinematic structure, the eigenforms can help detect these kinematic modes. The displacements of the eigenmodes are scaled such that the largest displacement component corresponds to 1. ![Fig. 3.6.6.2: Undeformed geometry (upper left corner) and the first nine eigen-modes of the structure](/files/-MCkET8OdWq8H7dCUfUm) {% file src="/files/q1oGzJkRwxuNBhSx7Bap" %} # 3.6.7: Natural Vibrations To determine how and at what frequency a structure vibrates, use the **“NaturalVibrations”** component. Fig. 3.6.7.1 illustrates a simply supported steel beam (IPE100) with a point mass at mid-span in its 10th natural vibration mode. The mass of beams and trusses is calculated based on their material weight. Karamba3D employs consistent mass matrices for beam elements, while a lumped approach is used for truss and shell elements. Additional masses can be defined at nodes (see section [3.1.9](/3-in-depth-component-reference/3.1-model/3.1.11-point-mass)) to simulate the effect of components such as concrete slabs, which typically constitute the majority of mass in high-rise structures. These additional masses are assumed to have translational inertia only. Karamba3D scales the resulting vibration modes so that their largest component is 1. These modes are attached to the model as result cases, which can be viewed using the **“ModelView”** component. The calculation of modal mass and participation factors is based on these scaled modal displacements. The input plugs **“ThII?”** and **“LCasesNII”**, as well as the inputs under **“Options”**, have the same meaning as those in the **“Eigen Modes”** and **“Buckling Modes”** components.

Fig. 3.6.7.1: Natural vibration mode of a simply supported steel beam with a point-mass at mid-span.

{% file src="/files/OEWXnQxBF8Az6SHFUCTD" %} # 3.6.8: Optimize Cross Section The **"Optimize Cross Section"** component is designed for the automated selection of optimal cross sections for beams and shells, taking into consideration the load-bearing capacity of the cross sections and, optionally, the maximum allowable deflection of the structure.

Fig. 3.6.8.1: Cross section optimization using the "OptiCroSec" component on a simply supported beam.

{% file src="/files/L3PWA1q1KgJTSAsWjuiD" %} ## Design to Prevent Structural Failure at the Ultimate Limit State (ULS) In Figure 3.6.8.1, no displacement limit is specified, allowing the **"OptiCroSec"** component to determine the cross section for each element to ensure adequate load-bearing capacity across all specified load cases and combinations, inputted via the "**LCasesUtil**" plug. Absence of an entry in "**LCasesUtil**" defaults to all load cases and combinations included in the model. A negative value for the target maximum utilization can be input to circumvent design toward strength limits. The "**MaxUtil**" input defaults to "1.0" meaning design for full utilization. The Karamba3D software executes the following steps for limit load design: 1. Calculate sectional forces at "**nSamples**" points along all beams using the initial cross sections. 2. For each element or predefined set of elements, the algorithm selects the first sufficient cross section from the related cross section family based on the utilization value specified at the "**MaxUtil**" input plug. This selection also incorporates the material assigned to the cross sections within the family. As a result, it is possible to use cross section families with varying materials. 3. If no modifications are required after step two, or if the maximum number of design iterations ("**Util Iter**") has been reached, the algorithm stops. Otherwise, it repeats from step one with the newly selected cross sections. The procedure is iterative in statically indeterminate structures due to the dependency of sectional forces on member stiffness, which results from cross-sectional dimensions and material properties.

Fig. 3.6.8.2: Cross section optimization using the "OptiCroSec" component on a cantilever wall.

{% file src="/files/cXP5dsZ4Ha9XvnCv3ive" %} Figure 3.6.8.2 illustrates an optimization scenario for a cantilever modeled with shell elements, resulting in thicker shell elements at the critical edges. The "CroSecs" input of the **"OptiCroSec"** component contains a constant family of shell cross sections. For shell elements, mechanical utilization is calculated by comparing the maximum stress at a point to the material strength, following the selected strength hypothesis (see section [3.5.1](/3-in-depth-component-reference/3.4-material/3.4.1-material-properties)). For steel, the Von Mises stress criterion is applicable. The optimization process for shells follows the same steps as for beams, with the algorithm ceasing once a cross section meets the set utilization threshold, which defaults to "1" (100%). Should the largest cross section in a family prove insufficient, the **"OptiCroSec"** component will issue a warning, as shown in fig. 3.6.8.2. The "Info" output details the reason for inadequacy concerning either maximum displacement or utilization targets. The output plugs "**MaxDispView**" and "**MaxUtilView**" respectively provide indices of elements failing the serviceability limit state (SLS) and ultimate limit state (ULS) criteria. These indices can be fed directly into the "ModelView" component's "View" input plug to highlight problem areas (see fig. 3.6.8.3). ## Design for Limiting Excessive Deflections at the Serviceability Limit State (SLS) ### Controlling Maximum Displacements For scenarios where overall displacement must be restricted, the "**MaxDisp**" input-plug initiates iterative design modifications before considering the ultimate limit state. This procedure, referenced in \[16], encompasses the following steps: * **Determination of Maximum displacements:** The maximum displacement for the load cases and load case combinations given via "**LCasesDisp**" are determined. If nothing is given there the load cases and load case combinations of "**LCasesUtil**" are used. The displacements retrieved encompass all nodal displacements and beam displacements at the element start-, mid- and end-positions. * **Adaptation Using Virtual Load Cases:** For the load case exhibiting the maximum displacement, a virtual load case is internally generated and calculated. The corresponding virtual energy produced by the maximum displacement load case with respect to all virtual load cases guides the resizing of element cross sections to meet the constraints defined in the "**MaxDisp**" input, which can interpret three types of input: * **Numeric Value**: Defines a displacement limit which compares to the absolute values of the structure's displacement vectors. * **Vectors**: These specify directional displacement limits, with the vector's length defining the maximum allowable displacement. * **Planes**: These restrict in-plane displacements, with the plane's distance from the global origin setting the displacement limit. This is useful for controlling horizontal movements in structures like floor slabs while ignoring vertical displacements. Figure 3.6.8.3 illustrates a frame under combined vertical and horizontal loads, where the horizontal displacement limit is set at 0.03 cm, and the vertical downward movement is limited to 0.29 cm. When multiple displacement criteria are specified, Karamba3D attempts to satisfy all conditions concurrently. * **Cross Section Adjustment**: The resizing of cross sections to achieve displacement limits is executed within a predefined number of iterations specified by "**Disp Iter**".

3.6.8.3: Optimization of frame displacements under horizontal and vertical loads. Multiple displacement criteria are applied simultaneously. Refer to "OptiDisp_Frame.gh" for details.

{% file src="/files/0xUMmmXoTUW0W7q8awrQ" %} Karamba3D supports two methodologies for integrating safety levels against maximum displacement and load-bearing limits: * **Simplified approach**: When using external loads at ultimate limit state level, one should keep in mind that this is approximately 1.4 times the loads used to check maximum displacement requirements. Thus one way of designing structures in Karamba3D is to limit material utilization to $$1/1.4 \approx 0.7$$ under characteristic loads (these are those usually given in the building codes) and use the resulting displacements directly for usability design. This approach eliminates the need for separate load combinations for ULS and SLS, directly using the resulting displacements for usability design. * **Accurate Approach**: Implement load superposition rules as defined by design codes, applying different safety factors for SLS and ULS conditions, configured via the "**LCasesDisp**" and "**LCasesUtil**" inputs respectively. There are cases when the above described procedure fails to converge. This concerns systems where the position of the maximum displacement constantly changes: Imagine a system which consists of a series of identical parts (e.g. frames) with identical loads: The first iteration will deal with the maximum displacement at the first subsystem, the second iteration with the maximum displacement of the second and so on. When the number of subsystems is larger than the maximum number of iterations some will not be optimized. When this happens alternative methods as described in subsequent sections should be employed. ### Displacement Control through Virtual Load Cases The principle of virtual forces, utilized to calculate structural displacements under specified loads, begins by applying a unit-load or set of unit-loads in the desired direction of displacement measurement. The term "virtual" denotes that the applied forces are conceptual and are assumed to be negligible in magnitude to avoid invoking second-order theory effects or large displacement phenomena. The numerical value of virtual loads, however need not be small and is typically standardized at one for simplicity. Figure 3.6.8.4 demonstrates the application of this principle on a cantilever beam subjected to a point-load at its tip. To limit the downward tip displacement, a virtual load of "1" kilonewton pointing downwards is applied. Displacement limitation is enforced by setting the "**LCasesDisp**" input with the actual load cases to consider and disabling cross section design for strength by inputting "-" as the load case name, which is unrecognized in the model. The "**MaxWork**" input allows setting a target for the maximum virtual work per virtual load case, measured in kilonewton-centimeters; a value of "1" restricts the movement to 1 cm. The output from "**MaxDisp**" typically indicates a conservative displacement limitation, especially if the largest cross section sizes of the applied families are adequate. Additionally, instead of translational loads, moments can be applied to control rotational displacements at specific structural points.

.4: Utilizing virtual forces to control displacement in a cantilever beam.

{% file src="/files/9Ax320vELfQLbnOSoarH" %} ## Considerations for Iterative Convergence and Structural Safety The iterative process for optimizing cross sections may not always guarantee convergence. Verification of results can be achieved using the "Utilization of Elements" component, which evaluates elements per Eurocode 3, accounting for the entire cross section's load-bearing capacity. The "Stress/Strength Ratio" output from the "ModelView" component indicates the stress-material strength ratio at any cross-sectional point, excluding considerations like buckling under compression. Regarding ultimate limit state considerations, the lower-bound theorem of plasticity ensures that the structure will suffice under given loads at any iteration, even though some elements might exhibit over-utilization, assuming the material exhibits sufficient plasticity, such as steel. As the number of iterations increases, the structural system tends to become more statically determinate. The profile selection procedure assumes that the cross sections of a family are ordered: starting with your most favorite and descending to the least desired cross section. In the cross section table "CrossSectionValues.bin" that comes with Karamba3D all families are ranked according to their height. The cross section with the smallest height comes first, the one with the largest height last. When using cross section area as sorting criteria, structures of minimum weight (and thus approximately cost) result. See section [3.3.11](/3-in-depth-component-reference/3.3-cross-section/3.3.13-read-cross-section-table-from-file) for how to switch between minimum height and minimum weight design. Ordering the profiles by area may lead to structures where the cross section heights vary significantly from one beam to the next. In order to check whether a given beam cross section is sufficient, Karamba3D applies a procedure for steel beams according to Eurocode 3 (EN 1993-1-1) (see [\[5\]](broken://pages/-MCkEPufKvmRk8DHQDJm) for details). The interaction values for the cross section forces $$k\_{yy}$$*,* $$k\_{yz}$$and so on get calculated according to EN 1993-1-1 appendix B. The values $$C\_{my}$$*and* $$C\_{mz}$$are limited to a minimum of 0.9 by default. This means that sideways sway initiates buckling which is on the safe side in case of non-sway frames. When the input-plug "SwayFrame" is set to 'False' the limit of 0.9 does not apply. The design procedure takes account of normal force, biaxial bending, torsion and shear force. For more details see section [A.2.6](broken://pages/-MCkEPuemaDAtAo6cKE6) and the master thesis of Jukka Mäenpää [\[9\]](broken://pages/-MCkEPufKvmRk8DHQDJm). It is possible to switch off the influence of buckling for single members or set user defined values for the buckling length (see section [3.1.10: Modify Element](/3-in-depth-component-reference/3.1-model/3.1.10-modify-element#buckling-property-for-cross-section-optimization)). The adverse effect of compressive normal forces in a beam can be taken into account globally (see section [3.6.5](/3-in-depth-component-reference/3.5-algorithms/3.5.5-buckling-modes)) or locally on the level of individual members. The procedure applied in Karamba3D for cross section optimization works on member level. A crucial precondition for this method to deliver useful results is the determination of a realistic buckling length $$l\_b$$of an element. For this the following simplification -- which is not always on the safe side -- is applied: Starting from the endpoints of an element, proceeding to its neighbors, the first nodes are tracked that connect to more than two elements. The buckling length is determined as the distance between these two nodes. It lies on the safe side in case of endpoints held by the rest of the structure against translation. When beams are members of a larger part that buckles (e.g. a girder of a truss) then the applied determination of buckling length produces unsafe results! One should always check this by calculating the global buckling modes (see section [3.6.5](/3-in-depth-component-reference/3.5-algorithms/3.5.5-buckling-modes)). In case of a free end the buckling length is doubled. Compressive normal forces in slender beams reduce their allowable maximum stress below the yield limit. Visualizing the level of utilization with the "ModelView"-component will then show values below 100% in the compressive range. The design procedure applied in Karamba3D takes lateral torsional buckling into account. An elements lateral torsional buckling length is calculated in the same way as for conventional buckling. The buckling length for lateral torsional buckling can be set manually via the property "BklLenLT" of the "Modify Beam"-component. In the course of cross section optimization Karamba3D checks the cross sections for local buckling and issues a warning if necessary. The check for local buckling uses the classification of cross sections into classes 1 to 4 according to EN 1993-1-1. Class 4 cross sections are susceptible to local buckling. During the optimization of cross sections normal forces$$N\_{II}$$are updated according to the setting made for the respective load cases and load case combinations. ## Comprehensive Input and Output Data Overview for the "OptiCroSec" Component ### Input Configuration Details The **"OptiCroSec"** component is equipped with several input plugs to facilitate the optimization of structural cross sections, detailed as follows:
Input PlugDescription
"Model"Specifies the structure to be optimized.
"ElemIds"Identifies specific elements for optimization. If unspecified, the entire model undergoes optimization.
"GroupIds"Lists identifiers for groups of elements that should have uniform cross sections, definable via element set names or regular expressions.
"CroSecs"Contains an ordered list of cross section families, from preferred to least preferred, identified by their "family" property.
"MaxUtil"Sets the target utilization value for elements, where 1.0 represents full utilization. Values less than 1.0 may be used to reserve structural capacity for uncertain early design stages or when operating under characteristic loads - then this value should be less than 0.7.
"LCasesUtil"Specifies load cases and combinations for assessing load-bearing capacity, defining the ultimate limit state. If unspecified, all model cases are considered. In case the load case of given name does not exist no strength design takes place.
"MaxDisp"Limits maximum structural deflections. Accepts numerical values, vectors, and planes, with each input being validated against every applicable displacement load case.
When working with design loads keep in mind that those are roughly a factor of “1.4” above the level to be considered for usability.
"LCasesDisp"Names load cases and combinations that constrain maximum nodal and element displacements (at start, middle, end), defining the serviceability limit state. Defaults to "LCasesUtil" settings if unspecified.
Additional configurations accessible through the **"Settings"** button include:
Input PlugDescription
"MaxWork"Sets the maximum virtual work for each virtual load case relative to actual cases.
"LCasesVirt"List of names of load cases and load case combinations specifying virtual loads.
"Util Iter"Defines the maximum number of iterations for achieving sufficient load-bearing capacity in the ultimate limit state. The default value is five.
"Disp Iter"Specifies the maximum iterations for meeting displacement criteria. The design iterations for maximum displacement come before those for load bearing capacity.
"Disp Inc"Determines the number of stiffness matrix updates per displacement iteration to accurately model internal force redistribution due to evolving cross-section stiffness. Setting up the stiffness matrix and solving it are computationally expensive. The higher the number of updates the more accurately one models the redistribution of internal forces due to changing cross seciton stiffnesses. The default value is 2.
"Disp Tol"Establishes a tolerance factor for achieving displacement targets from below. This value multiplied with the specified maximum displacement is the allowable difference between target- and actual displacement value.
"NSamples"Specifies the number of points along beams for utilization assessments, defaulting to three.
"Elast"Toggles between elastic and plastic cross-section design. If set to “True” (the default) cross section design is done within the elastic range. This means that under given loads the maximum resulting stress in a cross section has to lie below the yield stressf_yof the material. In case of materials with high ductility (like steel) the plastic capacity of cross sections can be exploited. Depending on the cross section shape the plastic capacity is 10 % to 20 % higher than the elastic capacity. Set “Elast” to “False” in order to activate plastic cross section design. When enabling plastic cross section design do not be surprised that the “ModelView” reports utilization-levels beyond 100 %. The reason is that Karamba3D assumes linear elastic material behavior.
"gammaM0"Material safety factor according to EN 1993-1-1 in case that failure is not initiated by buckling. This applies in case of tensile normal force or zero buckling length. Its default value is 1.0. In some European countries this factor lies above 1.0. The default value of gammaM0 can be set in the karamba.ini-file.
"gammaM1"Material safety factor according to EN 1993-1-1 in case that buckling initiates failure. This applies in case of compressive normal force and non-zero buckling length. The default value again lies at 1.1 - may be specified differently in your national application document of EN 1993-1-1. The default value of gammaM1 can be set in the karamba.ini-file. Attention: in Karamba3D 1.3.3 the default value of gammaM1 was 1.0!
"SwayFrame"Indicates susceptibility to sideways sway buckling, set to 'True' by default to ensure conservative design outcomes.
### Output Data Description The output of the **"OptiCroSec"** component provides essential data regarding the optimized structure:
Output PlugDescription
"Model" Returnd the structure with optimized cross sections
"Info"Reports any issues encountered during the optimization process.
"Mass"Indicates the total mass of the optimized structure.
"MaxDisp"Shows the maximum displacement after the final design iteration.
"DEnergy"Returns the internal energy of the structure post-optimization.
"MaxUtilView"Lists element indices where the maximum cross section within their family was insufficient for utilization needs. Can be directly plugged into the "View"-input of the "ModelView"-component.
"MaxDispView"Lists element indices failing to meet displacement criteria during iterations, useful for detailed evaluations in the "ModelView" component. Can be directly plugged into the "View"-input of the "ModelView"-component.
The aim of the design procedure applied in Karamba3D is to render plausible cross section choices. Be aware that it builds upon assumptions like the correct determination of buckling lengths. {% file src="/files/M2537uh6cF1g4HRk2gpH" %} {% file src="/files/M3ZNMaitCQGDlDGrylOZ" %} {% file src="/files/u1phI3H2Po1Bo9q3hN5E" %} {% file src="/files/mTP8sL7wf0u5v0JMzuP2" %} {% file src="/files/tYb916iuuG2Psch4VuDZ" %} {% file src="/files/FQ5tjY0AuGYtKoJdOXkp" %} {% file src="/files/ATEbLPnuukl33KVW2xnY" %} {% file src="/files/6kgIAatjPPN57RU8agol" %} {% file src="/files/U25HlllWwx8PrsRVpR3W" %} *Additional examples can be found in the Grasshopper main tab under Karamba3D > Help > Examples > Local Examples > Algorithms > Optimize Cross Section.* # 3.6.9: BESO for Beams Evolutionary structural optimization (ESO) constitutes a method of topology optimization which was pioneered by Y.M. Xie and G.P. Steven. The underlying principle is simple: One starts from a given volume made up from structural elements on predefined supports and with preset loads acting on it. Calculating the structural response will show that there are regions which carry more of the external load than others. Now one removes a number of those elements of the structure that are least strained and thus least effective. Again the response of the now thinned out model is determined, under-utilized elements removed and so on. This iterative procedure stops when a target volume or number of remaining structural elements is reached. ![Fig. 3.6.9.1: Cantilever with initially regular mesh after application of the “BESO for Beams”-component](/files/-MCkEYhu_4_D0y66gB4I) The above algorithm can be viewed as a way of tracing the internal force flow through a structure and removing those elements that do not form part of it. Fig. 3.6.9.1 shows a cantilever after applying the **“BESO for Beams”**-component on it. The algorithm works on beam and truss elements only. For shells a separate component exists (see section [3.5.10](/3-in-depth-component-reference/3.5-algorithms/3.5.10-beso-for-shells)). ![Fig. 3.6.9.2: Triangular mesh of beams before (a) and after (b) applying the “BESO for Beams”-component](/files/-MCkEYhvFcXi1lXy76cD) Fig. 3.6.9.2 shows the **“BESO for Beams”**-component at work. On the left side one can see the initial geometry which is a triangular mesh derived from a surface. There exist two load cases with loads acting in the plane of the structure in horizontal and vertical direction respectively. Three corner nodes of the structure are held fixed. The right picture shows the optimized structure reduced to 45 % of its initial mass in the course of 20 design iterations. ## Here the description of the input parameters: | | | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Model"** | Receives the model to be processed. | | **"ElemIds"** |

There are two alternatives concerning this input parameter:

  • No input: The whole of the structure will be included in the optimization procedure.
  • The input consists of a list of strings: All elements whose identifiers match take part.
| | **"LCases"** | List of load cases to be considered. Zero is the index of the first load case. Considering the total effect of several load cases amounts to adding up their individual influences on an element. | | **"TargetRatio"** | Ratio of the target mass of beam- or truss elements to the initial mass of beams/trusses in a structure. When determining the initial mass all beam- or truss- elements of the structure – irrespective of state of activation – count. In the target structure only active elements contribute to its mass. This enables one to apply BESO-components in series. Depending on the activation status of the model elements, applying **“BESO for Beams”** will lead to an increase or decrease in the number of active elements. The activation status of individual elements can be set by means of the **“ModifyBeam”**- and **“ActivateModel”**-components. | | **"MaxChangeIter"** | Number of iterations within which the target mass of the structure should be reached. If the number of iterations is selected too low then it may occur that single beams get disconnected from the main structure and they seem to fly. The reason for this lies in the fact that Karamba3D applies a so called soft-kill approach for thinning out the structure: Elements are not removed but simply given small stiffness values. This ensures that structural response can be calculated under all circumstances. | | **"MaxConvIter"** | Maximum number of additional iterations for convergence after the structures mass has reached its target value using **“MaxChangeIter”** iterations. | | **"GroupIds"** | Expects a list of strings. Elements that match a given list entry take part in the optimization and belong to one group. They get collectively activated or deactivated during force path finding. A structure may consist of active and non-active elements. The initial state of a group is determined by the state of the majority of its elements. Groups need not be disjoint. | ## By clicking on the “Settings” bar you can unfold the following input-plugs: Factors for weighting forces/moments: The **“BESO for Beams”**-component lets you select weighting factors for the different force and bending components in an element. The weight of an element is determined on the basis of the density of deformation energy induced by individual cross section force components. Multiplication by the corresponding user given weighting factor and adding up the component contributions results in the element weight. The weight of groups results from the average of their members. These are the available weighting factors: * **“WTension”**: factor for axial tension force * **“WCompr.”**: factor for axial compression force * **“WShear”**: factor for resultant shear force * **“WMoment”**: factor for resultant moments **"BESOFac"**: Say in each iteration step there needs to be a mass of $$n\[kg]$$ removed in order to meet the structure's target mass in the given $$nChangeIter$$ number of iterations. With $$BESOFac = m$$ there will be $$(m+1) \cdot n$$ active elements moved to the pool of inactive elements. An evaluation of the structure's response follows. In a second step $$m \cdot n$$ members get flipped from inactive to active so that the balance is right again. This adds a bi-directional component to the process which often leads to improved results. **“MinDist”**: In some cases one wishes to limit the number of elements that get added or removed in a certain area. **“MinDist”** lets you select the minimum distance in meter between the endpoints of elements that may be changed in one iteration. **“WLimit”**: At the end of the BESO-process it often occurs that a small fraction of the elements is much less utilized than the average. **“WLimit”** lets you remove those elements whose weight is below **“WLimit”** times the average weight of elements. ## On the right side of the **“BESOBeam”**-component these output-plugs exist: | | | | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Max.disp"** | Maximum displacement of the resulting model from among all load cases. | | **"Model"** | Structure with element activation according to the force path found. | | **"Hist"** | A data tree which contains for each iteration step a list of boolean values that signify whether an element is active (true) or inactive (false). The boolean values map directly on the model elements. Using a **“Tree Branch”**-component with a slider connected to a **“Activate Model”**-component (see section [3.1.5](/3-in-depth-component-reference/3.1-model/3.1.5-activate-element)) lets you inspect the history of the BESO-process (see fig. 3.6.9.2). | | **"Is active"** | Renders a list of “True”/“False” values – one for each element. “True” signals that the corresponding element is part of the final structure (i.e. active). Otherwise it contains a “False” entry. | | **"Weights"** | List of element or group weights in ascending order in the final structure. This can be used as a qualitative check of the result: The more evenly distributed the weights, the better utilized the structure. There will always be force concentrations around supports and external loads which show up as sharp peaks. A good way of visualization is to use a **“Quick Graph”**-component (see fig. 3.6.9.2). | {% file src="/files/ujFlL5Qv4hXbVOb0hwcj" %} {% file src="/files/ZOlZqP58LwvbmkO7NQTi" %} {% file src="/files/VZTia35yIZMajhZXNle2" %} *Additional examples can be found in the Grasshopper main tab under Karamba3D > Help > Examples > Local Examples > Algorithms > BESO.* # 3.6.10: BESO for Shells An in-depth description of the BESO for shells algorithm used in Karamba3D can be found in [\[7\]](/appendix/bibliography). Fig. 3.6.10.1 shows an example which starts off from a rectangular wall which supports two point-loads at each of its upper corners. The result of the BESO procedure is the X-shaped structure shown on the left side. ![Fig. 3.6.10.1: BESO for a rectangular plate under two corner loads](/files/-MCkESuxev-7E4kbzN_F) These are the main parameters that control the optimization process: | | " | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Model"** | Model to be optimized | | **"ElemIds"** | List of identifiers of shells that take part in the optimization. In case of an empty list (the default) all shells are included. | | **"LCases"** | List of load cases to be considered. Zero is the index of the first load case. Considering the total effect of several load cases amounts to adding up their individual influences on an element. | | **"TargetRatio"** | Ratio of the target mass to the initial mass of the shells in a structure. When determining the initial mass all shell elements of the structure – irrespective of state of activation – count. In the target structure only active elements contribute to its mass. This enables one to apply BESO-components in series. | | **"MaxIter"** | Maximum number of iterations | Under the submenu **“Settings”** these additional options can be used to further customize the optimization procedure: | | | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"ER"** | Is short for evolutionary ratio and defines the ratio between the volumes $$V\_i$$ and $$V\_{i+1}$$ of the optimized structure in two consecutive steps: $$V\_{i+1} = V{i} \cdot (1\pm ER)$$. The sign of “ER” depends on whether elements shall be added or removed. In case that $$ER<0$$ – which is the default –$$ER$$is set automatically: $$ER = (1-TargetRatio)/MaxIter + AR\_{max}/2$$. In case that **“ER”** is too small, the target mass of the optimized structure can not be reached within **“MaxIter”** steps. | | **"ARmax"** | The ratio between maximum number of elements to be added per step and all shell elements. | | **"Nhist"** | Number of iterations between those steps which are used for calculating the convergence criteria. | | **"Conv"** | Relative change of the mass between two iterations $$N\_{hist}$$ cycles apart below which convergence is assumed. | | **"Rmin"** | In order to avoid the formation of checkerboard patterns a filter scheme is used for calculating the fitness of individual elements (see [\[7\]](broken://pages/-MCkEPufKvmRk8DHQDJm), section 3.3.2). $$R\_{min}$$ defines the radius of influence in meters for determining the element sensitivity. It is thus important to choose this value according to the mean element size. If $$R\_{min} <0$$ (the default) then $$R\_{min}$$ is set equal to the characteristic element length which is calculated as $$(totalArea/numberOfElements)^{0.5} \cdot 2$$. | | **"Rexp"** | Determines how the strain energy at nodes within the distance $$R\_{min}$$ of the element center is weighted for calculating an elements sensitivity. The weight is determined as $$w =(R\_{ij}/\sum R\_{ij})^{R\_{exp}}$$. Here $$R\_{ij}=R\_{min}-R$$ with $$R$$ being the distance between a sample node and the center of the element. $$\sum R\_{ij}$$ is the sum of the center distances of all nodes closer than $$R\_{min}$$ to the element center. | | **"KillThick"** | The BESO for shell procedure makes use of a so called “soft kill”-approach. Instead of removing elements from the model they are made very soft by reducing their thickness. With the input-plug **“KillThick”** a value other than the default 0.00001 m can be selected. | The output-plugs of the **“BESOShell”**-component return the following data: | | | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Model"** | Model which results from the BESO optimization. | | **"ModelHist"** | List of intermediate models – one for each iteration step of the BESO procedure. | | **"CHist"** | History of the volume weighted compliance of the structure which drives the BESO procedure. When fed into a **“Quick Graph”** component one can check whether the BESO procedure converged: at the end the chart should be horizontal. If that is not the case try a smaller **“ER”**-value. | | **"VHist"** | List of values which chart the development of the volume of the shells to be optimized. | | **"Info"** | Returns information regarding the solution process in case something goes wrong. | {% file src="/files/DMobMTpRxVruNWYACShR" %} {% file src="/files/ccfRy4CADGxSnCYU4E5Z" %} # 3.6.11: Optimize Reinforcement The **“Optimize Reinforcement”**-component calculates reinforcement quantities for arbitrary shells. The algorithm is based on the sandwich model approach of Marti (see [\[6\]](/appendix/bibliography) or [\[4\]](/appendix/bibliography)). Each load-case is considered separately and the maximum reinforcement of all load-cases is chosen.

Fig. 3.6.11.1: Calculation of reinforcement quantities for a 1mx1m plate and an in-plane tensile 50kN load.

{% file src="/files/YRmz2IwX8ied3RNV8z6F" %} Fig. 3.6.11.1 shows a rectangular plate of size $$1m$$ by $$1m$$ with a uniform tensile line-load of $$50kN/m$$ which translates to two point-loads of $$25kN$$each. The first step consists of defining a reinforced concrete cross section via a **“Cross Section”**-component (see section [3.3.2](/3-in-depth-component-reference/3.3-cross-section/3.3.2-shell-cross-sections)). The definition of reinforcement layers does not impact the displacements or cross section forces of the model. It merely forms the basis for calculating reinforcement quantities using linear elastic cross section forces. For reinforcement design it is assumed that the material in layer zero (usually concrete) has no tensile and infinite compressive strength. Since the latter is a simplification, one should assure a sufficient height of the concrete cross section by using the **“Optimize Cross Section”**-component first. The input-plugs of the **“Optimize Reinforcement”**-component are similar to those of the **“Optimize Cross Section”**-component: | | | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **"Model"** | Structure for doing reinforcement design | | **"ElemIds"** | Identifiers of elements for which reinforcement quantities should be calculated. If not specified, optimization is carried out for all reinforced concrete cross sections. | | **"GroupdIds"** | List of identifiers of groups of elements that take part in reinforced cross section design and shall have uniform reinforcement. | | **"MaxUtil"** | Target value of the reinforcement utilization where 1.0 means full utilization - the default. | Under the submenu **“Settings”** reside two plugs which let you specify the partial safety factors for concrete (**“gammaMc”**) and steel (**“gammaMs”**). The former exists for future use, since currently concrete is assumed to be infinitely strong in compression. The latter is set to 1.15 which constitutes the standard value according to Eurocode 2 (see [\[3\]](broken://pages/-MCkEPufKvmRk8DHQDJm)). The output of **“Optimize Reinforcement”** comprises these plugs: | | | | ------------ | -------------------------------------------------------------- | | **"Model"** | Structure with optimized reinforcement | | **"Info"** | Warnings regarding the reinforcement design process | | **"Mass"** | Total mass of reinforcement after optimization in kilograms | | **"Disp"** | Maximum displacement of the structure for each load-case | | **"Energy"** | Elastic deformation energy of the structure for each load-case | The **“ShellView”**-component lets one display the thickness of the reinforcement layers and the stresses there (see fig. 3.6.11.1). The input-plug **“LayerInd”** sets the index of the layer to be displayed. The concrete cross section has index zero, index one corresponds to the top-, index four to the bottom-most reinforcement layer. The Z-direction of the local coordinate system points to the top of the cross section. The entry **“Local layer axes”** under **“Display Scales”** in the component **“ModelView”** lets one enable, disable and scale the arrows of the local coordinate system. In the example of fig. 3.6.11.1 the default reinforcement material BSt500 with a characteristic yield strength of $$f\_{y,k}=50kN/cm^2$$ leads to a necessary amount of reinforcement of $$a\_s = \frac{50kN \cdot 1.15}{2 \cdot 50kN/cm^2}$$. This is equivalent to a layer thickness of 0.00575 cm. The “2” in the denominator results from the fact that there are two reinforcement layers (of index one and four) which point in the direction of the tensile force. {% file src="/files/lvMg31lveEo3WnkDdBi8" %} {% file src="/files/Xwnad9Tusr5V2GNKvOg0" %} # 3.6.12: Tension/Compression Eliminator This component was programmed by Robert Vierlinger The **“Tension/Compression Eliminator”**-component removes elements from a model based on the sign of their axial force. ![Fig. 3.6.12.1: The “Tension/Compression Eliminator”-component](/files/-MCkEaMHxr-GJSwzUf2D) These are the available input parameters: | | | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **"Model"** | Structure to be processed. | | **"MaxIter"** | The removal of tensile or compressive elements works in an iterative fashion. The procedure stops either when no changes occur from one step to another or if the maximum number of iterations **“MaxIter”** is reached. | | **"BeamInds"** | Indexes of the elements that may be removed in the course of the procedure. By default the whole structure is included. | | **"LCase"** | You can specify a special load case to consider. The default is the first load-case in the model. | | **"Compr"** | If “True”, then only members under compression will be kept. Otherwise only members under tension will survive. This value is “False” by default. | Elements selected for removal are assigned a negligible stiffness (i.e. a soft-kill approach is used). {% file src="/files/gPshpV7s5BnVRXHBMDJ7" %} {% file src="/files/lVioUJKyVF0W42goNUSf" %} # 3.7 Results The results category consists of three sections. The first contains components that apply to a structure in general. Components of the second and third category apply specifically to beams and shells respectively. # 3.7.1 General Results This section describes components that retrieve calculation results that are not bound to a specific type of structural element. # 3.7.1.1 ModelView The **“ModelView”**-component of the **“Results”** subsection controls the general display properties of the structural model (see fig. 3.7.1.1.1). More specific visual properties that relate to beam and shell elements can be defined with the **“BeamView”** and **“ShellView”**-component. The viewing options get stored in the model. Settings of view-components thus stick with the model and remain valid further down the data-stream until changed by another view-component. When adding a **“ModelView”** to the definition it is sometimes a good idea to turn off the preview of all other components so that they do not interfere. Clicking on the black menu headings unfolds the **“ModelView”**-component and unveils widgets for tuning the model display. Each of these will be explained further below. The range and current value of the sliders may be set by double-clicking on their knob. ## **Input-plugs** The **“ModelView”**-component features five plugs on its left side:

Fig. 3.7.1.1.1: Partial view of a model

{% file src="/files/yhjKhpqDffVgrLrIMUfJ" %} ### 1. Model Expects the model to be displayed. ### 2. LCase Selects the load-case to be displayed parametrically. The input is a string containing selection criteria separated by "/". For details see the section about the ["Load-Case Selector"-component](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.7.1.2-result-selector). By default, the results of all calculated load-cases are displayed. If "Load Case Combination" in the "Result Selection" submenu is set to anything other than "Default", it overrides the selection via "LCase." The model's load-case-selection settings remain unchanged until a downstream ModelView component resets them. ### 3. Colors Color plots for e.g., stresses use a color spectrum from blue to white to red by default. One can customize the color range by handing over a list of RGB-values to the **“Colors”**-plug. There have to be at least four colors given. The first color is used for values below, the last color for values above the current number range. The remaining colors get distributed over the number range (see fig. 3.7.1.1.2). The colors are centered on zero if zero is part of the number range. Otherwise, the colors spread evenly between lower and upper numerical limit. In case you want to change the coloring defaults, go to "Edit User Settings" in the Karamba3D menu under "Settings". There it is also possible to switch off the centering around zero by setting “center\_color\_range\_on\_zero” to false. Alternatively, it is possible to select from a list of color-ranges via the component's context menu: right-click on the component, go to item "Colors" and select a color range. ### 4. View This plug-in allows users to choose specific parts of a model to be displayed. By default, the input is an empty string, indicating that the entire model should be visible. When multiple inputs are provided, they are combined using an AND operation. The input plug-in supports various input types: * **Strings:** Identifier or indexes of elements to be displayed. Besides their names elements can be referred to via their index number. This allows to use the output **"MaxUtilView"** and **"MaxDispView"** of the [**"OptiCroSec"**](/3-in-depth-component-reference/3.5-algorithms/3.5.8-optimize-cross-section)-component for diagnostic model views. \ As illustrated in Figure 3.7.1.1.1, regular expressions are also supported, starting with the character “&” and following C# regular expression conventions. Each model element identifier is compared against the string list, and any matching entry results in the element being displayed. For instance, the first example in Figure 3.7.1.1.1 limits visibility to element “A,” the second to element “B,” the third uses a regular expression to match elements “A” or “C,” and the fourth matches elements from “A” to “C.” A simplified regular expression ending with "$" can be used to select all elements whose names begin with the specified characters before the "$" sign. * **Planes:** Displays all elements and associated items located on a specified plane. * **Straight Lines:** Defines a vertical plane, controlling the visibility of elements, such as those aligned along a grid axis. * **Plane Surfaces:** Adds elements to the visible set if all their nodes lie entirely on the specified surface. * **Volumes:** Selects all elements completely enclosed within a defined solid brep. This functionality enhances model visualization by offering flexible and precise control over element visibility. The example below shows the different options in action. {% file src="/files/bCbPb6jvWxKxGSap5Fq0" %} ### 5. defDir If the input is a vector, it defines the direction of the displacement component to be displayed, which is useful for viewing specific displacements, such as vertical ones. Alternatively, a plane can be provided to project the displacements onto it, allowing for the visualization of horizontal displacements, for example. By default, the resultant displacements are displayed.

Fig. 3.7.1.1.2: Color plot of strains with custom color range.

{% file src="/files/JB6joVT5q5fOVlIzEB7p" %} ## Output-plugs There are five output plugs on the **"ModelView"**-component: | | | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **“Model”** | Is the model which was fed in on the left side with viewing options attached. | | **“DefMesh”** | You can get the mesh of the shells and beam cross sections of the deformed model for further processing. It is a list of meshes with each item corresponding to one shell or beam. | | **“DefAxes"** | Delivers the axes of the beams of the deformed structure as interpolated 3rd degree nurb-splines. Use the Length/Subdivision slider to set the number of interpolation points. | | **"DefModel”** | When there are results available from a statical calculation, the translational nodal deflections are scaled and added to the node coordinates of the original model so that the **"defModel"**-output contains the deformed geometry. | | **"DefMax"** | Maximum displacement of the displayed model parts in centimeter. The setting of the "defDir"-input is taken into account, the deformation scaling factor not. | ## **The “Display”-submenu**

Fig. 3.7.1.1.3: Local axes of cantilever composed of two beams, reaction force and moment at support

Fig. 3.7.1.1.4: Via the Annotations-submenu additional model information can be displayed.

The **“Display”**-submenu contains check boxes and sliders to enable/disable and scale displacements, reaction forces at supports, load-symbols, support-symbols, local coordinate systems and symbols for joints at the endpoints of elements (see fig. 3.7.1.1.3). The displacement scale influences the display and the output at the **"defMesh"**-, **"defAxes"**- and **"defModel"**-plug. It has no effect on stresses, strains, etc. The colors of the local coordinate axes red, green, blue symbolize the local X-, Y-, and Z-axis. **"Element axes":** If enabled the **“DefAxes”** output-plug emits the axis of the deformed elements as lines and shows them on the Rhino-canvas. **"Eccentricities": V**isualizes beam eccentricities as blue lines at the end-points if active. ## **The “Render Settings”-submenu** The slider entitled **“Length/Segment\[m]”** lets one control the distance at which beam results (displacements, forces, moments, etc.) are plotted (see [3.6.7](/3-in-depth-component-reference/3.6-results/3.7.2-results-on-beams/3.6.7-beamview)). It also sets the number of control points that are used for the **“defAxes”**-output and for displaying. In case of very large models or when the unit for geometry input is wrong, the default length per segment setting may lead to very long rendering times. To avoid this the karamba.ini variable "**MaxEvaluationPointsInModel**" limits the overall number of evaluation points to 30000 by default. In some cases, the color display of results gets distorted by the presence of stress concentrations or utilization peeks. They make much of the structure look unstrained with some small patches of color where the peeks are. The **“Upper Result Threshold”**- and **“Lower Result Threshold”**-sliders let you eliminate these extreme values. In case of the **“Upper Result Threshold”**-slider a value of x% sets the upper boundary value of the color range in such a way that x% of the actual value range is below. For the lower threshold it is vice versa. Values in the model beyond the given thresholds are given special colors to make them easily recognizable. By default, the result threshold values given above refer to the value range in percent. Sometimes it turns out to be practical to prescribe absolute values as thresholds (e.g., the yield stress of a material). The radio button group “Result Threshold as” can be used to switch between relative and absolute thresholds. Limiting the value range of utilization values can be confusing: If the result thresholds are given in percent, then setting the lower threshold to zero and the upper to 100 displays the full range of utilization values. If the result thresholds are given as absolute values, then a lower threshold of −100 and an upper threshold of 100 limit the color range to the areas where the material resistance is sufficient. ## The "Annotations"-submenu The "Annotations"-submenu lets one display model related text information on the canvas (see fig. 3.7.1.1.4). Use the "Text Height Factor"-slider to scale the display test. This controls also the character size of output further downstream (e.g., numbers on cross section force diagrams). For a more fine-grained control of the text output see the comments in the "karamba.ini"-file. The "Text Offset" controls the position of the text information relative to the elements. The **“Annotations”** menu contains checkboxes for adding visual information to parts of the model as follows: | **"Node indices"** | attaches node-indexes to nodes | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **"Element indices"** | attaches element-indexes to elements | | **"Element ids"** | displays the element identifiers | | **"CroSec names"** | displays the name of the cross-section of each element | | **"Material names"** | displays the name of the material of each element | | **"Load values"** | adds the numerical values of loads or point masses to the corresponding symbols | | **"NII"** | prints the value of second order theory normal forces $$N^{II}$$ for all elements where it is not equal to zero. For the meaning of $$N^{II}$$ see section [3.6.2](/3-in-depth-component-reference/3.5-algorithms/3.5.2-analyzethii) | ## **The “Cross Section Color”-submenu** Here one can enable the display of element-, cross section- and material-colors. See sections [3.1.6](/3-in-depth-component-reference/3.1-model/3.1.6-create-linear-element/3.1.6-line-to-beam), [3.3.1](/3-in-depth-component-reference/3.3-cross-section/3.3.1-beam-cross-sections) or [3.4.1](/3-in-depth-component-reference/3.4-material/3.4.1-material-properties) for how to set them. In order to to visualize the colors enable **"Cross section"** under **"Render Settings"** of the "**BeamView"-** or "**ShellView"**-component. ## **The “Result Selection"-submenu** This submenu is provided for convenience and mirrors the functionality of the “Result Selection” submenu within the “Result Selector” component (see section [3.7.1.2](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.7.1.2-result-selector)).\ When the load case combination is set to **“Default”**, the display is controlled by the input plug **“LCase”**. If a different option is selected, the settings in the **“Result Selection”** submenu take precedence and override the choice from the input plug. {% file src="/files/cbaqMoRchW9gMZ2bWoMD" %} {% file src="/files/ahyoGGLVr8cO9BGiUqwE" %} {% file src="/files/PJWeXyALkKZ15D0lOiJA" %} # 3.7.1.2 Result Selector The "Load-Case Selector"-component helps in creating selection strings which define what load-case result to output for each point of a model.\ A selection string (see fig. 3.7.1.2.1. top right) starts with the name of the load-case-combination to select from and contains zero or more selection specifiers separate by "/". It can be supplied as the "LCase"-input for all result components and comes out at the component's "**LCase**" output-plug. The selection string is stored in the model which results at the "**Model**"-output-plug and serves as the default selection for ensuing result-retrievals. The model's default selection shows up in its string representation (see fig.3.7.1.2.2, bottom right).

Fig. 3.7.1.2.1: Selection of load-case results for each

{% file src="/files/lQ9GqiuhUQCwNRYWuzpK" %} Fig. 3.7.1.2.1 shows a beam on two supports with two load-cases "q1" and "q2". "q1" contains a constant upward load of 1kN/m at the cantilevering parts. "q2" acts downwards on the span between the supports. Two load-case-combinations "SLS" and "ULS" exist which combine the load-cases "q1" and "q2" into four combined load-cases each (see bottom right panel of fig. 3.7.1.2.1). The input-plug "**Model**" receives the model from which to select results. In the drop-down menu under "**Load Case Combi**" one can select from among the active load-case-combinations. Active load-case-combinations are those which were selected for analysis in e.g., an upstream "Analyze"-component. When placed directly after an "Assemble"-component all load-cases and load-case-combinations are assumed to be active.\ With the input "**LCInd**" it is possible to select from the current load-case-combination a load-case of specific index. The indexes are zero-based and correspond to the order in which a load-case-combination gets disassembled (see section ["Disassemble Load-Case-Combination"](/3-in-depth-component-reference/3.2-load/3.2.4-load-case-combinations/3.2.5.2-disassemble-load-case-combinaton)). Selection via index overrides queries for minimum or maximum values of a response property. The "**Min**" and "**Max**" radio buttons in submenu "Min/Max" let you select between minimum and maximum result values. By default, both are active. Without the specification of a leading property (see explanation below) this results in the output of the envelope of all response properties. In case of result vectors (think of displacements) the hull gets computed for each component separately. Without a selection of "**Min**", "**Max**" or load-case index via "**LCInd**" results for all load-cases of a load-case-combination will be output.

Fig. 3.7.1.2.2: Diagram of shear forces in Z-direction which accompanies the minimum bending moment My.

The maximum and minimum result envelops of different result properties generally do not occur in the same load-case. For detailed design they should therefore be used cautiously. The submenus "**For Beams**", "**For Shells**", "**For Displacements**" and "**For Supports**" offer a more fine grained access to the result properties of load-case combinations (see fig. 3.7.1.2.1). For the groups of response quantities that come with beams, shells, displacements and supports a leading property can be selected - like "My" in fig. 3.7.1.2.2. The output of the other quantities of the response group will then be the accompanying ones. {% file src="/files/R5qjyG42ABJ04VxbYXUL" %} # 3.7.1.3 Deformation-Energy In mechanics, energy is equal to force times displacement parallel to its direction. Think of a rubber band: If you stretch it, you do work on it. This work gets stored inside the rubber and can be transformed into other kinds of energy. You may for example launch a small toy airplane with it: Then the elastic energy in the rubber gets transformed into kinetic energy. When stretching an elastic material, the force to be applied at the beginning is zero and then grows proportionally to the stiffness and the increase of length of the material. The mechanical work is equal to the area beneath the curve that results from drawing the magnitude of the applied force over its corresponding displacement. In case of linear elastic materials this gives a rectangular triangle with the final displacement forming one leg and the final force being its other leg. This shows that for equal final forces the elastic energy stored in a material decreases with decreasing displacements which corresponds to increasing stiffness.

Fig. 3.7.1.3.1: Simply supported beam under axial and transversal point-loads in two load-cases LC1 and LC2.

{% file src="/files/vEi6qTwJjUD5eMG59xfR" %} Fig. 3.7.1.3.1 shows a simply supported beam with two load-cases. The model gets first passed through a ["Load-Case-Selector component"](/3-in-depth-component-reference/3.6-results/3.7.1-general-results/3.7.1.2-result-selector) which sets the model's default selection to the minimum and maximum result envelope. Thus, when the model enters the "Deformation-Energy"-component via the **"Model"**-input there is no necessity to supply an additional load-case-selection string via the **"LCase"** input-plug. If supplied, a **"LCase"**-input sets the model's new default load-case selection.\ With the input **“Elems|Ids”** one can supply identifiers od elements of those parts for which the deformation energy shall be calculated. An empty list means that all elements are considered. **"nInt"** controls the number of segments along each beam for doing the numerical integration of the elastic energy. It defaults to two but should be set to a larger number for higher accuracy in case of multiple loads along an element. The structure of the data trees returned from the component contains one branch for each element and sub-element. A sub-element is e.g., a face of a shell. In fig. 3.7.1.3.1 the second number from the right of the data-path corresponds to the element index. Since beams do not have sub-elements the last path-number is always zero in the above example. The numbers in each branch belong to the minimum- and maximum results. This corresponds to the selection in the Load-Case-Selector-component. The **"Ax-Energy"**- and **"Be-Energy"**-outputs deliver the axial deformation- and bending energies. Have a look at **"Ax-LCaseInd"** and **"Be-LCaseInd"** in order to see from which load-case within the load-case-combination "LCC" the results in **"Ax-Energy"**- and **"Be-Energy"**- outputs derive. Since LCC = LC1|LC2 ("|" stands for "or") the iondexes are either "0" or "1". {% file src="/files/eRAkViTNoED4VwUtXGAt" %} {% file src="/files/NT8A2s6NAKFCI3s4VmSB" %} # 3.7.1.4 Element Query The **"Element Query"**-component lets one determine the mass, surface area and the volume of a given set of elements (see fig 3.7.3.1). These and the corresponding model need to be supplied as input at the **"Model"**- and **"Elems"**-input plugs. The 'Select Elements'-component (see section [3.1.16](/3-in-depth-component-reference/3.1-model/3.1.16-select-elements)) offers a flexible way of grouping elements for later on querying them.\ In case of shell and membrane elements the surface area is the sum of upper and lower boundary. For beams the outer surface will be returned - the interior of e.g., tubes is not counted. The meshes of the elements are water-tight and come with caps by default. In case this is not desired, set 'with\_caps' to 'False' in the 'karamba.ini'-settings using "Karamba3D/Settings" from the Grasshopper menu. The "Axis" output returns the centerline axis in case of linear elements and the middle surface for surface elements.

Fig 3.7.3.1: Information retrieval regarding elements via the 'Element query'-component

{% file src="/files/csMAR0TaNz6C0zH5eYsL" %} --- [Next Page](/llms-full.txt/1)