PrePoLix User Guide

1 Introduction

PrePoLix is a pre- and post-processor for the finite element solver CalculiX. It runs on Linux and Windows.

With PrePoLix you

• import CAD geometry (STEP, IGES, BREP) and mesh it with Gmsh, or open an existing CalculiX mesh (.inp),
• define the finite element model: materials, sections, constraints, contacts, steps, boundary conditions and loads,
• keep several analyses in one project, as in Ansys Workbench, and solve only what changed,
• run CalculiX and watch its progress,
• view and evaluate the results (.frd, .dat): contour plots, deformed shapes, animations, derived fields, history plots, paths, planes and hot spot stresses.

This guide is a reference. Each chapter describes one part of the program: where to find a function, what every field of its dialog means, and what PrePoLix writes to the CalculiX input file. You do not need to read it from front to back.

1.1 How PrePoLix thinks about a model

You do not need to define node sets, element sets or surfaces. Instead you pick faces, edges, parts or nodes in the 3D view, and the model stores your intent: “a pressure of 2 MPa on these faces”, “these two parts are tied”. Only when the input file is written does PrePoLix turn this intent into CalculiX keywords: it creates the required node sets, element sets and surfaces with generated names and splits a distributed load into what CalculiX needs. Named sets of your own are still possible (Section 4.6).

This has two consequences you will notice:

• When you remesh a part, loads and boundary conditions that were picked on the CAD geometry stay where they are, because they refer to faces and edges of the geometry, not to element numbers.
• The .inp file contains sets you never named. You can inspect it at any time in the keyword editor (Section 5.24) or export it (File → Export CalculiX Input File ...).

The project, including geometry, mesh and model, is saved as a PrePoLix project file (.plx).

1.2 Requirements

• CalculiX (ccx) is needed to run analyses. The Windows installer and the Linux AppImage include CalculiX 2.23 with the PaStiX, SPOOLES and ARPACK solvers, so analyses run right after installation. Another CalculiX, for example one built with Pardiso, can be set under Tools → Settings ... → CalculiX Test CalculiX checks it (Section 3.12).
• Gmsh is needed to import and mesh CAD geometry. The Windows installer and the Linux AppImage include it. Without Gmsh PrePoLix still starts; only geometry import and meshing are unavailable. Its library path can be set under Tools → Settings ... → Gmsh.
• On Linux, PrePoLix needs a Vulkan or OpenGL driver and libxkbcommon, which most desktop installations provide. A Gmsh library installed separately additionally needs libGLU and libXft; the AppImage brings them along.

1.3 Installation

Windows. Run prepolix-<version>-setup.exe from the release page. It installs PrePoLix with Gmsh and CalculiX to C:\Program Files\prepolix, creates a start menu entry, optionally a desktop icon, and can associate .plx project files with PrePoLix. Uninstall it under Apps in the Windows settings. Because programs may not write to C:\Program Files, the CalculiX work directory then defaults to %TEMP%\prepolix.

Linux. Download prepolix-<version>-x86_64.AppImage from the release page, make it executable (chmod +x prepolix-*-x86_64.AppImage) and start it. It includes Gmsh and CalculiX and runs on x86_64 distributions with glibc 2.35 or newer (Ubuntu 22.04, Debian 12, Fedora 36 and later). A tool such as Gear Lever or AppImageLauncher adds a menu entry, associates .plx files and updates the AppImage when a new release is published. The CalculiX work directory defaults to /tmp/prepolix. Alternatively build PrePoLix from source with a current stable Rust toolchain (cargo run --release), see the README of the repository.

1.3.1 Portable version for Windows

Where installing is not possible, for example on a company computer without administrator rights, download prepolix-<version>-windows-portable.zip from the release page instead. Unpack it to any folder you can write to, for example in your documents or on a USB stick, and start prepolix.exe in the folder PrePoLix-<version>. The folder contains the same program, Gmsh, CalculiX and this guide as the installer, but PrePoLix does not register itself with Windows: there is no start menu entry and no file association, and nothing is written to the registry. Settings and the material library are kept in the folder Settings next to prepolix.exe, the CalculiX work directory defaults to the folder Temp there, and the settings window shows Portable mode at its bottom. The file portable.txt switches this on; without it the settings go to %APPDATA%\prepolix\data as with the installer. To update, unpack the new version (the update window links to its ZIP file, see Section 1.4) and copy the Settings folder over; to remove PrePoLix, delete the folder.

1.4 Updates

PrePoLix asks GitHub for the latest release when it starts. If a newer version exists, a green symbol with a download arrow appears at the right of the menu bar, next to the version number. Nothing else happens: ignore it if you do not want to update. A click on the symbol, or Help → Check for Updates ..., opens the update window with the release notes (What’s Changed, one line per change with a link to it on GitHub):

• Update Now (Windows installer only) downloads the installer of the new version, checks its size and checksum and starts it. Windows asks for administrator rights, PrePoLix closes, the installer only shows its progress and then starts PrePoLix again; the shortcuts and the .plx association stay as you installed them. Save your project before: the project that was open is reopened when it was saved as a .plx file.
• Download ZIP (portable version only, Section 1.3.1) downloads the new portable ZIP file in the web browser. Unpack it yourself and copy the Settings folder over.
• Open Release Page opens the release on GitHub. A PrePoLix built from source offers only this.
• Close closes the window; the symbol stays until PrePoLix is closed.

The Linux AppImage does not check at startup, since an AppImage manager such as Gear Lever or AppImageLauncher updates it; Help → Check for Updates ... still shows what is new. The check at startup runs in the background and stays silent when there is nothing new or no internet connection. It can be turned off under Tools → Settings ... → Updates (Section 3.12). A proxy is taken from the HTTPS_PROXY variable or, on Windows, from a proxy server entered in the Internet Options (automatic configuration scripts are not read). The connection is checked with the certificates of the system, so a company proxy that inspects HTTPS works too.

1.5 Starting PrePoLix

Start PrePoLix from the start menu, by double-clicking a .plx file (Windows, if associated), by double-clicking prepolix.exe in the portable folder (Section 1.3.1), or from a terminal. Files given on the command line are opened in order, so a model and its results can be opened together:

prepolix bracket.plx bracket.frd

Several CAD files given together are combined into one geometry. Without command line arguments, PrePoLix reopens the project that was open when it was last closed, provided it was saved as a .plx file and still exists.

1.6 This guide offline

The Windows installer, the portable ZIP and the Linux AppImage contain this guide as a web page. Help → User Guide opens it in the default web browser; no internet connection is needed. On Linux PrePoLix hands the page to the browser through a small web server on your computer (address http://127.0.0.1:<port>/), because browsers installed as Snap or Flatpak cannot read the files of a mounted AppImage. A PrePoLix built from source without the guide opens the online guide at https://kwentin-ui.github.io/PrePoLix/ instead. The guide is also available as PDF on the release page on GitHub.

2 A First Analysis

This chapter walks through a complete static analysis of a plate with a hole that is fixed at one end and pulled at the other. Each step links to the chapter with the details.

1. Create the analysis. In the project window, Project → New Analysis ... asks for the model space and the unit system; keep 3D and mm, ton, s, °C (Section 3.1.1). A block appears in the project schematic; double-click it to open the analysis in its own window (Section 3.1).
2. Import the geometry. Geometry → Import ... reads the STEP file of the plate. It appears as part SOLID-1 on the Geometry tab (Section 4.1).
3. Mesh it. Mesh → Default Mesh Parameters ... sets the element size, Mesh All Parts creates quadratic tetrahedra. PrePoLix switches to the FE Model tab (Section 4.2).
4. Material and section. Model → Create Material ... with density, Young’s modulus 210000 MPa and Poisson’s ratio 0.3, or copy steel from the material library (Section 5.2). Then Model → Create Section ... assigns it to the part (Section 5.3).
5. Step. Model → Create Step ... with type Static (Section 5.10).
6. Support. Model → Create Boundary Condition ..., type Displacement/Rotation, which holds all components at zero; click the end face of the plate in the 3D view (Section 5.17, Section 3.10).
7. Load. Model → Create Load ..., type Force with F1 = 20000 N on the opposite end face (Section 5.18).
8. Solve. Solve in the toolbar or F5. The Analysis tab below the 3D view shows the output of CalculiX (Section 6.1.1). If the tree shows warning signs, click them first (Section 6.4).
9. Look at the results. The results open when the run is done; otherwise Results in the Analysis tab opens them. Select STRESS > MISES in the tree to see the von Mises stress around the hole (Section 7).
10. Save the project. File → Save Project writes a .plx file with all analyses of the project: geometry, mesh, model and results. The project schematic now shows the analysis as up to date; change a load, and its solution turns out of date until you solve again.

3 The User Interface

3.1 Projects and analyses

A PrePoLix project (.plx) holds several analyses, like a project of Ansys Workbench. PrePoLix starts with the project window. It shows each analysis as a block in the project schematic; each analysis opens in a window of its own (Section 3.5). Several analysis windows can be open at the same time, next to the project window.

New analyses are empty and independent of the others. To start from an existing one, use Duplicate: the copy takes over geometry, mesh, model and results. To share parts of an analysis, link them in the schematic (Section 3.2): a linked item changes in one place and is used in both.

3.1.1 Creating an analysis

Project → New Analysis ..., a double-click or right-click on the background of the schematic or Analysis in the block search (Section 3.1.3.1) open Model Properties for the new analysis (Section 5.1). Choose its model space (3D, plane stress, plane strain or axisymmetric) and its unit system there.

3.1.2 The blocks of the schematic

An icon in the top left corner of each block shows its model space: a cube for 3D, a thin plate for plane stress, a long prism for plane strain and a profile turned about its axis for axisymmetric models. Hover over it for the name. Below the header, each block lists the cells of its analysis from top to bottom, and below them the steps of the analysis as they are defined at the moment:

The symbol on the right of a cell shows its state; its tooltip says what it means:

PrePoLix keeps a fingerprint of the inputs each cell was made from, and only cells whose inputs changed are out of date. New meshing settings of one part make only the mesh of that part out of date, and with it the solution. A new load makes the solution out of date but not the mesh. Changes that CalculiX does not see, such as result paths or planes, leave the solution up to date. Within the solution, PrePoLix also remembers which steps are unchanged, so that CalculiX can start after them (Section 6.2).

A mesh taken from a mesh block is out of date as soon as the block’s parameters change, also in analyses that take it through another analysis: the analysis still holds the block’s old mesh. Solve in the analysis window then has the project window make the block’s mesh anew and take it over before CalculiX runs, so the results always belong to the block’s current mesh.

The same holds for results and states taken from another analysis: when the source analysis is out of date, so is the analysis that takes its results or continues from its state, and Solve in its window solves the source again first instead of taking its old results.

The pins on both sides of a row take and give links. Blue wires are references (geometry, mesh, setup items: the target has the same as the source), orange wires carry results into the inputs of steps and green wires carry the state after a step (Section 3.2). A round pin on the left takes one wire, a tall one (the categories of the setup) takes any number, and the green square takes the state of another analysis (Section 3.2.1).

3.1.3 Working with the schematic

• Double-click a block to open its analysis in its own window. If the window is open already, it comes to the front; while the analysis is solved in the background, it opens once the solve is done. The header of an open analysis says (open). Double-clicking a row opens the window in the matching workspace: Geometry and Mesh in the Geometry workspace, Setup and its categories in the FE Model workspace, the rows of the steps likewise with the step selected in the tree, and Results in the Results workspace.
• Drag a block by its header to move it, drag the background to pan, and scroll to zoom. Project → Show All Blocks (Home) fits all blocks into the view.
• Drag from a pin on the right of a row to a pin on the left of a row of another block to link them (Section 3.2). Right-click a pin to remove its links.
• Right-click a block for its context menu.
• Double-click or right-click the background to search the blocks to add there (Section 3.1.3.1, Section 3.3).

3.1.3.1 Adding blocks by search

Like the add menu of Blender, a double-click or right-click into empty space of the schematic shows every kind of block PrePoLix can add, grouped as in the Project menu. Just start typing: the search field has the focus and finds blocks by fuzzy matching, so letters in order are enough (rct finds Rectangle). It also knows other words for a block, such as hexahedra for Box or library for Materials. Search results show their group on the right.

Enter adds the highlighted block, the best match while you type, where you clicked; Up and Down move the highlight, a click adds any block, and Esc or a click elsewhere closes the search. Analysis asks for the model properties first (Section 3.1.1).

3.1.3.2 Frames, notes and compact blocks

Large schematics stay readable with three things borrowed from Blender’s node editor:

• A frame is a named, tinted rectangle around a group of blocks, such as “Load cases” or “Thermal chain”. Select the blocks and press Ctrl+J, or choose Frame Blocks in the context menu of a block: the frame is drawn around them and its label is ready to be typed. The frame follows its blocks and grows when one moves out; drag the frame itself to move it with all its blocks. A block dragged and dropped onto a frame joins it; Alt+P or Remove from Frame takes it out again. Double-click the label to rename the frame, and right-click the frame for its Color or to Remove Frame, which leaves its blocks where they are. A double-click into the frame below its label searches the blocks to add, as on the empty background.
• A note is a block with a text and no pins (Project → Add Note, or “note” in the block search). Click its text to write; it is kept once you click elsewhere, and Ctrl+Z undoes the whole edit.
• A compact block shows only its header and the rows a wire ends at, so the wires stay but the rows in between are gone. Click the triangle at the left of its header or press H a double-click on the header of a compact block opens it again.

Frames, notes and compact blocks are saved with the project, and undo and redo cover them.

3.1.3.3 Keys of the schematic

While the mouse pointer is over the schematic and no text field is being edited, these keys work as in Blender. They act on the selected blocks, or on the block under the pointer when none is selected. Select blocks with Shift and a click, or drag a rectangle with Shift held; Ctrl and a click removes a block from the selection. The Edit menu lists them for the selected blocks.

3.1.4 Menus and toolbar of the project window

The toolbar holds New Project, Open, Save, Update Project, the button that stops the update and kills the running CalculiX jobs, and Solution Monitor.

Closing the project window closes PrePoLix with all analysis windows. Closing an analysis window (or File → Close Analysis in it) keeps the analysis in the project, with all changes; save the project to write them to the file. An analysis window that is meshing or solving cannot be closed.

3.1.5 Update Project

Project → Update Project solves every analysis whose mesh or solution is out of date or missing, like Update Project in Ansys Workbench. Analyses without a mesh, geometry or step are skipped and listed in the output pane. Mesh blocks whose mesh is out of date make it anew first (Section 3.3.2).

• Analyses are solved in the order of their links: an analysis that takes results or a state from another one waits until that one is solved. An analysis upstream is solved only when it is not up to date itself; when it is solved again, the analyses that use its results are solved after it.
• Independent analyses are solved at the same time, up to Parallel analyses of the CalculiX settings (default 2), each with the number of threads set there (Section 3.12). Two analyses on one computer are worth it when CalculiX spends its time in the equation solver on few threads; set Threads times Parallel analyses to at most the number of processor cores.
• An analysis whose window is closed is solved in the background, without opening its window: PrePoLix meshes its geometry if the mesh is missing or out of date, writes the input file, runs CalculiX and keeps the results in the project, as Solve in the window does. The cells of its block show the progress. An analysis whose window is open is solved in its window, which shows the new results when it is done.
• If CalculiX fails, only the analyses that depend on the failed one are skipped, independent ones go on. The output pane sums up with Project updated or Update finished with errors the solution monitor tells what went wrong.

3.1.5.1 Updating one block

When the schematic holds independent branches, one of them can be brought up to date without the others: click the amber circular arrow of a block (or the blue question mark of a Solution or Results row that was never solved). PrePoLix updates that block and every block it takes data from, directly or through others, the way Update Project does: mesh blocks make their meshes anew, analyses are solved in the order of their links, Campbell blocks sweep and mesh export blocks write their files. Blocks that are neither the clicked one nor upstream of it stay as they are. Clicking the arrow of a parameter study solves its design points (Section 3.4). The symbols cannot be clicked while an update is under way. The output pane ends with <block> updated.

3.1.6 Solution monitor

The project window has its own monitor, like the monitor of an analysis window (Section 6.1.1) but for all analyses of the project. It is the Analyses tab of the output pane below the schematic and comes to the front when an update or Solve on a block starts; Project → Solution Monitor or the monitor button in the toolbar switches between it and the Output tab.

The list shows each analysis being solved, queued or done, with its status (preparing, meshing, running, keeping results, solved, failed or stopped), its running time and the current step and increment of CalculiX. Analyses solved in their open window are marked (window). Right of the list is the output of the analysis picked in it: the lines of PrePoLix (meshing, model checks, restart, keeping the results) around those of CalculiX, which Filter narrows down to the lines containing a text.

3.2 Linking analyses

Analyses of a project share data through links in the project schematic: drag from a pin on the right of a row to the pin on the left of a row of another analysis. Links are of two kinds:

• A reference makes a row of the target the same as the row of the same name in the source: the mesh is the mesh, the material is the material. It goes from like to like, and the target cannot change what it takes.
• An operation hands on what a step of the source produced: its results go into a calculation of the target. It starts at a row below Results, which only gives, and ends where the target uses it: an input of one of its steps under Setup > Steps, its initial conditions, or its State.

The colour of a wire tells its kind, the row tells where it acts:

A block thus reads from top to bottom: where it starts (State), what it is (the blue rows of the definition), what it uses (the orange inputs of its steps in the setup) and what it produces (Results, with pins on the right only).

Each pin has a type: geometry, mesh, setup, results, a number, an input of a parameter study, or a whole analysis. Pins of model data also have the model space of their block (3D, 2D plane stress, 2D plane strain or axisymmetric); the tooltip of a row names both. While a wire is dragged, the pins it can end at get a ring and all others fade. Hovering over a faded pin says why the link cannot be made there.

The output pane of the project window says what each link does (“Axial-load takes Mesh from Cantilever”) and why a link cannot be made:

• the pins are of different types, for example a mesh dropped on the setup;
• the two blocks have different model spaces (“linked blocks need the same model space”). A different unit system is fine, since every block keeps its values in SI units. Numbers have no model space;
• the link would go back to an analysis that already comes before the source, and form a cycle;
• the item does not fit the slot, for example a material dropped on the sections, or results dropped on a step that cannot use them;
• the target continues another analysis and takes its whole model from there (Section 3.2.3).

Right-click a pin to remove its links, or use Unlink in the analysis window. The target keeps a copy of what it took, which it can edit from then on.

3.2.1 Linking data

A data link makes the target use what the source has, live: a change in the source reaches the target at once. Whole cells can be linked (Geometry, Mesh), a whole category of the setup (open Setup with the arrow in front of it: Materials, Sections, Constraints and so on) or a single item of a category (open the category: one material, one contact pair, one step). A linked category also passes on items added to it later.

A linked Geometry takes the shapes only: the parts are read-only, but the mesh setup on the Geometry tab (Default Mesh Parameters ..., the Mesh Setup items) stays the target’s own, and the target meshes the geometry itself. Several analyses can so mesh the same geometry, from another analysis or from a file block (Section 3.3.4), each its own way. A target without geometry starts from the mesh setup of the source. A linked Mesh takes the mesh with the setup it was made with; both are read-only then.

The FE Model tree of the target shows only what is set up in that analysis: linked items are hidden by default, so that the tree lists the inputs that matter for it. Categories stay in the tree, also when everything in them is linked, so that items of the analysis itself can be added; a linked mesh or step leaves just its category row with the link sign. Tick Show linked items above the tree, in the View menu or in the settings (Graphics) to list them; the choice is stored in the settings. Hidden items are still part of the model: dialogs offer the linked sets, materials and so on as before, and the solver gets them.

In the window of the target, linked items are read-only. When shown, a link sign marks them in the tree, and their tooltip names the analysis they come from and says that they change there. The commands that would change them are refused with the same hint; a double-click opens a small dialog instead of the item’s own:

A linked mesh follows the source: when the source is meshed again, the target’s solution is out of date.

3.2.1.1 Pins: single values and collections

The pins on the left of the rows have two shapes, like the sockets of a node editor:

A linked category is a bundle of links of its items. Open the category in both blocks to see a wire per item. Items the source gets later come through as well. To leave one item out, right-click its pin in the target, or double-click it in the tree of the target’s window and choose Unlink: the target keeps its copy and can edit it, and the pin of the category turns lighter, with a dot. Its tooltip counts the items that come through (“2 of 3 items from Static”). Drag the item’s own wire again to take it back.

When two links bring an item of the same name, the one made later wins. An own item of the target with the name of a linked one is covered by it, and its copy of the linked item stays once that item is left out or the link is removed. Linked steps come before the target’s own steps, in the order of the links. A link of the whole Setup is a single value: it takes all categories of the source in place of the target’s.

3.2.2 Taking results of a step

The rows below Results of a block are its steps: what each step produces. They have a pin on the right only. What a step of another analysis uses is an input of that step: open Setup > Steps of the target and then the step with the arrow in front of it, and its inputs are listed below it, each with an orange pin:

Results dropped on the row of the step itself, while it is closed, go to the input that fits: eigenmodes to Eigenmodes, temperatures to Temperatures, anything else to Global results. Once the step is opened, the wire is seen to end at that input. Results dropped on an input they do not fit are refused, and the output pane says why (“Heat is no frequency step”).

The temperatures of a thermal step can also be dropped on Initial Conditions under Setup: the analysis then starts at them (*INITIAL CONDITIONS, TYPE=TEMPERATURE on every node).

• Temperatures and eigenmodes are transferred node by node, so both analyses need the same mesh: link the mesh, or continue from a state (Section 3.2.3). Otherwise the output pane says why nothing is taken. A submodel has its own, finer mesh.
• A frequency step without Storage cannot give its eigenmodes; the link is refused with a hint to turn it on.
• A step that works on the eigenmodes of another analysis needs no frequency step before it. Its boundary conditions are written before the first step, because CalculiX takes no new ones in a modal or steady state dynamics step.
• Defined temperatures need initial temperatures: a link to Initial Conditions provides them, and the model check counts it (Section 6.4).
• When the source has no results yet, Solve and Update Project solve it first. When the source is solved again, the analyses that use its results are solved after it. A source whose results are out of date is not solved again on its own; its block shows the circular arrow, and Update Project brings both up to date.
• Before the run, PrePoLix copies the result files it needs next to the input file, because CalculiX reads them from there.
• Unlink takes back what the link set: the defined field, the eigenmodes or the initial temperatures.

3.2.3 Continuing an analysis after a step

CalculiX solves the steps of a run one after the other, each starting from the state the step before it left. A state link lets an analysis take that state from a step of another analysis and continue with steps of its own, as if they stood behind that step in one input file. Where Ansys Workbench links a static analysis to a pre-stressed modal analysis, PrePoLix links any step to any following steps: a load history that branches after a pre-load into several load cases, a frequency step after a static step, or a modal dynamics step after the frequency step of another analysis.

Drop the results of a step on the State row at the top of another block. The target then continues the source:

• It takes the geometry, the mesh, the whole setup and the steps up to and including that step from the source. All of it is read-only in its window and marked with the link sign like other linked items; the steps it took are listed before its own. New steps are added as usual and are its own; as always, a new step starts with the boundary conditions and loads of the step before it.
• Its State row reads After <step> of <source>. In its block, Results lists only the steps of its own. The steps it took over are folded into one row right below Results, 2 steps from <source>, in the link colour and with the link sign; it has no pins, and a click on its arrow lists the steps, greyed, as a reminder of what the state contains. Their results are in the block of the source. Every step shows the symbol of its type, like in the tree.
• A state link replaces every other link of the target: while it continues another analysis, nothing else can be linked to it.
• Unlink on the State pin, or on a taken item in the window, makes the analysis independent again. It keeps copies of the model and of the steps it took, so it still solves the same problem, now on its own.

Continue from here. The quickest way to a continuation: drag the pin of a step to empty space and pick Continue from here from the menu that opens. A new analysis named <source> continued appears at that place, already continuing from that step, with the model space and unit system of the source. Open it and add its steps.

Solving. CalculiX solves only the own steps of the target: the run reads the state CalculiX wrote after the step in the source’s run (*RESTART, READ) and continues. The monitor says so (“Restart after step 2 of 3: the steps up to it are unchanged; CalculiX reads their state from Cantilever and solves the rest”, or “from the earlier run” once the target has run before). The results of the target contain all steps, those of the source and its own, as if solved in one go.

• When the source has no results yet, Solve and Update Project solve it first.
• CalculiX takes no new sets after reading a state. PrePoLix therefore writes the sets the target’s steps need into the input file of the source as well. If they are missing because the source was solved before the steps were added, the target is solved in full instead, with the source’s steps repeated in its own run; the results are the same, it only takes longer. The monitor says Full run and why.
• CalculiX writes a state only after steps over time (static, dynamic, heat transfer, coupled and uncoupled temperature-displacement, visco), not after a frequency, buckling or perturbation step. A target that continues after such a step is solved in full as well.
• The state files are kept in the work directory, not in the project file (Section 6.2). On a computer without them the target is solved in full.

3.2.4 Split and merge

The context menu of a block turns steps into continuations and back, without changing what is solved:

A split is useful when one of several load cases after a common pre-load should be computed without the others, or to show the branches of a load history in the schematic; a merge brings the steps back into one block when the branch is no longer needed.

3.3 Source blocks

Besides analyses, the project schematic holds source blocks: blocks that only give data to analyses through links. They have no steps and are not solved, and Update Project passes them by; the mesh export block at the end of this section takes data instead of giving it. Add one from Project or by double-clicking or right-clicking the background of the schematic; its header has its own tint, so that it stands apart from the analyses. Its context menu has Edit ..., Rename ..., Duplicate and Delete ... a double-click opens its editor in the project window. Deleting a source block removes its links; the analyses keep copies of what they took.

3.3.1 Materials

A materials block holds materials in the project file, so that several analyses use the same definition: change it once in the block and every analysis that links it follows. Unlike the material library (Section 5.2), which belongs to you and every project you open, the block belongs to the project and travels with it.

Its rows are Materials, which gives all of its materials, and below it one row per material; the arrow in front of Materials hides and shows them. Drag a row to the Setup row of an analysis, or to its Materials row or a material once Setup is open, as with links between analyses (Section 3.2.1). A link of all materials also passes on materials added to the block later; while the block shows its materials, it is drawn as a wire per material. In the analysis window the linked materials carry the link sign and are read-only; Open Materials in their dialog opens the block’s editor.

OK keeps the changes, and the analyses that link the block take them at once; Cancel drops them.

3.3.2 Box and Rectangle meshes

A mesh block makes a structured mesh from a few numbers, without geometry and without Gmsh: Project → Add Mesh → Box meshes a box with hexahedra for 3D analyses, Project → Add Mesh → Rectangle a rectangle in the X-Y plane with quadrilaterals for 2D analyses. Link its Mesh row to the Mesh row of analyses of the same model space; several analyses can share one mesh block.

Its parameters are rows of the block under Mesh, like the inputs of a Blender node: X, Y, Z of the corner it starts at and the edge lengths Lx, Ly, Lz in the block’s units, the numbers of elements nx, ny, nz as whole numbers and the Element type. Click a field to type a value, or drag it; a rectangle has no Z rows. Once a parameter changes, the Mesh row shows the mesh out of date. The violet pins on the left of the numbers take a value from a Parameters block (Section 3.3.5). To make the mesh finer or coarser as a whole, put a Refine Mesh block after it (Section 3.3.3).

Its sides are node sets and surfaces at once, named after the axis and the side they lie on: X- at the smallest X, X+ at the largest, then Y-, Y+ and, for a box, Z- and Z+. Boundary conditions and loads pick them under Node set or Surface without selecting anything. The elements form the part BOX or RECTANGLE, which a section takes.

The sides, edges and corners are also faces, edges and points of geometry. A selection in the 3D view with Faces, edges and points picks a whole side of the box, and it stays on that side when the mesh is made anew with other divisions, other lengths or another refinement, as on imported geometry. A selection of single nodes or element faces holds only for the mesh it was made on.

A double-click on the block’s name opens all its parameters in a dialog, with what the rows leave out: the model space of a rectangle and the units the lengths are shown in.

The line below the fields counts the elements and names the sides. OK keeps the parameters, and the Mesh row of the block shows that its mesh is out of date. Update Project makes it anew before it solves (Section 3.1.5), and so does Generate Mesh in the block’s context menu; the analyses that link it take the new mesh, and their solutions are out of date.

3.3.3 Refine Mesh

A Refine Mesh block makes the mesh linked to it again, finer or coarser by a factor, and gives the new mesh on. Add it with Project → Add Mesh → Refine Mesh, drag the Mesh of a mesh block or of an analysis with imported geometry to the pin on the left of its Mesh row, and drag the pin on the right of that row to the Mesh row of the analyses that are to use the refined mesh. The mesh it refines stays as it is.

What the factor does depends on where the mesh comes from:

• From a mesh block (Box, Rectangle): the numbers of elements along every edge are multiplied by the factor and rounded, so a box of 10 x 2 x 2 elements refined by 1.5 has 15 x 3 x 3. The block makes this mesh itself: once the factor or the mesh block changes, its Mesh row is out of date and Update Project or Generate Mesh in its context menu makes it again.
• From an analysis with imported geometry: it gives the geometry with its mesh setup on, every element size divided by the factor (the max. and min. element size of the meshing parameters, those of Meshing Parameters items and the local mesh sizes). The analysis that takes it meshes the geometry with these sizes when it is solved; the sizes as set in the mesh setup stay. Its mesh can therefore not go to a Mesh Export block: export the mesh of the analysis that meshed it.

Refine Mesh blocks can follow each other; their factors multiply. A mesh read from an input file has no parameters or geometry to mesh it again with, and the link is refused.

3.3.4 File

A file block reads a file from outside the project and gives what it holds to analyses: the results of a CalculiX run (.frd), the mesh of a CalculiX input file (.inp) or geometry (STEP, IGES, BREP, STL). Add it with Project → Add File ... or from the picker; a dialog asks for the file at once. Its rows depend on the file:

• results: Results with a row per step of the file, whose pins link like the steps of an analysis, for example to the Global results row of a submodel (Section 6.6);
• an input file: Mesh, to link to the Mesh row of analyses;
• geometry: Geometry, to link to the Geometry row of analyses.

The File row holds the path: type it, or double-click the block or use Choose File ... in its context menu. A relative path starts at the folder of the project file. The block reads the file in the background and reads it again whenever it changes on disk; Read Again in the context menu reads it at once. The symbol of the first row shows the state: a green tick once the file is read, a dash while no file is chosen or it is missing, and an error when it could not be read, with the reason in the tooltip and the output pane. A linked analysis is out of date when the file changes, and Update Project solves it again with the new data. The file is never written to; deleting the block leaves it as it is.

3.3.5 Parameters

A Parameters block holds named numbers that other blocks take through value links, so that one number drives several places: the length of two meshes, or a size that is changed in one spot. Add it with Project → Add Parameters → Parameters it starts with one length.

Each parameter is a row with its value, typed or dragged in place, and a violet pin on either side. Drag the pin on the right to the pin on the left of a number of a mesh block (X to nz), to the Factor of a Refine Mesh block or to an exposed parameter of an analysis or a Materials block (Section 3.3.7). The number then takes the value of the parameter: it is shown in violet and read-only, and when the parameter changes the blocks after it are out of date, so Update Project meshes and solves again. The pin on the left takes the value of another parameter. A value link joins like with like: a length goes to a length, a force to a force, a count to a number of elements, a factor to Factor otherwise the output pane says why it was refused. Right-click the pin to remove the link; the number keeps its last value.

A double-click on the block opens its editor:

3.3.6 Math and Switch

A Math block computes a number from others, like the Math node of Blender: a height that is twice a width, a thickness that never drops below a minimum. A Switch block picks one of several numbers by an index, for variants such as three sheet thicknesses. Add them with Project → Add Parameters → Math and Project → Add Parameters → Switch, or search them with Shift+A.

Their inputs are rows with a violet pin on the left: type a number, or drag a value pin to it, from a Parameters block, from another Math or Switch block or from the Inputs of a parameter study (Section 3.4). The Result row at the bottom shows the number the block gives; drag its pin on the right to any number of the same kind, to another Math or Switch block or to the Outputs of a study. Blocks that take the result are out of date when it changes, as with a parameter.

A value link joins like with like here too: once a block has a kind, it takes only numbers of that kind, and the output pane says why a link was refused. Changing the operation removes links to inputs the block no longer has.

3.3.7 Exposed parameters

Any number of an analysis that a study or a Parameters block should set, such as a force, a thickness or the Young’s modulus of a material, is first exposed. In the dialog of the item, a small P button follows each number that can be exposed; click it and close the dialog with OK. The number then is a row of the analysis’ block in the project window, under Exposed Parameters, with the value it has and a violet pin on the left. It also appears in the FE Model tree under Exposed Parameters, where a double-click opens the item.

The row is named after the item and the number, such as Force-1 Y right-click it to rename it or to remove the parameter, which leaves the number as it is. Type a value in the row, or drag a value pin of a Parameters block to its pin: the number then follows the parameter, and the field in the dialog is read-only while the link is there. Renaming the item keeps the parameter. The numbers that can be exposed are those of loads, boundary conditions, defined fields and initial conditions, of materials and sections, the time period and first increment of steps and the number of modes of a frequency step. A Materials block (Section 3.3.1) exposes the numbers of its own materials in the same way.

Exposing a number does not change the analysis: only a new value makes it out of date.

3.3.8 Measure

A Measure block computes one key figure from the results of a step: the largest von Mises stress, the displacement of a node, a total force or an eigenfrequency. It is the number a parameter study reads, and a quick way to see the figure that matters without opening the results. Add it with Project → Add Measure it starts with the largest von Mises stress.

Drag the pin of a step under Results of an analysis to the Results row of the block, with an orange wire like every link of results. A Measure block measures one step; another wire to it takes the place of the first. The block shows what it measures and, in its last row, the value in its units with the state of the value:

• a green tick when it was computed from the results as they are and those are up to date;
• the orange arrows when the results are out of date, after a change of the analysis or of a block it links to; Update Project solves the analysis again and the value follows;
• a dash while there are no results, or when the results lack what it measures. The output pane then says why, for example “step 1 has no field STRESS in the results”.

The value is computed anew in the background whenever the results or its definition change, and the output pane prints it (“Max stress: Maximum of STRESS MISES = 8.6 MPa”). The project file keeps the value, so a reopened project shows it at once. The pin on the right of the value row gives it to a parameter study (Section 3.4).

A double-click on the block opens its editor:

3.3.9 Mesh Export

A mesh export block is the opposite of a source: it takes a mesh and writes it to a file, as a CalculiX input file (.inp) with the nodes, the elements, and the node sets and surfaces of the mesh. Add it with Project → Add Mesh Export or from the picker under Export, and drag the Mesh row of a mesh block or an analysis to its Mesh row. Several export blocks may take the same mesh.

The block has two rows. Mesh is the input; its symbol shows whether the file is up to date. File is the file to write: type its path, or double-click the block’s name to pick it in a dialog. A relative path starts at the folder of the project file, so a project moved together with its export folder keeps working; while the project is unsaved it starts at the folder the program was started in.

Update Project writes the file once everything before the block is done: the mesh of a mesh block is made first, an analysis is solved first, and the file is written from the mesh as it is then. It writes only when something changed, that is when the mesh or the path is new or the file is gone, so an update of a project that did not change leaves the file alone. If an analysis before the block fails, the block does not write. Export Now in the block’s context menu writes the file at once, whatever the state.

The file holds the mesh only, not the loads or steps of an analysis that takes the same mesh, so it reads back as a mesh when an analysis imports it. A path the program cannot write shows as an error in the Mesh row’s tooltip and in the output window.

3.4 Parameter studies

A Parameter Study block solves the project for several sets of numbers and lists what came out, like the parameter set of Ansys Workbench. Its table has a column for each number it varies (its inputs, P1, P2 …) and for each number it reads back (its outputs, O1, O2 …); each row is a design point, a set of input values with the outputs they gave.

Add one with Project → Add Parameter Study, then link its columns:

1. Drag the pin of its Inputs row to a number the study varies: a parameter exposed by an analysis (Section 3.3.7), a number of a mesh block, the Factor of a Refine Mesh block (Section 3.3.3) or an input of a Math or Switch block (Section 3.3.6). The link makes an input column named after that number, of its kind (a force, a length …), with its value as it is now. The wire is violet and dashed and runs below the blocks, as it leads back to the blocks before the study. One column can give its value to several numbers: drag the pin of its row to each. Quicker for an exposed parameter: right-click its row and pick the study under Add to Study.
2. Drag the value pin of a Measure block (Section 3.3.8) to its Outputs row. The link makes an output column named after the measure. The Result of a Math or Switch block is an output in the same way, named after the block.

The first column makes the first design point, DP 0, which is the current one: the blocks stand at its inputs, and its outputs are those the project shows. Removing a link leaves the column; Remove in the editor removes a column and its links.

A double-click on the block (or Edit in its context menu) opens its editor, with the columns and the table of the design points:

Run, the circular arrow of the block or Update Project solve the points that are not up to date. Each point is a whole update of the blocks between the study’s inputs and its outputs: meshes are made anew, the analyses are solved, the measures are computed. The current point is solved last, so that the analyses end with its results; the results of the other points are not kept, only their outputs. The output pane prints each point; Stop of the project window ends the run after the running solves stopped. A point stays up to date as long as the blocks it runs are what it was solved with: change a load or a material of the analysis and every point is out of date, and the next Update Project solves them again. Set as Current gives the inputs of a point to the blocks; as the point is up to date, Update Project then solves the analyses for its results without running the study.

3.4.1 Filling and importing points

Fill ... makes points from values per input. Each input takes the value of the current point (Current), a List of values separated by ;, such as 1; 1.5; 2, or a Range of evenly spaced values from one value to another. All combinations makes a point for every combination of the values of the inputs; One at a time varies each input by itself, the others at the current point. A point with the inputs of a point already in the table is not added again. Replace the points removes all points but the current one first. The dialog says how many points it adds before Add Points.

Import ... adds the points of a table pasted from a spreadsheet, or read with Open File ... from a CSV file. Cells are separated by tabs, ; or ,. A first row of names takes the columns named after inputs, with or without the unit in brackets, as Copy Table and Export CSV ... write them; an input without a column takes the value of the current point. Without such a row, the columns are the inputs in order. Values are in the units shown; a value with its own unit, such as 7 kN, is converted.

3.4.2 Plot

The Plot tab draws the outputs over an input, another output or the elements (x). The boxes O1, O2 … choose the outputs shown, and Curve per makes a curve for each value of another input, for a study over two inputs. Points without the values are left out. Drag to move the view, scroll to zoom, double-click to fit.

3.4.3 Mesh convergence

A study checks whether the results depend on the mesh: put a Refine Mesh block between the mesh and the analyses that solve on it, link the Inputs row to its Factor and a Measure block of the results to the Outputs row, and add points with factors such as 1, 1.5, 2 and 3. The Elements column shows how many elements each one solved; in the plot, the measure over Elements is the convergence curve. When the output hardly changes from one point to the next, the mesh is fine enough. When it grows with every refinement, it is a singularity: a stress at a sharp corner or under a point load grows without end as the mesh gets finer. Measure a displacement there, or a region away from it.

3.5 Analysis window

Each analysis of the project opens in a window of its own. Its title shows the name of the analysis and of the project. The layout is fixed. Only the separators between the panes can be moved.

From top to bottom the window contains:

Menu bar

File, Edit, View, Geometry, Mesh, Model, Interaction, Analysis, Results, Tools, Help. Edit holds Undo and Redo (Section 3.8). Help → User Guide opens this guide in the web browser (Section 1.6).

Toolbar

two rows. The first row holds the file, view and display buttons, the second row the result controls (Section 7.3). The result row is always there but greyed out outside the Results tab, so the 3D view does not jump when you switch tabs.

Model tree

on the left, with the three tabs Geometry, FE Model and Results (Section 3.6).

3D view

in the centre (Section 3.9).

Output pane

below the 3D view, with two tabs. Output collects messages: what was loaded or saved, warnings, keywords of an imported .inp that were skipped (“Not yet evaluated: …”), unit conversions and the output of the query tool. Analysis is the monitor of CalculiX (Section 6.1.1); it comes to the front when a run starts.

Status bar

on the left what is loaded (“bracket.plx: 12345 nodes, 6789 elements, 3 parts”) or what is running (“Meshing …”), on the right the unit system and the model space of the analysis.

3.5.1 Toolbar, first row

Buttons that cannot be used at the moment are greyed out, for example Stop while nothing runs.

3.6 Model tree

The tree on the left has three tabs:

Geometry

imported CAD parts and the mesh setup (Section 4).

FE Model

mesh parts, materials, sections, constraints, contacts and steps.

Results

the opened result files with their fields, history outputs, paths, planes and hot spots (Section 7).

Geometry and FE Model share one camera, Results has its own. A model that has no mesh yet opens on the Geometry tab, opening a result file switches to Results.

3.6.1 Working with tree items

• Double-click an item to open its dialog. Double-clicking a container (for example Materials) creates a new item in it.
• Right-click an item for its context menu (see below).
• Del deletes the selected item after asking “Delete the selected item?”; Ctrl+Z brings it back (Section 3.8).
• Space activates or deactivates the selected item while the mouse is over the tree.
• Selecting an item highlights its region in the 3D view. Master and slave regions of contacts and ties get different colours.
• Parts can be selected together: Ctrl+click toggles a part, Shift+click selects a range.

3.6.2 Context menus

Containers

Create ..., Expand All, Collapse All. Some containers have more entries: Material Library ... on Materials, Default Mesh Parameters ... and Mesh All Parts on Mesh Setup, Create Tie ... and Create Node Tie ... on Contact Pairs, Search Contact Pairs ... on Constraints and Contact Pairs. A container that cannot take items explains why in a tooltip, for example “A frequency step has no loads.”

Items

Edit ..., Activate/Deactivate, Swap Master/Slave (ties, spring connections and contact pairs), Delete. Items that come from another analysis through a link are shown in blue with the name of that analysis; their commands are greyed out, and a double-click offers to open that analysis or to unlink the item (Section 3.2.1).

Parts

Properties ..., Hide/Show, Delete on the Geometry tab also Create Mesh.

3.6.3 Deactivating items

Steps, boundary conditions, loads, constraints, contact pairs, node ties and initial conditions can be deactivated with Deactivate or Space. A deactivated item is shown grey with a red no-entry sign; clicking the sign activates it again. Deactivated items stay in the model but are written to the input file only as a comment, so CalculiX ignores them.

3.6.4 Renaming

Tree items are renamed in the Name field of their dialog. Mesh parts are renamed in their Properties dialog. Names are converted to upper case and may contain letters (no umlauts), digits, _ and -, up to 80 characters. Items that refer to a renamed part, material or amplitude follow the new name. Geometry parts cannot be renamed, because the mesh setup refers to them by name.

3.6.5 Properties dialogs

A double-click on a part opens its properties: name, number of elements and nodes, element types, colour and visibility. On the FE Model tab the element types can be changed (Section 4.2.2). On the Results tab, a double-click on Model shows file, load time, node and element counts, element types, the dimensions of the model and its sets and surfaces. A double-click on a result component shows its maximum and minimum with the node where they occur.

3.7 Files and projects

3.7.1 File menu of an analysis window

The File menu of the project window is described in Section 3.1. The analysis window has these entries:

3.7.2 What each file type does

.plx (PrePoLix project)

all analyses of the project, each with its geometry, mesh setup, mesh, FE model and the results it keeps (Section 6.3), and the place of its block in the schematic. Saving writes a temporary file first and then replaces the old one, so a crash during saving cannot destroy the project, together with the links between the analyses. A project written by a newer version of PrePoLix is refused, and so are projects saved by PrePoLix 0.2.6 and older, which held one model only. Projects of the first multi-analysis format (one model space for all analyses) are converted on opening: their results are dropped and have to be solved again, and once saved, the project no longer opens in older versions.

.inp (CalculiX input)

imported with Geometry → Import ... (Section 4.1.1). Only the mesh is read: nodes, elements, *NSET, *ELSET (also GENERATE), *SURFACE and files referenced with *INCLUDE. Every element set named in *ELEMENT, ELSET=... becomes a part. All other keywords (materials, steps, …) are skipped and listed in the output pane.

.frd (CalculiX results)

the results of the analysis’ own runs. Result files from elsewhere are not opened.

CAD files

imported with Geometry → Import ... (Section 4.1).

Supported element types of .inp meshes: C3D4, C3D6, C3D8, C3D10, C3D15, C3D20 with their R and I variants, S3, S4, S6, S8, M3D membranes, CPS/CPE/CAX plane and axisymmetric elements, B31, B32, T3D2 and T3D3.

3.7.3 Drag and drop and command line

A project file dropped onto the project window or an analysis window opens in the project window. CAD files and input files dropped onto an analysis window are imported into it; several CAD files dropped together are combined into one geometry.

On the command line, prepolix project.plx opens the project. Other files, for example prepolix plate.step, start a new project with one analysis named after the first file, into which the files are imported. Without files, PrePoLix reopens the last saved project that was open at exit.

3.8 Undo and redo

Edit → Undo (Ctrl+Z) takes back the last change of the model, Edit → Redo (Ctrl+Shift+Z) makes the last undone change again. Every change counts once, however it was made: an item created, edited in its dialog, deleted, moved, activated or deactivated, a part renamed or deleted, a mesh setup item changed, the mesh generated anew or edited with a mesh tool. A new change drops what could be redone. Undo returns to the state at each change.

The shortcuts act on the model when no text field has the focus; in a text field, Ctrl+Z undoes the typing there. Undo and Redo are greyed out while a dialog is open, while meshing runs and on the Results tab; the tooltip of the greyed-out entry says why. The output pane notes each undo and redo.

The last 100 changes can be undone, of which at most 10 that replaced the mesh, as each keeps a copy of the mesh. The history starts empty for each model opened or created.

3.8.1 In the project window

The project window has its own Edit → Undo (Ctrl+Z) and Edit → Redo (Ctrl+Shift+Z or Ctrl+Y) for the schematic: blocks added, copied, deleted or renamed, blocks moved, links drawn or removed, and what is entered in the dialogs of the blocks (parameters, measures, parameter studies, mesh and material blocks, new analyses). A deleted block comes back with its links and everything it held. The output pane notes each undo and redo; the last 100 changes can be undone, and the history starts empty for each project opened or created.

Changes made inside an analysis are undone in its window (above). A change that would replace the data of an analysis whose window is solving, meshing or loading waits: the output pane says so, and the change can be undone once the window is idle. A solve is no change that can be undone.

3.9 The 3D view

3.9.1 Mouse and keyboard

Rotating keeps the point you grabbed where it is, so you can look at a small detail at the end of a long structure from all sides without it leaving the screen.

Keyboard shortcuts of the main window: Ctrl+N new, Ctrl+O open, Ctrl+S save, Ctrl+Shift+S save as, F5 run analysis, Del delete the selected tree item, Space activate or deactivate it. In dialogs Enter means OK and Esc Cancel.

3.9.2 Views

The projection is orthographic. Y points up in the front view.

• Front, Back, Left, Right, Top, Bottom and Isometric are on the toolbar and in the View menu.
• Vertical View rolls the view about the viewing direction so that the global axis closest to screen-up points exactly up.
• View → View Normal to Axis → X/Y/Z looks along an axis onto the plane normal to it.
• View → Isometric, Axis Up → X/Y/Z shows the isometric view with the chosen axis pointing up, for models built with Z up.
• The coordinate triad in the lower right corner can be clicked: a click on an axis tip (or on its grey negative half) looks along that axis.

A 2D model always opens in the front view. Legend, info block, scale bar and min/max labels can be dragged to another position in the view.

3.9.3 Showing and hiding parts

Each part in the tree has a visibility check box. Hide and Show in the context menu of a part act on all selected parts. Hidden parts cannot be picked and are ignored by box selection and by Zoom to Fit.

3.9.4 Screenshots

The Screenshot button on the toolbar captures the 3D view including legend and labels: Copy to Clipboard or Save As ... (PNG).

3.9.5 Section view

View → Section View ... or the toolbar button cuts the model with a plane. Volume elements show their cut faces with mesh edges and, on the Results tab, with the result colours.

In the 3D view the plane has a manipulator: drag the arrow to move the plane, drag the arcs to tilt it. Changes are shown at once. OK keeps the section, Deactivate removes it, Cancel restores the previous state. View → Section View Off removes the section as well.

3.9.6 Exploded view

View → Exploded View ... pulls the parts of an assembly apart for display. The mesh itself is not changed; parts that share nodes move together. A left click on the toolbar button switches the exploded view on and off, a right click opens the settings.

3.10 Selecting regions

Boundary conditions, loads, constraints, contacts, mesh settings and many result tools act on a region of the model. You define it by clicking in the 3D view while the item’s dialog is open.

3.10.1 Region field

Each dialog with a region has a Region field. Its combo box chooses where the region comes from; the choices depend on the item:

Selection in the 3D view

picked nodes, element faces, edges, parts or CAD faces. The field shows what is selected (“12 element faces”) and has a Clear Selection button.

Parts

whole parts, picked in the 3D view.

Node Set, Element Set, Surface

sets and surfaces of an imported .inp mesh, or ones you defined yourself (Section 4.6).

The ... button next to a field makes it the target of clicks in the 3D view; it is shown pressed while it is active. Dialogs with two regions (master and slave) use one ... button per region to switch between them.

3.10.2 Selection window

While a dialog picks, the Selection window opens next to it and decides what a click selects.

Geometry based

Faces, edges and points selects the CAD face under the cursor, split faces included (Section 4.1), or on a mesh without geometry the smooth patch of faces; near a feature edge or corner, within a few pixels, it selects that. Part selects whole parts. Edge angle and Surface angle grow the selection across edges or faces as long as the angle between neighbours stays below the given value (default 30°).

Mesh based (More)

Node, Element, Edge, Surface, Part, Edge angle, Surface angle and ID. ID takes a list such as 1, 5, 10-20 with Add and Remove for face and edge regions the numbers are element numbers.

Modes that do not fit the region are disabled, for example Node for a pressure load. On the Geometry tab, for mesh setup items such as a Local Mesh Size, the window offers only the geometry based modes, as the geometry has no mesh yet; All and Invert act on the faces of the visible parts. Undo takes back the last pick, Clear empties the selection, All and Invert act on the visible items.

3.10.3 Modifier keys and box selection

• A plain click replaces the selection, Shift adds, Ctrl removes, Shift+Ctrl keeps only the intersection. A plain click into empty space clears the selection.
• Dragging with the left button draws a box. Dragged from left to right (blue) it takes what lies completely inside; dragged from right to left (green) it also takes what crosses the box.
• When the mouse rests for a moment, what a click would select is previewed in orange.

3.11 Entering values

Numeric fields accept a decimal point or a comma, scientific notation (2.1e5, 2,1e5) and the typographic minus sign. Thousands separators are not allowed, and the fields do not evaluate arithmetic expressions. You can also drag a field with the mouse to change its value.

Fields of physical quantities show the unit of the model’s unit system behind the value (Section 5.1.3). You may type a value in another unit and PrePoLix converts it: in a model in mm, 3 cm becomes 30 mm; other examples are 200 GPa, 7.85 g/cm³, kN·m, N/mm², W/(m²·K), 5°, rpm, psi and °F. The unit must belong to the quantity of the field. In a unitless model, enter numbers only.

PrePoLix never rounds what you typed: values are shown with all significant digits, very small or very large values in scientific notation.

3.12 Settings

Tools → Settings ... opens the settings window. The pages are listed on the left. Defaults resets all pages, Apply applies without closing. Settings are stored per user (~/.local/share/prepolix on Linux, %APPDATA%\prepolix\data on Windows), by the portable Windows version in the folder Settings next to prepolix.exe (Section 1.3.1).

3.12.1 Graphics

3.12.2 Post-processing

3.12.3 CalculiX

Keywords. Older CalculiX versions lack keywords of newer features, for example *COMPLEX FREQUENCY (complex frequency step) or *CYCLIC SYMMETRY MODEL. CalculiX does not stop at an unknown keyword: it skips the card with a warning and computes without it. The test therefore reads each keyword PrePoLix can write on its own and lists the unknown ones by the feature that needs them, e.g. Complex frequency step (*COMPLEX FREQUENCY). Every analysis checks the keywords of its own input file in the same way, including those of the keyword editor (Section 6.4).

3.12.4 Gmsh

3.12.5 Updates

Below, the page says how this copy of PrePoLix is updated (Section 1.4).

4 Geometry and Mesh

4.1 Importing geometry

Geometry → Import ... or the toolbar button Import Geometry reads STEP (.step, .stp), IGES (.iges, .igs) and BREP (.brep) files. Several files can be selected at once. Gmsh with OpenCASCADE reads the files, so Gmsh must be available (Section 3.12).

• The geometry is read into the open analysis, in its model space and length unit (both were chosen when the analysis was created, Section 3.1.1).
• If the model already has geometry or a mesh, the imported parts are added. Existing parts keep their names, mesh settings and selections.
• STEP and IGES files are converted to the length unit of the model. BREP files have no unit and are read as they are.
• Default element sizes are derived from the size of the geometry: maximum 5 % and minimum 0.1 % of the bounding box diagonal.
• Parts keep the names they have in the CAD program, as STEP files from Onshape, SolidWorks or FreeCAD carry them, for solids and for surface parts alike. The names are made fit for CalculiX: upper case, letters, digits, - and _, German umlauts written out (Stütze becomes STUETZE). A name that is already taken gets a number appended (OBEN-2). Parts without a name in the file are called SOLID-1, SHELL-1 or LINE-1.

4.1.1 Importing a mesh

The same dialog also takes input files (.inp). Their mesh is added to the model as mesh parts, for example a mesh written by File → Export Deformed Mesh (.inp) ... (Section 6.7) to use a buckling mode as imperfection. Select the files in the file dialog (the filter Input file shows only those) and the parts appear on the FE Model tab.

• A model is never replaced. If it already has parts, the imported nodes and elements are numbered after the highest numbers it has, so nothing that refers to the existing parts changes.
• A part, set or surface whose name is already taken gets a number appended: the second PART-1 becomes PART-1-2.
• Only the mesh is read: nodes, elements, sets and surfaces. Materials, steps and loads of the file are skipped and listed in the output window.
• The mesh must fit the model space of the analysis: a mesh of plane stress elements goes into a 2D plane stress analysis, solids into a 3D one. A 2D mesh cannot be added to a 3D analysis or the other way round.

4.1.2 Parts

Every solid becomes a part. Faces that do not belong to a solid become shell parts, edges that do not belong to a face become line parts (for beams and trusses). Part names are taken from the CAD file where it has names, otherwise they are SOLID-1, SHELL-1, LINE-1 and so on.

The context menu of a geometry part has Create Mesh, Properties ..., Hide/Show and Delete. Deleting a geometry part keeps a mesh that was already created from it.

4.1.3 Split faces

It is common to split faces in the CAD program, for example a ring on a shaft where a bearing sits, so that a boundary condition can be applied to exactly that area. PrePoLix keeps such faces: the mesh follows their borders, and on the FE Model tab their outline is drawn like any other edge although the surface does not bend there. Pick them with the geometry based selection (Section 3.10) like any other face.

4.1.4 Geometry for 2D models

In a 2D model the geometry must consist of faces only and lie in the plane z = 0. For an axisymmetric model it must lie at x ≥ 0, because the y axis is the axis of rotation. Otherwise the import is refused with a message. Faces whose normal points in −z direction are flipped when they are meshed.

Many CAD programs draw a sketch or a face on a plane away from the origin. A file whose geometry lies flat in a plane parallel to the x-y plane, at a constant z, is therefore moved into the plane z = 0 when it is imported, and the Output names the file and the height it came from. This is checked file by file, also when files are added to a geometry. Geometry that is tilted or has any thickness in z stays where it was drawn.

4.2 Meshing

PrePoLix meshes each geometry part separately with Gmsh. Parts do not share nodes; connect them with ties, contacts or node ties (Section 5.5).

• Mesh → Mesh All Parts meshes every part.
• Create Mesh in the context menu of a part meshes only this part. Its old mesh is replaced; the other parts keep their node and element numbers.

The output pane lists each part with its element count and size range. Afterwards PrePoLix switches to the FE Model tab.

4.2.1 Element types

Solids and lines can only be meshed in 3D models. Faces are meshed in both: in a 3D model they become shells, which get their thickness from a Shell section; a solid section on shells is reported as an invalid section.

4.2.2 Changing the element type

A part on the FE Model tab can be given another element type with the same nodes: double-click the part and choose it in the Element type box, then OK. A part with several element types has one box per type.

Membranes need a membrane section (Section 5.3.5). Quadratic triangles and wedges have one type only, which is shown as text, as do linear triangles in 2D models. Lines get their type from their section (Section 5.3). The choice is kept with the part: meshing the part again gives the new elements the same type, and in a 2D model a new model space keeps the reduced integration (CPS8R becomes CAX8R).

4.2.3 Meshing errors

If Gmsh fails, the output pane shows “Meshing failed: …” with the message of Gmsh. The faces, edges and points the message names are marked red on the Geometry tab, so you can see where the problem is. The marking disappears with the next meshing.

4.3 Mesh setup

The mesh is controlled by the Mesh Setup items on the Geometry tab. Create them with Mesh → Create Mesh Setup Item ... or Create ... on the Mesh Setup container.

4.3.1 Default mesh parameters

Mesh → Default Mesh Parameters ... sets the parameters for every part that is not covered by a Meshing Parameters item. Mesh All Parts in this dialog applies the values and meshes at once.

4.3.2 Mesh setup items

Meshing Parameters

the fields above for selected parts. If several items name the same part, the last one counts.

Local Mesh Size

an element size on selected CAD faces and edges. Click them in the 3D view; Shift adds, Ctrl removes. The Selection window next to the dialog (Section 3.10.2) offers the geometry based modes: Faces and edges takes the face under the cursor or the edge near it, Part all faces of a part, Edge angle the clicked edge and the edges that continue it, Surface angle the clicked face and the neighbouring faces that meet it at less than the angle, such as the pieces of a split cylinder. A box takes the faces inside it. The default size is a quarter of the maximum element size.

Tetrahedral Gmsh

chooses the Gmsh algorithms for selected parts. Surface algorithm: Frontal-Delaunay (default), Delaunay, MeshAdapt or Automatic. Volume algorithm: Delaunay (default), Frontal or HXT.

Extrude Mesh

hexahedra and wedges for parts that are extrusions of a face (Section 4.3.3).

OK stores the item. OK & Remesh stores it and meshes again the parts it names. A Local Mesh Size item is picked on faces and edges, so it meshes all parts again.

4.3.3 Extrude mesh

A part that is a straight extrusion of a face, such as a plate with holes, a profile or a gear blank, can be meshed with hexahedra instead of tetrahedra. The Extrude Mesh item meshes the source face with Gmsh, mostly with quadrilaterals, and sweeps that face mesh through the part in layers: every quadrilateral becomes a hexahedron (C3D8, or C3D20 with second order), every triangle a wedge (C3D6, C3D15). The size of the face mesh comes from the part’s meshing parameters and local mesh sizes, as for tetrahedra.

Before meshing, prepolix checks that the part really is an extrusion of the source: every vertex at the boundary of the source has a straight edge of the same length and direction to its copy at the other end, and the part’s volume is the source’s area times the height. If not, meshing fails with a message naming the part; mesh it with tetrahedra or select the faces at one end. The element type can be changed afterwards in the part’s properties (Section 4.2.2), for example to C3D8I, which bends without the locking of C3D8. A later Tetrahedral Gmsh item for the same part meshes it with tetrahedra again.

Without an item, Hexahedra where possible in the meshing parameters runs the same automatic search for every part they cover. A part where no source face is found is meshed with tetrahedra without an error; a Tetrahedral Gmsh item naming a part keeps it tetrahedral.

4.3.4 Bodies of revolution

Hexahedra where possible also finds parts that are a section turned about an axis: rings, flanges, hubs and segments of them. Their edges are circles about one common axis and profile curves in planes through it. prepolix meshes the section with quadrilaterals and turns that mesh about the axis in steps of about the max element size at the largest radius, at least 16 steps for a full turn. A segment is turned from one of its end faces to the other; a closed ring gets a section cut through it and ends where it started. The result is hexahedra, with wedges where the section mesh has triangles (Figure 69). Faces, edges and vertices of the geometry stay selectable on the mesh.

A part counts as a body of revolution only if its volume is that of its section turned about the axis. Parts that reach the axis, such as solid shafts, keep tetrahedra: their elements at the axis would have to be pyramids, which CalculiX lacks. A part that is both an extrusion and a body of revolution, a plain ring for example, is meshed as an extrusion.

4.4 Using an existing mesh

A CalculiX mesh can be imported with Geometry → Import ... (Section 4.1.1). Its node sets, element sets and surfaces appear under Mesh in the FE Model tree and can be used as regions. Such a mesh has no geometry, so regions are picked on the mesh.

4.5 Mesh tools

The mesh tools change an existing mesh without meshing again: they move or mirror parts, join parts, merge nodes that lie on top of each other and renumber the mesh. They work on the FE Model tab, on meshed geometry as well as on imported meshes.

4.5.1 Transform parts

Transform ... in the context menu of one or more parts under Mesh moves their nodes.

Mirrored elements are turned inside out again, so they stay valid; the surfaces, sets and regions of the model follow the elements. Only the mesh moves: meshing the geometry again restores its position. In 2D models the rotation axis is the z axis and the transformations have two components.

4.5.2 Merge parts

Select several parts under Mesh (Ctrl adds to the selection) and choose Merge in their context menu. The elements of the other parts join the first selected part, which keeps its name; element sets of the same name are joined too, and sections, loads and other items that named a merged part now name the kept part. The nodes are not merged: use Merge coincident nodes afterwards where the parts touch.

4.5.3 Merge coincident nodes

Mesh → Merge coincident nodes ... joins nodes of all parts that lie within the Tolerance (default 0.1 mm) of each other into one node, the one with the lowest number. This connects parts that were meshed separately but share their boundary nodes exactly, for example halves of an imported mesh. The output pane reports how many nodes were merged.

4.5.4 Renumber nodes and elements

Mesh → Renumber nodes and elements ... numbers all nodes and elements from the First node number and First element number on (default 1), in their current order, without gaps. Sets, surfaces and the regions of the model follow the new numbers.

4.6 Node sets, element sets and surfaces

You do not need sets to set up a model: every dialog with a region takes a selection directly. Named sets are useful when several items share the same region, or when you want to keep a selection under a name. They are listed under Mesh in the FE Model tree, together with the sets and surfaces of an imported .inp mesh.

Double-click Node Sets, Element Sets or Surfaces, or choose Create ... in their context menu, to define a new one. Double-click a set, or choose Edit ... in its context menu, to change it; Delete or the Delete key removes it. Selecting a set in the tree highlights it in the 3D view.

Node Set

the picked nodes, or all nodes of the picked faces, edges or parts.

Element Set

the elements of the picked faces or of whole parts.

Surface

the picked element faces.

The set remembers the selection, not only the node and element numbers: a set picked on the geometry is found again on a new mesh after meshing again. A set whose selection is no longer on the mesh (picked nodes of an old mesh) is still listed, but stays empty until you pick it again; items using it show a missing reference.

Sets are used through the region combo box of the dialogs (Node Set, Element Set, Surface). Renaming a set renames it in every item that uses it. The input file contains the sets as *NSET, *ELSET and *SURFACE with your names.

Editing a node set or an element surface of an imported mesh turns it into a set of your own with the same nodes or faces, which you can then pick anew.

5 The FE Model

The FE Model tab holds everything CalculiX needs besides the mesh: materials, sections, constraints, contacts, amplitudes, initial conditions and steps with their boundary conditions, loads and outputs. Most items are created from the Model and Interaction menus or with Create ... in the context menu of their container in the tree.

5.1 Model properties

Model → Model Properties ... (or a double-click on Model in the tree) shows the basic properties of the model. The same dialog opens when an analysis is created (Section 3.1.1); the model space and the unit system are chosen there and fixed from then on. The dialog of an existing analysis shows them, but only the model type and the physical constants can still be changed. For another model space or unit system, create a new analysis.

5.1.1 Model space

3D

solids, shells and lines.

2D plane stress

plane elements (CPS), the section has a thickness.

2D plane strain

plane elements (CPE), the section has a thickness.

2D axisymmetric

axisymmetric elements (CAX). The y axis is the axis of rotation, the model must lie at x ≥ 0.

All 2D models must lie in the global X-Y plane. Hovering over a model space shows a short hint on when to use it: plane stress for thin parts loaded in their plane, plane strain for long prismatic parts without strain out of the plane, axisymmetric for bodies of revolution.

Geometry and meshes must fit the model space of their analysis: a 2D mesh from an input file cannot be imported into a 3D analysis, nor solids into a 2D one.

5.1.2 Model type

General model or Submodel. A submodel takes the displacements at its cut boundaries from a global model. With Submodel, the block of the analysis in the project schematic gets a Global results row: the results of a step of the global analysis are dragged there (Section 6.6). No result file is picked in the dialog.

5.1.3 Unit system

The dialog lists the base and derived units of the chosen system.

How values are stored. PrePoLix stores every value of the mesh, the geometry and the model in SI units (m, kg, s, N, Pa; temperatures in °C), whatever the unit system of the analysis. The unit system only decides how values are shown and typed: a dialog of an analysis in mm, ton, s shows lengths in mm and stresses in MPa, and converts what you type. A value typed with another unit is converted too, for example 3 cm in a length field becomes 30 mm. The input file CalculiX gets is therefore always in SI units, which the keyword editor says above its text (Section 5.24); results are shown in the unit system of the analysis (legend, scale bar, queries, tables). Because of this, analyses of one project may use different unit systems and still share meshes, materials and results through links (Section 3.2).

5.1.4 Physical constants

Absolute zero and Stefan-Boltzmann are only needed for thermal radiation. Defaults fills them in for the selected unit system. They are written as *PHYSICAL CONSTANTS.

5.2 Materials

Model → Create Material ... creates a material. Each property is switched on with its check box. A new material starts with Elasticity switched on.

Values can be typed in any unit of the right kind, for example 210 GPa or 7.85 g/cm³ (Section 3.11).

5.2.1 Material library

Material Library ... in the context menu of Materials opens the material library. On the left are the library materials in categories, on the right the materials of the model.

• Copy to Model and Copy to Library copy the selected material. Values are converted between the unit system of the library and that of the model. A name that already exists gets a suffix.
• Add Category, Rename, Delete, Move Up and Move Down organise the library.
• Preview Material Properties shows the values of the selected material.

A new library contains Generic Steel (category Steel / Structural) and generic plastics in the category Plastics: PLA, PETG, ABS, PA6, PA12, PET, PC, PP, POM and PMMA. Each has density, Young’s modulus, Poisson’s ratio, thermal expansion, thermal conductivity and specific heat. The values are typical room-temperature means from datasheets. Plastics vary a lot with grade, moisture, temperature and, for 3D printing, with print orientation and infill, so treat them as starting points and replace them with the values of your material.

Libraries saved by an older version are updated when they are opened: missing generic materials are added, and the former S235 is renamed to Generic Steel if you have not changed it. Materials you changed or deleted are not touched afterwards.

The library is stored per user in materials.ron in the settings folder (Section 3.12). When the dialog is closed, PrePoLix asks whether to save changes to the library.

5.2.2 Plasticity

Plasticity in the material dialog adds von Mises plasticity with a tabular hardening curve. It needs Elasticity on the same material.

A single row gives an ideally plastic material. Beyond the last point CalculiX keeps the last yield stress. The model check (Section 6.4) reports a curve that does not start at strain 0, a strain that does not grow, or plasticity without elasticity as “Invalid plasticity”.

Plastic strains need a nonlinear analysis: switch on Nonlinear geometry or use automatic incrementation with several increments in the static step (Section 5.10), and request PEEQ (equivalent plastic strain) in the element field output to see where the material yields.

5.3 Sections

A section assigns a material to elements. Every element needs a section, otherwise the model check reports “Elements without material”. Create sections with Model → Create Section ....

5.3.1 Solid section

For solid elements and the plane and axisymmetric elements of 2D models. In plane stress and plane strain models the section has a Thickness (default 1). Written as *SOLID SECTION.

5.3.2 Truss section

For line parts that carry only axial force. Cross-section area must be positive. The lines are written as T3D2 truss elements.

5.3.3 Beam section

Beams are written as *BEAM SECTION with B31 or B32 elements. Pipe and box sections need quadratic lines and are written as B32R, as CalculiX requires.

5.3.4 Shell section

A Shell section gives surface elements of a 3D model a thickness, so that a thin plate or a sheet-metal part can be computed with shell elements (S3, S4, S6, S8) instead of solids. Create it with Model → Create Section ... and choose Shell.

Written as *SHELL SECTION, ELSET=..., MATERIAL=... with the thickness on the next line. As soon as the model has a shell section, the field outputs are written with OUTPUT=2D, so that the results are reported at the shell nodes instead of the nodes CalculiX expands the shells to internally, and the result file keeps the node numbers of the model.

Shell nodes have rotations: Displacement/Rotation boundary conditions can hold UR1, UR2, UR3, and Moment loads can act on them.

5.3.4.1 Shell thickness in the FE model

The FE model shows the elements of shell and membrane sections as the solid their section gives them: the surface thickened by the Thickness, with the mesh lying where the Offset puts it. The top face is the side the element normal points to, so an offset of 0.5 draws the solid below the mesh and −0.5 above it. Neighbouring elements whose normals point to opposite sides show a step, which reveals a flipped normal before the analysis is run.

Turn the display off and on with View → Shell Thickness or in the settings under Graphics. Picking still selects the elements on the mesh, and the Results workspace is not affected.

5.3.5 Membrane section

A Membrane section is the shell section’s sibling for structures without bending stiffness: foils, fabrics, balloons, pretensioned roofs or a thin skin on a solid. A membrane carries forces in its plane only, like a tensioned cloth. Its nodes have no rotations, and a flat membrane can take a load across its plane only once it is pretensioned or deforms, which needs a geometrically nonlinear step (Nlgeom). For a plate under a lateral load the shell section (Section 5.3.4) stays the right choice.

Create it with Model → Create Section ... and choose Membrane. The mesh must be linear: mesh the part with Second order off (Section 4.3). Linear shells of the region (S3, S4, S4R) are written as the membranes M3D3, M3D4 and M3D4R, so the part keeps its element type. A membrane type can also be chosen for the part itself: double-click it on the FE Model tab and pick it in the Element type box (Section 4.2.2).

Written as *MEMBRANE SECTION, ELSET=..., MATERIAL=... with the thickness on the next line. The field outputs are written with OUTPUT=2D, as for shells.

Membranes have to be linear: CalculiX 2.23 computes the quadratic membranes M3D6 and M3D8 wrongly (in a simple tension test M3D8 is 1.7 times too soft and gets softer with a thicker section). The model check reports a membrane section on quadratic or solid elements, and a shell or solid section on membranes, as an error Section does not fit its elements.

A membrane strip of 100 × 10 × 2 stretched by 0.1 in a first step and loaded with a pressure in a second one sags at mid-span as a taut string does,

with the tension

per width; PrePoLix’s tests check this with CalculiX.

5.4 Features

Under Features in the tree you define reference points, coordinate systems and planes. They are helpers for other functions (section views, plane results, paths, result transformations) and are not written to the input file. The results have their own copy of the features, which can be edited on the Results tab.

Points can be typed in or picked with .... In the geometry mode Points, the default of the selection window, a click on a face or edge takes the corner point of the geometry nearest to it, also in 2D models. With More the mesh based modes pick a node, or the centre of the nodes of a picked edge, element or surface, for example the centre of a hole.

Reference Point

a named point. Create by offers:

• Coordinates: typed in or picked, in the global system or in a coordinate system of the features chosen under Coordinate system. In a cylindrical system the coordinates are R, Theta in degrees and Z. The point follows the coordinate system when it changes.
• Center of gravity: the area-weighted centre of the faces selected in the 3D view (in 2D models of the edges), e.g. the centre of a hole or of an end face.
• Bounding box center: the centre of the box around the selected faces.

A point at the centre of a selection moves with the mesh: after remeshing, a selection of geometry faces gives the new centre. Global position shows where the point lies.

Coordinate System

Rectangular or Cylindrical, defined by Origin, Point on x-axis and Point in xy-plane. For a cylindrical system the z axis is the cylinder axis and the directions are r, θ and z.

Plane

by Coordinate system (a plane XY, YZ or XZ of a system with an offset), by Three points (normal by the right-hand rule) or by Point and normal. A plane built on reference points follows them when they change.

5.5 Constraints

Parts meshed separately share no nodes. Constraints connect them or attach springs to the model. Create them with Interaction → Create Constraint ... or with Create ... on Constraints.

Surface-to-surface springs have a Master and a Slave region, each with its own ... button. Choose the finer mesh as slave. Swap Master/Slave in the context menu exchanges the two.

The 3D view of the FE model shows active constraints in yellow, together with the symbols of any step: a coil spring for each direction with stiffness, at each node of a point spring (at their centre for ten nodes or more), at the centre of a surface spring and at points spread over the slave surface of a surface-to-surface spring; cones pushing onto the surface of a compression only support; and lines to the reference point of a rigid body (Section 5.7). The selected or edited constraint is red. Ties have no symbol.

Hide in the context menu of a constraint removes its symbol from the 3D view, Show brings it back; the tree marks a hidden constraint with an eye. Hide All and Show All in the context menu of Constraints do this for all constraints at once. A hidden constraint is still drawn while it is selected, and the setting is saved with the project. Hiding changes only the view, not the analysis; Deactivate leaves a constraint out of the input file.

5.6 Contacts

5.6.1 Surface interactions

Interaction → Create Surface Interaction ... defines the contact behaviour that contact pairs refer to. Move the models you need from Available to Selected.

A Tied surface behavior glues the surfaces together, like a Tie, but as a penalty contact. CalculiX needs Friction with it in the same surface interaction: the Stick slope is the stiffness of the tie along the surfaces (half the Young’s modulus of the first material if empty), the friction coefficient is irrelevant. Without friction the run aborts. So choosing Tied adds Friction to the selected models at once, and the dialog does not accept a tied interaction without it. Tied contact works only with the method Surface to surface. The model check reports contact pairs that use it otherwise.

5.6.2 Contact pairs

Interaction → Create Contact Pair ... creates a contact between a master and a slave surface.

In 3D models the master and slave regions can also be edges of shells and membranes, where a shell meets a solid face edge on: a click near a free edge of a shell picks the edge, and so do Edge angle and, under More, Edge. CalculiX takes such an edge as a face of the shell (S3 and up). For a contact on a shell edge use Surface to surface with a Tied surface behavior (with its Friction, see above).

5.6.2.1 Which method?

Hover over a method in the list to see a short description. The Search Contact Pairs window shows the same texts.

5.6.3 Ties

Interaction → Create Tie ... or Create Tie ... in the context menu of Contact Pairs glues a slave surface to a master surface (*TIE). Ties are listed under Contact Pairs, with the contact pairs and node ties; projects that kept them under Constraints open with them moved there.

5.6.4 Node ties

Create Node Tie ... in the context menu of Contact Pairs makes all nodes of a region move together. It connects the ends of beams and trusses of different parts. With Rotations: rigid the connection also transmits moments; without it, beams are connected by a hinge.

5.6.5 Searching contact pairs

Interaction → Search Contact Pairs ... finds surfaces of different parts that touch and creates ties or contact pairs for them.

Search fills the table; its Geometry column tells what touches, e.g. Solid-Shell edge where the edge of a shell or membrane stands on a solid. Each row can be edited and switched off with its check box; select several rows to edit them together. The context menu of a row has Swap Master/Slave and Merge by Master/Slave. PrePoLix chooses the coarser mesh as master, then the stiffer material, then the larger surface; an edge of a shell is always the slave of a face. A shell touches with the side facing the other part: CalculiX ties its top (S2) or bottom (S1). OK creates the checked pairs, all under Contact Pairs line ends become node ties. Surfaces that are whole CAD faces or edges are stored by geometry and survive remeshing.

CalculiX ties the edge faces of membranes to nothing (the solver stops with a singular stiffness matrix), so PrePoLix writes the slave side of a tie on membrane edges as a node surface of the edge’s nodes; a membrane has no rotations that would need more.

5.7 Rigid bodies, moments and reference points

A Rigid Body constraint makes the nodes of a region move as one rigid body, driven by a reference point: a bolt head, a bearing seat or a face a lever acts on. Create it with Interaction → Create Constraint ... and choose Rigid Body. To only hold or move a face as a rigid body about its centre, a Remote Displacement boundary condition (Section 5.17.1) needs no reference point.

In the 3D view of the FE model, a rigid body is drawn as yellow lines from nodes spread over its region to its reference point, with the symbols of any step. A selected or edited rigid body is drawn in red; a deactivated one has no lines.

Written as *RIGID BODY, NSET=..., REF NODE=..., ROT NODE=...: PrePoLix adds a reference node at the point for the translations and a rotation node for the rotations, as CalculiX requires.

5.7.1 Loads and supports on a reference point

Boundary conditions and loads can act on a reference point instead of on nodes: choose Reference Point as the region in their dialogs. The point must drive an active rigid body, otherwise the model check (Section 6.4) reports “Reference point without rigid body”.

• A Displacement/Rotation boundary condition on the point holds or moves the whole body; UR1, UR2, UR3 turn it about the point.
• A Force on the point pulls the whole body with the given force.
• A Moment load (M1, M2, M3, written as *CLOAD on the rotational degrees of freedom 4 to 6) turns the body about the point. Moments can also act on nodes of beams or shells, which have rotations of their own, and need a 3D model.

The reaction forces and moments of a held reference point can be requested with a history output (Section 7.10) of RF on the point.

5.8 Amplitudes

An amplitude describes how a load or a prescribed value changes with time. Create it with Model → Create Amplitude ... and choose it in the Amplitude field of a boundary condition or load.

The factor is interpolated linearly between the points and stays constant before the first and after the last point. Times must not decrease. The amplitude is written as *AMPLITUDE.

With Default instead of an amplitude, CalculiX ramps the value up linearly over a static step and applies it at once in a heat transfer step.

5.9 Initial conditions

Model → Create Initial Condition ... sets a state of the model before the first step. The region can be a selection, parts, a node set or a surface.

Velocities only act in a dynamic step; static, frequency and thermal steps ignore them without a message, and the model check (Section 6.4) reports a velocity without a dynamic step. In 2D models a velocity has two components and the axis of a rotation is the z axis.

5.10 Steps

A step is one analysis of CalculiX with its own boundary conditions, loads and outputs. Create it with Model → Create Step ... or Create ... on Steps. A new step copies the boundary conditions and loads of the last step, as far as its type accepts them. The type of a step cannot be changed after it was created.

5.10.1 Step types in the tree

Every step shows a pictogram of its type in front of its name, so that you can tell the steps apart whatever you named them. Hover over the pictogram or the name to read the type.

A deactivated step shows the red no-entry sign instead; its tooltip still names the type.

5.10.2 Order of the steps

CalculiX runs the steps in the order of the list, and a step starts from the state at the end of the previous one. To change the order, right-click a step in the Steps list and choose Move Up or Move Down. The step keeps its boundary conditions, loads, defined fields and outputs, and stays selected. Move Up is disabled on the first step and Move Down on the last.

Steps that build on the previous one, such as a step with Perturbation, take the state of whatever step now precedes them, so check the order after moving. The step numbers of existing results refer to the order at the time of the run.

5.10.3 Solver

All step types have a Solver field: Default (Pardiso or PaStiX if available), Pardiso, Spooles, PaStiX, Iterative scaling or Iterative Cholesky. Default uses Pardiso if the CalculiX executable contains it, otherwise PaStiX if it contains that, otherwise the default of CalculiX. The CalculiX shipped with PrePoLix contains PaStiX and SPOOLES; on models with many nodes PaStiX is several times faster. Frequency and buckle steps need a direct solver.

5.10.4 Static

5.10.5 Frequency

Computes eigenfrequencies and mode shapes (*FREQUENCY). A frequency step takes no loads.

Materials need a density in a frequency step.

5.10.6 Buckle

Computes buckling factors and buckling modes (*BUCKLE). The loads of the step are the reference load: the critical load is the buckling factor times these loads.

5.10.7 Heat Transfer, Coupled and Uncoupled Temperature-Displacement

Heat Transfer computes temperatures only (*HEAT TRANSFER). Coupled Temperature-Displacement computes temperatures and displacements together in one system of equations (*COUPLED TEMPERATURE-DISPLACEMENT). Uncoupled Temperature-Displacement (*UNCOUPLED TEMPERATURE-DISPLACEMENT) solves the temperatures first and then the displacements from them in each increment. It is faster and suits thermal stresses as long as the deformation does not change the heat flow, for example through a contact that opens. The step takes the same boundary conditions and loads as the coupled step: temperatures, heat fluxes, films and radiation together with supports and mechanical loads.

Incrementation and solver fields are the same as for a static step.

5.10.8 Visco

A static step over a creep time in which materials with a creep law creep (*VISCO), see Section 5.16.

5.10.9 Field outputs

Field outputs control what CalculiX writes to the result file (.frd) as *NODE FILE, *EL FILE and *CONTACT FILE. A new step gets a node and an element field output whose variables depend on the step type. Create more with Create ... on Field Outputs of a step or with Model → Create Field Output .... Edit one with a double-click. Hovering over a variable shows what it is.

Like boundary conditions, field outputs can be deactivated and deleted from their context menu. A deactivated field output is left out of the input file.

5.10.10 History outputs

History outputs write values of a region to the .dat file in every increment (*NODE PRINT, *EL PRINT, *CONTACT PRINT). Create them with Create ... on History Outputs of a step. Hovering over a variable shows what it is.

CalculiX prints a history output at every increment, so a step gives one row per increment: a linear static step one row, a nonlinear step (Nlgeom, contact, plasticity) as many rows as it takes increments, a frequency or buckle step one row per mode. A history output also stays in effect in the following steps until a step defines history outputs of the same type (node, element or contact) of its own.

When results are opened, the .dat file is read too, and the history outputs appear on the Results tab (Section 7.10).

5.11 Dynamic step

A Dynamic (time integration) step computes the motion of the model over time (*DYNAMIC): the response to a suddenly applied load, an impact or an initial velocity (Section 5.9). Create it with Model → Create Step ... and choose the type in the dialog.

A dynamic step takes the same boundary conditions and loads as a static step, and materials need a density. Loads act from the start of the step with the amplitude of the step; a load that should be applied at once needs a stepped Amplitude (Section 5.8) with the value 1 from time 0, otherwise CalculiX ramps it over the step. The results have one increment per written time step; the Step increments animation (Section 7.6) plays them, and history outputs (Section 7.10) show the motion of selected nodes over time.

5.12 Complex Frequency step

A Complex Frequency (rotating, Coriolis) step computes the eigenfrequencies of a rotating structure with its Coriolis forces (*COMPLEX FREQUENCY), for example the whirl modes of a shaft. Create it with Model → Create Step ... and choose the type in the dialog.

The step needs two steps before it, in this order:

1. A Static step with a Centrifugal load (Section 5.18). Its rotation axis and speed define the rotation; the Coriolis forces come from this load.
2. A Frequency step with Store matrices and eigenmodes and Perturbation switched on. The complex frequency step is solved on the eigenmodes this step writes to the .eig file. Its number of eigenfrequencies limits how many complex frequencies make sense.

The complex frequency step writes *STEP, PERTURBATION exactly when this frequency step has Perturbation switched on, since CalculiX stops when the two steps differ (“the .eig-file was created without perturbation info”). Without perturbation the modes ignore the stiffening by the centrifugal preload of the static step.

The complex frequency step takes the boundary conditions of the step before it and no loads. The model check (Section 6.4) reports a missing stored frequency step as an error (“No stored eigenmodes”) and a Coriolis step without a centrifugal load as a warning (“No rotation”).

Join bonded parts of a rotor with a Tie constraint (Interaction → Create Tie ...), not with a contact pair with tied surface behavior. CalculiX leaves contact pairs out of a frequency step without perturbation, so the parts they hold float; and even with perturbation the Coriolis coupling of the complex frequency step misses the contact, so whirl pairs do not split and modes go missing. The model check warns about both (“Contact ignored”, “Contact with Coriolis”).

The node field output of a new complex frequency step is U, PU: PU writes the magnitude and phase of the displacements of every mode (PDISP), which the whirl animation needs.

5.12.1 Results of a complex frequency step

Every complex mode is its own increment of the step; the increment list shows its real part (the frequency in Hz) as Complex frequency (real part). The deformed shape and the legend show the magnitudes of the displacements.

With the Scale factor animation (Section 7.6) a complex mode whirls instead of swinging: the displacement of every node is

, and the phase

runs through a full turn over the frames. The status line shows the phase of the frame. Forward whirl (with the rotation) and backward whirl (against it) are told apart by the direction the shape turns in.

The .dat file of the step is read into the history outputs (Section 7.10). For every mode, EIGENVALUE_OUTPUT holds OMEGA and FREQUENCY (the real part) and OMEGA_IM (the imaginary part of the eigenvalue, the damping of the whirl), and TURNING_DIRECTION is +1 for a forward and −1 for a backward whirling mode, as CalculiX prints it (F or B).

5.13 Cyclic symmetry

Disks, impellers, gears and flanges repeat one sector around an axis. With cyclic symmetry only that sector is meshed, and a Frequency step still computes the eigenfrequencies of the whole part: CalculiX solves the sector once for every nodal diameter, the number of lines through the axis along which a mode shape does not move. The results are expanded to the whole part. For a static step the tie makes both cut faces move alike (nodal diameter 0).

5.13.1 The cyclic symmetry tie

Create a tie (Section 5.6) between the two cut faces of the sector and tick Cyclic symmetry in its dialog. CalculiX rotates the master face by one sector about the axis onto the slave face (*TIE, CYCLIC SYMMETRY and *CYCLIC SYMMETRY MODEL); which face is which does not matter, as long as the sector angle is 360° divided by the number of sectors.

Only 3D models can be cyclic symmetric. The nodes of the slave face follow the master face, so PrePoLix leaves them out of the boundary conditions: CalculiX refuses a node that is both bound and fixed (“dependent side of a MPC and a SPC”).

5.13.2 Frequency steps by nodal diameter

As soon as an active tie has a cyclic symmetry, the Frequency step dialog shows a Nodal diameter range (*SELECT CYCLIC SYMMETRY MODES). A sector of

sectors carries the nodal diameters 0 to

; unticked, all of them are computed. The Number of eigenfrequencies counts per nodal diameter.

The model check (Section 6.4) reports invalid sector settings, a cyclic symmetry tie in a 2D model and nodal diameters beyond

.

5.13.3 Results

The modes are numbered on through the step, first those of nodal diameter 0, then 1 and so on. The Step, Increment list shows the nodal diameter of every mode (1, 7 (ND 2)), as does the information block of the 3D view. Each mode of a nodal diameter above 0 has a twin of the same frequency, turned by a quarter wave; CalculiX writes the real part (DISP, STRESS) and the imaginary part (DISPI, STRESSI) of the complex mode. The eigenvalue table under History Outputs lists the nodal diameter of every mode in NODAL_DIAMETER.

5.14 Modal Dynamics and Steady State Dynamics steps

Both steps superpose the eigenmodes of the structure instead of integrating the full model: Modal Dynamics (from stored modes) computes the response over time (*MODAL DYNAMIC), Steady State Dynamics (frequency response) the amplitude at every frequency of a harmonic excitation (*STEADY STATE DYNAMICS). Both need a Frequency step with Store matrices and eigenmodes before them, with the same boundary conditions; the model check (Section 6.4) reports a missing one as “No stored eigenmodes”. Create the steps with Model → Create Step ....

5.14.1 Modal Dynamics

Loads of a modal dynamics step need an Amplitude (Section 5.8); a stepped amplitude applies the load at once. Only loads and the boundary conditions of the frequency step act; CalculiX cannot change supports in a modal step.

5.14.2 Steady State Dynamics

The results have one increment per frequency. The displacements are written as real part (DISP) and imaginary part (DISPI); the magnitude of a node is the length of both together.

5.14.3 Modal damping

Both steps have a Modal damping setting, written as *MODAL DAMPING:

5.15 Sensitivity step

A Sensitivity (shape) step (*SENSITIVITY) shows where a change of the shape pays off most. For every node of a design region CalculiX computes how much a design response, such as the strain energy or an eigenfrequency, changes when the node moves a little along the surface normal. The step does not change the model: it is a guide for the next design change, for example whether a larger fillet or a thicker rib raises the stiffness more. Create it with Model → Create Step ... and choose the type in the dialog.

The step evaluates the solution of the step directly before it, so it has no boundary conditions, loads or defined fields of its own:

• Mass and strain energy need a Static step before it.
• Eigenfrequencies need a Frequency step with Store matrices and eigenmodes before it; CalculiX reads the modes from the .eig file.

The model check (Section 6.4) reports a sensitivity step without the fitting step. CalculiX defines the design region once for the whole model: PrePoLix writes the region of the first sensitivity step (*DESIGN VARIABLES, TYPE=COORDINATE), and the check warns when a later sensitivity step has another one.

5.15.1 Results

The step writes the surface normals NORM and one field per design response: SENMASS, SENENER (strain energy) or SENFREQ (eigenfrequencies, one increment per mode with its frequency). DFDN is the derivative of the response with respect to a shift of the node along its outward normal, DFDNFIL the same after the filter, scaled by CalculiX. A negative value of SENENER means that moving the surface outward there lowers the strain energy, that is, material added there stiffens the part most. Values near zero mark surfaces where material can be removed at little cost.

The history output STEP_n of the step lists the value of every response (DESIGN_RESPONSE) and the length of its gradient (GRADIENT_LENGTH).

5.16 Creep and the Visco step

Metals at high temperature, plastics and solders keep deforming under a constant load. This creep is modelled with Norton’s law and computed over time in a Visco (creep) step (*VISCO).

5.16.1 Creep law of a material

Creep (Norton) in the material dialog (Section 5.2) adds Norton’s creep law (*CREEP, LAW=NORTON): the equivalent creep strain rate is

with the von Mises stress

and the time

, both in the units of the model (MPa and s in mm, ton, s). The material also needs Elasticity it can be plastic as well.

Only Visco steps let the material creep; a Static step treats it as elastic (and plastic).

5.16.2 Visco step

Create it with Model → Create Step ... and the type Visco (creep). It has the settings of a static step (Section 5.10); the Time period is the creep time, 1000 s by default. The loads of the step are held over that time. Typically a Static step applies the loads first and the Visco step keeps them, so the creep starts from the loaded state.

The new step requests PEEQ in the element field output, which CalculiX writes as the equivalent creep strain PE. The model check (Section 6.4) warns about a Visco step whose materials have no creep law, since it then computes the same as a static step, and reports a creep law without elasticity or with a constant that is not positive.

5.17 Boundary conditions

Boundary conditions belong to a step. Create them with Create ... on BCs of a step, or with Model → Create Boundary Condition ... for the last step. The dialog lists only the types the step accepts. In the 3D view, supports are drawn as cones (translations) and plates (rotations).

The region is a selection of faces, edges or nodes, a node set or a surface. Displacement and temperature boundary conditions can follow an Amplitude (Section 5.8).

5.17.1 Remote displacement

A Remote Displacement prescribes the displacements U1 to U3 and rotations UR1 to UR3 of a point, and the selection follows the point: a shaft end turned by an angle, or a bolt hole held in place while the part turns about it. Unticked components of the point are free. A new one holds all components at zero, which clamps the selection rigidly in place.

The three behaviors match those of Ansys:

• Rigid: the selection keeps its shape and moves with the point as a rigid body. This stiffens the selection, like a pin glued into the bore.
• Deformable: the point moves with the area-weighted mean of the selection, and the selection may deform. Its mean displacement equals that of the point and its mean rotation about the point that of the point, so a bore can ovalize while it is held. This is the distributing coupling (RBE3) of other programs.
• Coupled: every node of the selection shifts like the point in the ticked directions and is free in the others. The point has no rotations here, so UR1 to UR3 are not shown.

You define no reference point, rigid body or equation for it. When the input file is written, PrePoLix adds a reference node and a rotation node at the point. Rigid writes a *RIGID BODY on the selection; Deformable and Coupled write *EQUATIONs between the nodes and the point. The values go on these two nodes, with a *TRANSFORM when a coordinate system is chosen. The point is computed on the current mesh, so a selection of geometry faces keeps working after remeshing. In the 3D view the supports are drawn at the point with lines to the selection.

• In plane stress and plane strain models the point has U1, U2 and UR3 (rotation about z); in axisymmetric models U1 and U2.
• Remote displacements of several steps on the same selection with the same behavior, coordinate system, location and pinball region share one point. The rigid body or the equations belong to the whole model, so they still act in steps without the boundary condition.
• A node can belong to only one rigid body or remote point: do not let the selection overlap that of another remote displacement or a rigid body constraint (Section 5.7). The model check (Section 6.4) reports “Nodes in several rigid bodies or remote points” otherwise.
• Ansys features that CalculiX cannot carry over are left out: the Beam behavior, the augmented Lagrange formulation (PrePoLix always writes exact constraints) and tabular values per component (one amplitude acts on all components).

5.17.2 Motion preview

When a displacement boundary condition follows an amplitude, a play button appears right of the Amplitude field. It previews the prescribed motion in the 3D view: the nodes of the region move by the prescribed displacements times the amplitude, passing through the amplitude’s time range in three seconds and starting again after a short rest. The button turns into a stop button; the preview also ends when the dialog closes or the amplitude is removed. Changes to the values, the amplitude or the region show while it plays.

Only the nodes of the region move; the rest of the mesh stays in place, so the elements next to the region stretch. The motion is exaggerated so that the largest displacement is a quarter of the model size; the dialog shows the current time of the amplitude and this scale. Rotations (UR1 to UR3) are not shown.

5.18 Loads

Loads are created like boundary conditions, with Create ... on Loads of a step or Model → Create Load .... A frequency step takes no loads.

Every load can follow an Amplitude. Film and radiation have a second amplitude for the film coefficient or the emissivity.

In 2D models face loads act on element edges. In axisymmetric models forces act on the full circumference.

5.18.1 What a force acts on

A Force picks its region like a boundary condition: in the Selection window Faces, edges and points takes the face, edge or corner point under the click, and Region can also be a node set, a surface or the Reference Point of a rigid body (Section 5.7). The force is always the total and is distributed to the nodes when the input file is written:

When a selection mixes them, faces come before edges and edges before points: only the faces of a selection of faces and edges carry the force.

5.19 Hiding symbols

Hide in the context menu of a boundary condition or load removes its symbol from the 3D view, Show brings it back; the tree marks a hidden item with an eye. Hide All and Show All in the context menu of BCs or Loads of a step do this for all of them. Constraints are hidden the same way (Section 5.5). A hidden item is still drawn while it is selected, and the setting is saved with the project. Hiding changes only the view; Deactivate leaves an item out of the input file.

5.20 Symmetry boundary condition

A Symmetry boundary condition cuts a symmetric model in half: select the faces that lie in the cut plane and PrePoLix holds them as the mirror image would. You do not have to work out which components of a Displacement/Rotation boundary condition to fix. Create it with Create ... on BCs of a step or Model → Create Boundary Condition ... and choose the type Symmetry.

The boundary condition holds the displacement normal to the plane and, at nodes of beams and shells, the rotations about the two axes in the plane. Solids have no rotations, so for them only the normal displacement counts. The plane is stored as your selection, not as numbers, so it follows the mesh after remeshing.

In the input file, a plane normal to a coordinate axis becomes a plain *BOUNDARY, e.g. for the plane

the components 3, 4 and 5. Any other plane gets a local coordinate system for its nodes (*TRANSFORM, TYPE=R) with the local x axis along the normal, and *BOUNDARY holds the local components 1, 5 and 6.

5.20.1 Warnings

If the selection makes no sense as a symmetry plane, the dialog says so in red, and the model check marks the boundary condition with a warning sign (Section 6.4):

• Not planar: the nodes are not all on one plane, e.g. a curved face or faces of two different planes. The message gives the largest distance from the best-fitting plane. The input file is still written, with that plane.
• No plane: a single node, or nodes on a line that is not a shell edge, do not fix a plane. Enter the normal, or the input file cannot be written.
• Axisymmetric: in an axisymmetric model only a line of constant y (perpendicular to the axis) is a symmetry plane.
• Shared nodes: CalculiX reads every boundary condition and point load at the nodes of a skewed plane in its local system. Zero displacements in all directions, such as a fixed support at an edge of the plane, are the same in any system and give no warning.

5.21 Bolt pre-tension

A Pre-tension (bolt preload) load tightens a bolt: it pulls the two sides of a cut through the shank together with a force, or shortens the bolt by a given length. Create it with Create ... on Loads of a step or Model → Create Load ....

PrePoLix cuts the mesh apart at the selected faces when it writes the input file: every element on their side, also one that only touches the cut with an edge or a corner, gets copies of the nodes on the cut. *Equations tie the copies to the other side the way CalculiX’s *PRE-TENSION SECTION does: the gap normal to the cut is the first degree of freedom of a new node per load, the sides cannot slide against each other. The preload is a *CLOAD with the force or a *BOUNDARY with the shortening on this node. The same load name in a later step reuses the node, so a bolt tightened by a force in the first step can be held at its length in the next step with a displacement of 0, like the usual “preload, then load” sequence of a bolted joint.

A pre-tension load can follow an Amplitude (Section 5.8). The reaction force at the pre-tension node is the bolt force; request it with a history output (Section 7.10) of RF on the load.

5.22 Moving load

A Moving Load drives a group of wheels over a structure: a crane over its runway beam, a trolley over a crane bridge, a vehicle over a bridge deck. CalculiX has no such load, so PrePoLix writes one static step per position, each with the wheel forces at that position. No script is needed. Create it with Create ... on Loads of a static step or Model → Create Load ... and pick the type Moving Load.

Below the table the dialog shows the total force of all wheels. In the 3D view the wheels are drawn at the first and at the last position; here one wheel is off the girder at the start and at the end.

5.22.1 Wheels at the ends of the structure

A wheel whose contact patch is off the selected faces carries no force; one that is partly off carries the part of its force that falls on the faces. So a crane can drive over the runway beam from one end to the other and off it: put Start and End before and behind the beam. For a trolley that stays on its bridge choose them so that every wheel stays on the faces. The model check warns with “Wheel off the surface” when a wheel leaves the faces at some positions; this is a reminder, not an error.

5.22.2 Input file and results

The step is written once per position (** Moving load position 3 of 31, Crane at -500), everything else in the step stays the same in all of them. The wheel forces become *CLOAD on the nodes of the faces under each patch, with the shares of a uniform pressure on the covered part of each face (as for a Force, Section 5.18). The results have one step per position: step through them, or animate them with the animation type Steps (Section 7.6) to see the load travel. The animation keeps one deformation scale for all positions.

5.23 Defined fields

A defined field prescribes the temperature of the model in a mechanical step, for thermal expansion or temperature-dependent materials. Create it with Create ... on Defined Fields of a step or Model → Create Defined Field .... Heat transfer, coupled and uncoupled steps solve for the temperatures and take no defined fields.

Written as *TEMPERATURE with the node set and the value, or as *TEMPERATURE, FILE=...,
BSTEP=.... When the analysis starts, a result file is copied next to the input file, where CalculiX looks for it; the monitor lists the copied files.

A model with a defined field needs an Initial Condition of type Temperature (Section 5.9), otherwise CalculiX refuses the *TEMPERATURE keyword; the model check (Section 6.4) reports a missing one. The temperatures act through the Thermal expansion of the materials (Section 5.2) with their reference temperature.

5.24 Keyword editor

Model → Edit CalculiX Keywords ... shows the input file PrePoLix writes, as a tree of keywords on the left and as text on the right. Here you add CalculiX keywords for features the dialogs do not offer yet.

• Select a place in the tree and press Add to insert a user keyword there. Type the keyword and its data lines under Edit Selected Keyword.
• Move Up and Move Down move a user keyword, Delete removes it.
• Active switches a user keyword off without deleting it; it is then written as a comment.
• Generated keywords are read-only. Hide data (faster) shortens long data blocks in the preview.

Each step has empty places such as Controls, Output frequency and Defined fields for keywords like *CONTROLS, *OUTPUT or *TEMPERATURE.

User keywords are saved in the project and written every time the input file is written (run, model check, export). If the model changes so that a keyword has no valid place any more, PrePoLix warns that it will not be written.

A user keyword inside a step belongs to that step. When an analysis continues another one (Section 3.2.3), the keywords of the model definition and of the steps it took come from the source: edit them there, since the source’s replace them in the continuation once links bring it up to date. Its own steps keep their own keywords. Split After and Merge into move the keywords of the moved steps along with them (Section 3.2.4).

6 Running CalculiX

6.1 Solving an analysis

Each analysis of the project is solved in its window. CalculiX uses the settings under Tools → Settings ... → CalculiX (Section 3.12) and runs in the folder <work directory>/<project name>/<analysis name>, so the analyses of a project never overwrite each other’s files.

Solve, Stop and Monitor are also in the toolbar, next to the state of the solution; all commands are in the Analysis menu. Which cells are out of date is decided as in the project schematic (Section 3.1): changing a load makes only the solution out of date, changing the meshing settings of a part makes its mesh out of date, and result paths or planes change nothing that CalculiX needs.

The input file is named after the analysis, for example Cantilever.inp. Old result files of the analysis in its folder are deleted before CalculiX starts. PrePoLix refuses to run a model without mesh, without step or with all steps deactivated, and it stops if the input file cannot be written (for example because a region is empty).

6.1.1 Monitor

The monitor is the Analysis tab of the output pane below the 3D view; it comes to the front when a run starts, so the model and its results stay in view while CalculiX runs. Its top row has Kill to stop CalculiX, Results to open the results once the run is finished, the Filter field and the status with the running time and the current step, increment and iteration; below it is the output of CalculiX. The Output tab goes back to the messages, and the pane can be made taller by dragging its upper edge.

The Filter field shows only the lines that contain the text you type, ignoring upper and lower case. With “average force”, for example, you see the average force of every increment one below the other. The filter applies while CalculiX is still running, and Clear or an empty field shows all lines again.

The status at the end is completed, finished with errors, results available, failed or killed. If CalculiX failed, PrePoLix looks for known error messages in the output and adds a line “Possible cause: …” with a remedy, for example for distorted elements, missing material data, rigid body motion or missing convergence.

6.2 Solving again from the last unchanged step

CalculiX can write the state of the model after each step over time (static, dynamic, heat transfer, coupled and uncoupled temperature-displacement, visco) into a restart file, and PrePoLix asks it to (*RESTART, WRITE in every such step). When you change a later step of an analysis and solve again, CalculiX does not start from the beginning: it reads the state after the last unchanged step from the earlier run and solves only the rest. The monitor tells which of the two happened:

A restart that CalculiX cannot finish is solved once more in full, so a changed analysis always ends up solved. The state files stay in the folder of the analysis in the work directory, next to its results; they are not saved in the project file, and after a move to another computer the first run is a full one.

Under Tools → Settings ... → CalculiX (Section 3.12), Keep the state after each step turns the restart files off, and Restart files per project limits the disk space they take (4096 MB by default): beyond it, the oldest state files of the project are removed, which only costs time, never correctness.

The same mechanism lets one analysis continue another one after a step, through a state link in the project schematic (Section 3.2.3).

6.3 Results kept with the project

When a run is finished, its analysis keeps the results: the input file, the result file (.frd) and the history output (.dat) of the run are saved in the project file with the next File → Save Project, together with a fingerprint of what the run was made from. The results open on the Results tab. The output pane shows how much the files add to the project file; they are stored compressed, at about a third of their size (a 236 MB result file adds about 100 MB). Keeping a large result takes a few seconds and runs in the background. A new run replaces the results the analysis keeps.

When an analysis with kept results is opened, PrePoLix writes the files to Kept_Results in the folder of the analysis and opens the results on the Results tab. The project schematic and the toolbar of the analysis window show whether they are still up to date.

What you defined on the kept results is saved with them and comes back as you left it: derived field and history outputs, transformations, hot spots, the reference points, coordinate systems and planes of the results, result paths and plane results, and the increment, field and component shown. The view comes back too: the camera of the Results tab, View → Mesh Edges, the deformation and its factor, Show Undeformed, the color levels, hidden parts, the annotations of the query tool and the plots of result paths. PrePoLix takes all of this from the open result each time the project is saved.

When the analysis runs again, its new results take over all of this from the results before, so the view, transformations, paths and plots stay as they were. Annotations of the query tool and hot spots on picked nodes or faces refer to nodes and elements of the mesh; they are kept only if the mesh did not change. After remeshing they are dropped, reference points placed on picked nodes or faces stay at their last position, and the output pane lists what was dropped.

Analysis → Remove Results drops the kept results; save the project to remove them from the file.

To send only the meshes and the model definitions, use File → Save Project Without Results .... It saves a copy without the kept results under a new name (proposed as <project name>-without-results.plx); the open project stays on its own file and keeps its results.

6.4 Model check

PrePoLix checks the model continuously while you work. Items with a problem get a warning sign in the tree; items with an error and their containers are shown in red. Click the warning sign to see what is wrong and how to fix it.

Errors include elements without material, materials without the data the step needs (elasticity, density, conductivity, specific heat), invalid material constants, distorted elements, a missing initial temperature in a transient heat transfer step, an increment larger than the step, rigid body motion of a part in a static step, truss structures that are mechanisms, radiation without the physical constants (Section 5.1) and missing references (a deleted material, part or set that an item still uses). Warnings include parts held only by contact, conflicting boundary conditions, loads on fixed nodes, rotations without effect and steps without load.

When a run starts, PrePoLix also checks that the configured CalculiX knows every keyword of the input file (see Test CalculiX in Section 3.12). An unknown keyword, for example of a step type that an older CalculiX lacks, appears as error “Keyword unknown to CalculiX” on the analysis and in the monitor, with the feature that needs it.

When CalculiX aborts, PrePoLix explains the error messages it knows in the same way, for example “RADIATE card was selected but noPHYSICAL CONSTANTS card encountered” as “Physical constants missing”; other messages appear as “CalculiX error” with the text of the monitor.

The checks do not stop a run; their errors are listed at the top of the monitor. Missing references do stop it, because the input file cannot be written.

6.5 Exporting the input file

File → Export CalculiX Input File ... writes the same input file as a run, for example to run CalculiX by hand or on another computer. Deactivated items appear as comments.

6.6 Submodels

A submodel computes a detail of a larger model more precisely. Its cut boundaries follow the displacements of the global model. Global model and submodel are two analyses of the project, linked in the schematic (Section 3.2.2):

1. Set up the global model in one analysis and the submodel, with its own finer mesh, in another.
2. In the submodel, create a boundary condition of type Submodel on the cut faces in a static step, and choose the displacement components.
3. Set Model Type to Submodel in the submodel’s Model Properties. Its block in the project schematic gets a Global results row below State, with an orange input pin and a question mark while nothing is linked.

4. Drag the results of the global step (the row of the step below Results of the global analysis) to Global results. The output pane confirms “takes the displacements of Step-1 of Global in Step-1 (submodel)”, and the row names the global analysis. The step with submodel boundary conditions takes them, or the first step; the link also sets the global step of the boundary condition. Each step can take the results of another global step at its own Global results input under Setup > Steps. Dropping results there makes an analysis a submodel too. Global results computed elsewhere come from a file block (Section 3.3.4) that reads their .frd file; its steps link the same way.

   

5. Solve the submodel or Update Project: the global model is solved first if it has no results yet. PrePoLix copies the global results next to the input file and writes *SUBMODEL and *BOUNDARY, SUBMODEL.

In the Results tab of the submodel, Show Global Contours in the results tool bar, next to Show Undeformed, draws the edges of the global model around the results, read from the global results the submodel took: at the global increment the submodel follows and deformed by the same scale. They show where the submodel sits in the global model and how the two deform; the global model is neither a part in the tree nor coloured, and the legend leaves its values out. The switch shows only for a submodel whose global results file is there.

Removing the link leaves the analysis a submodel whose Global results row waits for a new one. Model Properties makes it a general model again.

6.7 Exporting a deformed mesh

File → Export Deformed Mesh (.inp) ... writes the mesh of the displayed result with its nodes moved by the displacements times the current deformation scale factor. A typical use is an imperfection for a buckling analysis: show the buckling mode, set Deformation to User defined with the imperfection amplitude as factor, export, and import the file into the model with Import Geometry (Section 4.1.1). The file contains only the mesh.

7 Results

7.1 Opening results

The Results tab shows the results of its analysis: they open when a run is finished, with Results in the monitor, with Analysis → Open Results and when an analysis with kept results is opened (Section 6.3). The .dat file of the run is read as well. Result files from elsewhere are not opened.

When results are opened, PrePoLix shows the Results tab with the last increment.

7.2 Results tree

Model

the mesh of the results with its parts and sets, and the features (reference points, coordinate systems, planes) used for result evaluation.

Field Outputs

the fields of the result file with their components. Click a component to show it. Names follow the CalculiX result file (U1, S11, …). PrePoLix adds the displacement magnitude ALL, MISES, TRESCA, the principal stresses and the signed maximum absolute principal stress.

History Outputs

values from the .dat file and history outputs you create (Section 7.10).

Hot Spot Stresses, Paths, Plane Results

evaluations described in the following sections.

Results list the parts of the model they were computed from, as in the FE Model tab, also when several parts share a section. A .frd file itself only groups the elements by material; PrePoLix reads the parts from the input file CalculiX ran, the .inp file of the same name next to the results. Results of an analysis run from PrePoLix always have it.

7.3 Results toolbar

7.4 Contour plot, legend and labels

The legend shows the field, the unit and the range in nine colour bands from blue (minimum) to red (maximum) by default. The info block in the upper right shows file, date, step, increment or mode with its frequency or buckling factor, and the deformation scale factor. Labels mark the node with the maximum (and optionally the minimum) value. Legend, info block and labels can be dragged. Which of them appear is set under Tools → Settings ... → Post-processing.

7.5 Color scale

Each result file has its own colour scale. Double-click the legend, choose Color Scale... in its context menu, click ... next to Color levels on the results toolbar, or use Results → Color Scale .... Changes show at once; Cancel restores the scale the dialog was opened with and Defaults returns to the rainbow with automatic limits.

The last line of the legend title says Automatic or Manual. When the results are kept with the project (Section 6.3), its colour scale is saved in the project file and restored with it; a result file that is read again, for example after another run, keeps its scale.

7.5.1 Parts without colour contours

A stiff or irrelevant part can dominate the colour scale. Right-click a part under Model in the results tree, or in the 3D view, and choose Color Contours Off. The part turns plain grey and no longer counts for the legend range, the minimum and maximum labels or the animation limits; the colours of the other parts then use the full scale. Color Contours On brings the contours back. With several parts selected, the command applies to all of them. Results kept with the project (Section 6.3) remember which parts have contours off. Nodes that a grey part shares with a part that still has contours keep their colour.

Increment 0 of a buckle step is the reference state; the modes follow as increments 1, 2, …

7.6 Animation

The animation button on the results toolbar opens the animation window.

The buttons step through the frames or play them; the slider selects a frame. Closing the window shows the increment that was shown at the start, or the one you selected meanwhile.

The window can stay open while you change the increment: the Step, Increment list and the First, Previous, Next and Last Increment buttons of the results toolbar keep working. The animation continues with the new increment (or the increments of its step) and keeps its settings, so you can page through modes or steps without reopening the window.

7.6.1 Exporting the animation

The export button (disk symbol) at the right of the player row saves the animation as a file, with the choices GIF …, MP4 … and MKV ….

PrePoLix then plays the animation once frame by frame and records the 3D view as it is shown, with legend, labels and status block, at the size of the view on screen. The animation window is hidden meanwhile; the status bar counts the frames and Esc cancels. The file follows the settings of the window:

• Frames and Frames per second give the number of frames and the playing speed.
• Once and Loop record every frame once, Swing records there and back, so a player that repeats the file swings smoothly. A GIF repeats endlessly unless the playback is Once videos are played as the video player is set.
• Color scale is recorded as set: with Current frame the legend changes from frame to frame.

GIF needs nothing else; its frame times are counted in hundredths of a second, so above 50 frames per second it plays slower. MP4 and MKV are written by FFmpeg, which has to be installed: PrePoLix looks for ffmpeg on the PATH, or uses the executable set under Tools → Settings … > Post-processing > FFmpeg executable. The video is H.264 (or FFmpeg’s default codec if it lacks H.264); its width and height are rounded down to even numbers. The output pane reports the saved file or what went wrong.

7.7 Sound of the mode shapes

For a frequency step, the sound button opens Sound of the Mode Shapes. It plays the eigenfrequencies as tones, so you can hear how the structure would ring.

• Tick the modes to hear them together; Level sets the volume of each mode. A click on a mode number shows this mode swinging in the 3D view.
• Make audible: Automatic shifts all frequencies by whole octaves into the audible range, keeping their intervals. Octaves applies a fixed shift, Original none.
• Sound: Sustained tones, or Struck tones that decay like a bell, higher modes faster (Decay time).
• Show superposed while playing overlays the ticked modes in the 3D view, each swinging at its own frequency ratio, with Speed for the lowest mode.
• Save as WAV... writes the sound to a file.

7.8 Transformations

The transformation button on the results toolbar shows the results of a symmetric or periodic model as the full structure. Transformations only change the display.

Move a type from Available to Active and set its properties:

Symmetry X/Y/Z

mirrors the model at the plane normal to the axis through the Symmetry point.

Linear pattern

copies the model Number of items times along the line from the start to the end point.

Circular pattern

copies the model Number of items times by Angle about the axis through two points.

Several transformations are applied one after the other. Vector and tensor results are mirrored or rotated with the copies, and legend and labels include them. Clear removes all transformations.

7.9 Derived field outputs

Create ... on Field Outputs computes new fields from the results.

7.10 History outputs and tables

History Outputs on the Results tab lists the history outputs from the .dat file (for example the eigenfrequencies of a frequency step) and the ones you create with Create ...:

From Field Output

values of a field at selected nodes, one row per increment.

From History Output by Equation

a formula of other history outputs.

From Element Size

volume of elements or area of faces in every increment.

From Hot Spot

the values of a hot spot (Section 7.13) in every increment, optionally beside the position of a moving load (Section 7.13.1).

A double-click on a component opens its table. Click column headers to select them (Ctrl adds, Shift selects a range) or drag over cells. Copy (Ctrl+C) copies the selection as tab-separated text, Plot (Ctrl+P) draws the selected columns over the first one.

Export in the plot window copies the plot to the clipboard as an image (Copy to Clipboard) or saves it as a PNG or SVG file. The SVG file is vector graphics with the curves, grid and legend, for reports in good print quality.

Show in View in the plot window puts the plot into the 3D view as an annotation, like a path plot (see Section 7.11): it stays after the window is closed and appears in screenshots. Drag the box to move it and its bottom right corner to resize it. Edit... in its context menu, or a double-click, opens Edit Annotation for the title, the axis labels and a fixed value range; Delete, or Remove from View in the plot window, removes it. The plot keeps the values it was made from; with results kept with the project (Section 6.3) it is saved with them.

7.11 Paths

Create ... on Paths shows the displayed component along a straight line.

The dialog shows minimum, maximum and a plot of the value over the distance. Copy to Clipboard and Save as CSV... export the values; Table lists them. Points outside the mesh have no value. The dialog’s height can be changed by dragging its bottom right corner; the plot takes the extra height.

Show in View puts the plot into the 3D view as an annotation, where it stays after the dialog is closed and appears in screenshots. It shows the displayed component of the current increment and follows when another one is selected. Drag the box to move it and its bottom right corner to resize it; Delete in its context menu, or Remove from View in the dialog, removes it.

Show on Path in the context menu draws the plot onto the path itself instead: the path is the distance axis, the values stand off it perpendicular on the screen over a translucent area, with the largest and smallest value labelled. Drag the curve away from the path or towards it to change its height. Drag it across the path and the height becomes negative: the plot flips to the other side of the path. Show in Box puts it back into its box.

Edit... in the context menu, or a double-click on the plot, opens Edit Annotation. Changes show at once; Cancel restores the plot.

7.12 Plane results

Create ... on Plane Results evaluates the displayed component on a plane defined under Features: minimum and maximum with their position, the area-weighted mean, and the cut area. With its check box ticked, the 3D view shows only the cut, and the legend uses the values on it.

7.13 Hot spot stresses

Hot spot stresses evaluate welded joints as recommended by the IIW: the stress at the weld toe is extrapolated from read-out points on the plate surface. Double-click Hot Spot Stresses in the Results tree, or use Results → Create Hot Spot ..., and pick the weld toe.

Below the inputs the dialog shows the result for the displayed increment while you edit: the hot spot stress S_hs with its node, the stresses at the read-out points and a plot of the stress along the path from the toe to a quarter beyond the last read-out point. The read-out points and the hot spot stress are blue dots, the extrapolation through them is dashed, so you can check at a glance whether the read-out points lie on the smooth part of the stress rise. The value axis leaves out a sharp notch peak right at the toe, which would otherwise flatten the plot; hover the curve to read values. Copy to Clipboard and Save as CSV... export the curve, the read-out points and the hot spot stress.

Show in View puts the plot into the 3D view as an annotation that stays after the dialog is closed and follows the displayed increment, like the plot of a path (Section 7.11): drag it to move it, drag its corner to resize it. Its context menu offers Edit..., Show on Path, which draws the curve, the read-out points and the extrapolation onto the path in the model, and Delete.

The evaluation runs for all increments and writes <result>_hot_spots.csv next to the result file, with one row per toe node and increment; the output pane lists the highest value of each hot spot. A hot spot is deleted with the Del key or Delete in its context menu.

7.13.1 Hot spot stress over all steps

Create History Output with the type From Hot Spot writes the values of a hot spot into a history output, one row per increment, so the hot spot stress can be followed through all steps, for example while a crane drives over a girder with a moving load (Section 5.22).

The history output has the field HOT_SPOT with one component per toe node, NODE_<id>. Its table holds all values of the node side by side: the position of the moving load (POSITION, if one is chosen), the hot spot stress S_HS and the stresses at the read-out points S_1, S_2, … (nearest first). A hot spot on an edge with several toe nodes also gets the component MAX with the largest hot spot stress of all toe nodes in each increment and its NODE. Increments without stresses have no values.

To plot the stress over the position, double-click the component, select the column POSITION and then S_HS (Ctrl-click), and choose Plot (Ctrl+P).

The history output follows its hot spot: when the hot spot is changed, it is computed again; when the hot spot is deleted or renamed, or the moving load is no longer in an active step of the FE model, it reports an error in the output pane and has no data until it is edited.

7.14 Query

Tools → Query ... or the Query button of the toolbar (the pipette) reads values from the model by clicking: Vertex/Node, Facet/Element, Edge (length), Surface (area), Part, Assembly, Bounding box size, Distance (two nodes), Angle (three nodes) and Circle (centre and radius through three nodes). The values appear in the output pane and as labels in the 3D view. On results, node queries also show the deformed position, the displacement and the value of the displayed component.

The labels stay in the view when the query window is closed and can be dragged aside. A right click on a label offers Delete for this label and Delete All Annotations Remove Annotations in the query window, in the Tools menu and on the toolbar deletes all of them. Each model keeps its own labels: the geometry, the FE model and every result file. Meshing again removes those of the FE model, since they refer to node and element ids.

Edge and Surface pick like the geometry based selection (Section 3.10): an edge runs from corner to corner, on the Geometry tab and on meshes generated from CAD geometry it is the CAD edge; a surface is the CAD face or the smooth patch bounded by feature edges. Hovering shows what a click would pick. On results the output pane also has the deformed length or area and the change.

7.15 Campbell diagram

A Campbell diagram shows the eigenfrequencies of a rotor over its speed of rotation. CalculiX computes the whirling modes for one speed per run, so PrePoLix runs the analysis once per speed and collects the results.

The sweep lives in a Campbell block of the project schematic (Section 3.1), which takes the analysis to sweep and keeps the diagram. The analysis needs an active Centrifugal load, whose axis and point tell how the rotor turns, and a Complex Frequency step (Section 5.12); the speed of the load does not matter, 0 included, as the sweep sets it. Analysis → Campbell diagram ... in the window of such an analysis opens its Campbell block, and makes one next to the analysis and links it first if there is none. A block can also be added from the block picker or the context menu of the schematic (category Campbell); then drag the Setup pin of the analysis to the Analysis row of the block.

The block shows the state of its diagram in its Analysis row, how many speeds it has and up to five critical speeds. The speeds and the settings of the sweep are saved in the project file, so the diagram is there again when the project is opened. The diagram stays up to date while the analysis is unchanged, apart from the speed of its centrifugal loads; once the mesh or the model of the analysis changes, the block turns out of date. Update Project starts the sweep of every Campbell block that is out of date or has not swept yet, beside the solves of the analyses; the sweep runs the model of its analysis by itself and needs no results of it.

Double-clicking the block, or Open Diagram ... in its context menu, opens the window with the settings of the sweep and the diagram. The sweep does not run the analysis itself and adds nothing to its results. The diagram appears as soon as two speeds are done. The window can be closed while the sweep runs: the block goes on and shows its progress.

Start sweep sets the centrifugal loads of the model to every speed, runs CalculiX in a folder named after the block in that of the project in the work directory (Section 3.12) and reads the complex frequencies of the last Complex Frequency step and the whirl direction of every mode from the .dat file. When the .dat file of a CalculiX version has no readable complex frequencies, they come from the .frd file, without whirl directions. As many speeds run at the same time as Parallel analyses of the solver settings allows. The files of a speed are deleted once its frequencies are read; those of a failed speed stay for a look.

The sweep needs no step size. It starts with eight speeds spread evenly over the range and then keeps adding speeds where the curves bend most: between the two speeds whose curves deviate most from a straight line, weighted with the width of the gap, so that a resolved curve lets the speeds spread over the rest of the range. The diagram grows with every speed. The sweep ends at Maximum runs, at Stop, which cancels the running speeds and keeps the finished ones, or when no gap is wider than a five-hundredth of the range. Pause lets the running speeds finish and starts no new ones; Continue goes on from there. Continue also goes on with a finished or stopped sweep: another Maximum runs runs that refine between its speeds, as long as the model has not changed since; after a change, Start sweep begins anew.

To look closer at part of the diagram, hold Shift and drag across it: the marked speed range is shaded and named Refine range, and new speeds go only there, down to a five-hundredth of the marked range. Mark a range while the sweep runs or is paused, or after it finished, and press Continue the sweep again picks the speeds where the curves bend most within the range. Clear range under the diagram lets new speeds go anywhere again. Gaps next to a speed CalculiX could not solve are not refined further. The progress and the messages of the runs appear below the diagram. When fewer than two speeds give complex frequencies, the window says so in place of the diagram; the messages below name the CalculiX error of each failed speed.

The diagram has one curve per mode and one dashed grey line per engine order, which starts at 0 rpm even though the sweep leaves out standstill. The modes are followed from speed to speed by their course, not by their rank among the frequencies: a mode joins the curve it continues best, so curves that cross keep their colour, and a curve that falls to zero and rises again (in the rotating frame of reference, the forward whirl at its critical speed) stays one curve. Roots CalculiX finds at fewer than three neighbouring speeds, such as a spurious root near 0 Hz, are drawn as grey crosses named Unmatched roots instead of tearing the curves; growing modes, whose eigenvalue has an imaginary part of weight, are drawn as red diamonds named Unstable. A mode that whirls the same way at every speed carries its direction in the legend, F (forward) or B (backward) as CalculiX reports it.

The diagram can be moved and zoomed like the plots of egui: drag it to pan, scroll to zoom, drag along an axis to zoom only that axis, and double-click to fit the view to the curves again. A click on a legend entry hides or shows that mode or order line. Hovering a point shows its curve, speed and frequency.

Where a mode crosses an order line, the rotor is excited at one of its eigenfrequencies: these crossings are listed under Critical speeds with the order, the mode, its whirl, the speed in rpm and the frequency. Copy table copies the frequencies of all modes at all speeds as tab-separated text. Export CSV ... saves the same table as a CSV file, with a Save As dialog: one row per speed with the speed in rad/s and rpm, the frequency in Hz and the whirl (F, B or empty) of every curve, the other roots CalculiX found at that speed (unmatched and unstable, separated by spaces), and the frequency of every order line. Numbers use a decimal point and the cells are separated by commas.

7.16 Exporting results to ParaView

File → Export VTU ... and File → Export VTK ... write the current results for ParaView and other programs built on VTK. Both are enabled when results are open; they export the result selected in the Results workspace.

Export ... asks for the file name. Each file holds the undeformed mesh and, as point data, every field of the increment: the components CalculiX wrote form one array per field (DISP as a vector, STRESS and TOSTRAIN as symmetric tensors in VTK’s component order XX, YY, ZZ, XY, YZ, XZ), and computed components such as MISES or the principal values are scalar arrays named STRESS_MISES and so on. Field outputs defined under Results are included. NodeId, ElementId and PartId give the CalculiX node and element numbers and the part of each element; a VTU file also lists the part names in its field data (PartNames). Each file also stores STEP, INCREMENT and the increment’s time, frequency or load factor as field data.

To see the deformation in ParaView, apply Warp By Vector with DISP.

7.16.1 VTU or VTK

VTU

VTK’s XML format (.vtu). Use it for ParaView; it is compressed, stores names of the components and of the parts, and every VTK program of the last years reads it.

VTK

the legacy VTK format (.vtk, version 4.2) for older or simpler tools that do not read XML files.

7.16.2 Several increments as a time series

Several increments become one file per increment and a collection file that ParaView opens as a time series, the way the ParaView documentation recommends for transient data:

• VTU: a ParaView Data file name.pvd and the files name/name_0000.vtu, name/name_0001.vtu, … in a folder name next to it.
• VTK: a file series name.vtk.series (a small JSON file, read by ParaView 5.5 and later) and the files name/name_0000.vtk, … The PVD format only holds XML files, so legacy files use this file series instead.

Open the .pvd or .vtk.series file, not the single files, and step through the increments with ParaView’s time controls. The collection gives every file its time: the increments’ own values (time, eigenfrequency or load factor) if they increase from file to file, as within one static or dynamic step. Otherwise, for example when several steps start their time again or mix a static and a frequency step, the files are numbered 0, 1, 2, … in their order in the results file, and the output pane says so. The real values stay in the field data of each file. Keep the collection file and its folder together when moving them.