Skip to content

Add documentation for volumetric coupling with the CalculiX adapter #530

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: master
Choose a base branch
from
Open

Add documentation for volumetric coupling with the CalculiX adapter #530

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
506793a
Add multiscale mechanics volumetric coupling documentation to Calculi…
IshaanDesai Jun 16, 2025
ad1c409
Merge branch 'master' into ccx-vc-mech
IshaanDesai Oct 8, 2025
01168d8
Merge branch 'master' into ccx-vc-mech
IshaanDesai Oct 8, 2025
44605ad
Rework CCX adapter volumetric coupling content
IshaanDesai Oct 9, 2025
fe161fe
Merge branch 'ccx-vc-mech' of github.com:precice/precice.github.io in…
IshaanDesai Oct 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 25 additions & 6 deletions content/docs/adapters/calculix/adapter-calculix-configure.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,13 @@ precice-config-file: ../precice-config.xml
The adapter allows us to use several participants in one simulation (e.g., several instances of Calculix if several solid objects are taken into account). The name of the participant `Calculix` must match the specification of the participant on the command line when running the executable of `CCX` with the adapter being used (this is described later). Also, the name must be the same as the one used in the preCICE configuration file `precice-config.xml`.

One participant may have several coupling interfaces. Note that each interface specification starts with a dash.
Depending on the data you need to read and write, the interface should define either a `faces-mesh` (or `mesh` as a synonym) where the data points are centers of faces (computed by the adapter) or a mesh made of CalculiX vertices, with the keyword `nodes-mesh`. An interface made of faces should be defined in the CalculiX case using the `*SURFACE` command, whereas meshes with nodes should define these nodes using `*NSET`. Using the wrong family of mesh (e.g. reading forces on faces) throws an error. If you need both kinds of meshes, you should define more than one interface.
Depending on the data you need to read and write, the interface should define a mesh of the following types

* a `faces-mesh` (or `mesh` as a synonym) where the data points are centers of faces (computed by the adapter). An interface made of faces should be defined in the CalculiX case using the `*SURFACE` command.
* a `nodes-mesh` where the data points are the nodal vertices. An interface made of nodes should define these nodes using `*NSET`.
* a `elements-mesh` where the data points are the quadrature points of the elements of a mesh. The mesh should be defined by nodes using `*NEST`. This mesh type is intended for volumetric coupling, when quantities defined on quadrature points of all the elements are coupled.

Using the wrong family of mesh (e.g. reading forces on faces) throws an error. If you need both kinds of meshes, you should define more than one interface.

For FSI simulations the mesh type of an interface is always `nodes-mesh`, as forces and displacement are defined on nodes. The name of this mesh, `Calculix_Mesh`, must match the mesh name given in the preCICE configuration file. In CHT simulations, `faces-meshes` are usually chosen, as they are needed to apply heat fluxes or convective heat transfer.
For defining which nodes of the CalculiX domain belong to the FSI interface, a node set needs to be defined in the CalculiX input files. The name of this node set must match the name of the patch (here: "interface").
Expand All @@ -45,6 +51,12 @@ On nodes-mesh:
* Displacements (Use `*BOUNDARY`)
* Temperature (Use `*BOUNDARY`)

On elements-mesh:

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A note on the motivation for splitting the tensors into multiple data fields would be useful (related to precice/precice#2085). I guess this also comes with some limitations: how does IQN work with such data?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have removed the data that can be read and written on a elements-mesh because this PR should be solely about volumetric coupling and not about multiscale mechanics. I will add the documentation associated to multiscale mechanics in a separate PR.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean that we can define such an elements-mesh but we cannot currently read/write anything on it? We should then give more context on why that is, what we aim for, and how this still might be useful to someone at this state.

Copy link
Member Author

@IshaanDesai IshaanDesai Oct 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this mean that we can define such an elements-mesh but we cannot currently read/write anything on it?

We can attempt to read and write and of the data that we current support in the adapter. But not all data exists on a quadrature point of an element. Hence the use of elements-mesh is a bit open-ended. With precice/calculix-adapter#135 we are able to read strains and write stresses and stiffness values to CalculiX.

We should then give more context on why that is, what we aim for, and how this still might be useful to someone at this state.

I would explain it in the following way:

  1. We do not officially support data on the elements-mesh because we do not have test cases with relevant physical scenarios.
  2. Currently we aim to support read strains, and writing stresses and stiffness, because we have a multiscale mechanics application case at hand.
  3. The elements-mesh is useful to someone who wants to play with volumetric coupling with CalculiX. A user can look at this like an experimental feature which we are still testing.

Are these explanations satisfactory?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

because we do not have test cases with relevant physical scenarios.

this sounds independent: we might not have a test case but still support. The interest here is what the adapter can actually do at the moment, even if experimental/not officially supported.

I guess not even stresses will work at the moment without #135, since you do all this additional work there. Would temperatures work? This is also the main target for some users. Heat fluxes (in some form)?

The rest sounds good.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this sounds independent: we might not have a test case but still support. The interest here is what the adapter can actually do at the moment, even if experimental/not officially supported.

Good point.

I guess not even stresses will work at the moment without #135, since you do all this additional work there.

Correct.

Would temperatures work? This is also the main target for some users. Heat fluxes (in some form)?

Temperatures and heat sources (not fluxes) should work with elements-mesh. We would have to of course test things, but by design it should work.

{% warning %}
Data that can be read on a elements-mesh is yet to be added.
{% endwarning %}

Have a look at the CalculiX documentation for a detailed description of each of these commands. There is an [online (but outdated) version](https://web.mit.edu/calculix_v2.7/CalculiX/ccx_2.7/doc/ccx/node1.html) and an [up-to-date PDF version](http://www.dhondt.de/ccx_2.19.pdf).

Valid `writeData` keywords are:
Expand All @@ -62,13 +74,14 @@ On nodes-mesh:
* Displacements
* DisplacementDeltas
* Temperature

From CalculiX version 2.15, additional `writeData` keywords are available:

```text
* Positions
* Velocities
```

On elements-mesh:

{% warning %}
Data that can be written on a elements-mesh is yet to be added.
{% endwarning %}

Note that the square brackets imply that several read- and write-data types can be used on a single interface. This is not needed for FSI simulations (but for CHT simulations). Lastly, the `precice-config-file` needs to be identified including its location. In this example, the file is called `precice-config.xml` and is located one directory above the folder, in which the YAML configuration file lies.

Expand Down Expand Up @@ -144,6 +157,8 @@ The preCICE CalculiX adapter should support most elements when using `nodes-mesh

When using face meshes, only tetrahedra and hexaedra are supported.

When using `elements-mesh` for volumetric coupling, linear tetrahedral (C3D4) and hexahedral (C3D8) elements are supported. The adapter loops over all the elements and extracts the coordinates of the quadrature points. These coordinates are then used as coupling vertex coordinates.

### Coupling to 2D simulations

The adapter supports quasi 2D simulations when the z-direction is ignored. If you set the preCICE interface dimension to 2, the adapter will map data from the CalculiX 3D simulation to 2D space and vice-versa. The 3D simulation should be made of solid elements (or shells) of unit thickness.
Expand All @@ -156,6 +171,10 @@ When writing continuous fields (such as temperature and displacements), the adap

When using `faces-mesh`, the behavior in unchanged and the z-component is discarded.

#### Behavior with `elements-mesh`

2D scenarios with volumetric coupling are untested and hence not recommended.

### Nearest-projection mapping

In order to use nearest-projection mapping, a few additional changes are required. The first is that the interface surface file (`.sur`) must be added to the CalculiX input file. An example of the addition to the input file is given below
Expand Down
2 changes: 1 addition & 1 deletion content/docs/adapters/calculix/adapter-calculix-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ The latest supported CalculiX version is {{site.calculix_version}}. If you alrea

## History

The adapter was initially developed for conjugate heat transfer (CHT) simulations via preCICE by Lucia Cheung in the scope of her master’s thesis [[1]](https://www5.in.tum.de/pub/Cheung2016_Thesis.pdf) in cooperation with [SimScale](https://www.simscale.com/). For running the adapter for CHT simulations refer to this thesis. The adapter was extended to fluid-structure interaction by Alexander Rusch [[2]](https://www.gacm2017.uni-stuttgart.de/registration/Upload/ExtendedAbstracts/ExtendedAbstract_0138.pdf).
The adapter was initially developed for conjugate heat transfer (CHT) simulations via preCICE by Lucia Cheung in the scope of her master’s thesis [[1]](https://www5.in.tum.de/pub/Cheung2016_Thesis.pdf) in cooperation with [SimScale](https://www.simscale.com/). For running the adapter for CHT simulations refer to this thesis. The adapter was extended to fluid-structure interaction by Alexander Rusch [[2]](https://www.gacm2017.uni-stuttgart.de/registration/Upload/ExtendedAbstracts/ExtendedAbstract_0138.pdf). The adapter was further extended for volumetric coupling by Ibrahim Kaleel and Ishaan Desai.

## References

Expand Down