Intact CLI 1.0.5 User’s Manual¶

Introduction¶

The Intact command line tool allows users to run a variety of physics simulations over assemblies of different geometry types. These simulations are configured with a json file. We generally refer to one of these simulations as a scenario. Code examples that are meant to be run in a shell are prefixed with $. For example

$ intact --help

will produce output that looks like:

$ intact --help
A command line interface for Intact
For more information, the user manual can be found at:
https://intact-solutions.com/intact_docs/
Usage:
  Intact [OPTION...]

  -h, --help                    Print program usage
      --build-info              Print report about current build, then exit
      --version                 Print the software version
  -s, --scenario arg            Scenario json file
  -f, --fields arg              Fields to sample (if empty, all available 
                                fields will be sampled). Comma delimited.
  -o, --output arg              Output directory. The default it the 
                                directory of the scenario file.
      --skip-sample             Skip the sampling step of the solver.
      --json-output             Output the sampled results in JSON format 
                                (VTK is the default output).
      --tempdir                 Make a temporary directory for output
      --scenario-name arg       Prefix for output files, defaults to 
                                scenario file name
      --load-solution-file      Load a cached solution file/s
      --logdir arg              Path to the log file. Default value is 
                                current working directory.
      --logname arg              If not specified, log will not be put in a 
                                file
      --save-solution           Save the scenario solution in vtk format
      --refinement-level arg    Refinement ratio w.r.t. assembly bounding 
                                box. If not present, no refinement is 
                                performed.
  -v, --verbosity arg           Verbosity level, run with --help for more 
                                information
      --define-version          Software version

Aside from the syntax for paths, this documentation applies to builds of the intact tool on all operating systems. All officially supported features are documented here, though the build provided may have additional functionality.

In addition, this manual should be bundled with example simulation files. We advise looking at those as a companion to the material described here.

Viewing Results¶

The intact command line outputs VTK files. These are fairly standard, and can be manipulated in a variety of programming languages. For more information about official VTK resources please check out their homepage.

VTK - The Visualization Toolkit

There are a number of third-party libraries for working with VTK files in other languages.

We recommend using the Paraview application for viewing and manipulating these results in most cases. Paraview is an industry-standard scientific data analysis and visualization tool that is free and open-source. More information, and builds for most operating systems, are available from the Paraview home page.

Paraview Quick-start¶

Opening Paraview should yield an interface that looks roughly like this.

The intact command line tool will place the samples in the results directory (by default, the same directory as the json file). Looks for a samples *.vtu file and open it in Paraview. Some physics types, like modal and transient thermal will produce multiple output files.

Make sure the samples are visible in the pipeline browser by clicking the eye icon.

The sampled fields are available in the properties dropdown. For example the following would be typical of a linear elasticity scenario.

Here is how stress results would look. One can rotate and pan the viewport.

Command Line Options¶

Command line documentation can be retrieved with the help flag.

$ intact --help

The help documentation bundled with the tool is definitive, the most important options are covered here in more detail.

`-s, --scenario <path/to/scenario.json>`¶

When not calling either --help or --build-info, this option is mandatory for all calls. The tool needs a path for the scenario json file to use.

`-o, --output <path/to/output_dir>`¶

The tool generates a variety of output files. By default, these files will be put in the same directory as the scenario json file. Use this flag to change the directory where output files will be placed. The scenario json file, and any geometry files referenced, will be copied over to the output directory.

`--build-info`¶

This flag can be used to get detailed information about the version of the tool. Attaching this information to any bug reports will help with debugging.

Specifying Boundary Conditions¶

Specifying boundary conditions for Intact.Simulation is a bit different than other FEA systems. Because Intact’s technology is based on the use of a non-conforming mesh, boundary conditions are not specified directly on a finite element mesh. This also means that Intact does not support non-real boundary conditions like point and edge constraints / forces / moments.

Instead, boundary conditions in Intact are specified as triangle mesh based surfaces. These can be either *.ply or *.stl files. Specific semantics of what each boundary conditions does are specified in the section for each physics, however all boundary conditions will need to specify a surface.

Some things to keep in mind with these surfaces.

Having multiple disconnected components in one mesh will not cause a runtime error but may not yield high quality results. It is best to create a separate boundary condition instance in the json configuration for each fully connected component.
It is possible to specify a boundary condition that is disconnected from the geometry. This can result in a runtime warning, but is not an error. Note in cases where a force / quantity is distributed over the boundary condition surface this will result in some of the quantity not being accounted for since there is nothing to apply it to.

Common JSON Keys¶

The scenario json format shares a lot of structure between the different physics. The common components are detailed here. All scenario json files start with a top-level object, which contains a few common attributes.

{
  "boundary_conditions": [ ... ],
  "geometry": { ... },
  "materials": { ... },
  "metadata": { ... },
  "scenario_name": "Name_for_output_files",
  "type": "<physics type>"
}

Geometry¶

Specifying geometry in scenario json has two pieces. First, a collection of components must be defined. Each component has a geometry type, a file to load, a material id, and a component id. The other component to specifying geometry is an assembly of components. The material id needs to match a material defined in the materials object from the scenario object. Each component needs a unique integer id.

`Geometry::Mesh`¶

There are four types of geometry that can be used with components. The most common is to use a triangle mesh to specify the surface of a volume. These triangle meshes can be loaded from both ply and stl files.

{
  "file": "block.ply",
  "geometry_type": "Mesh",
  "id": 1,
  "material": "Acrylic"
}

`Geometry::VDB`¶

Geometry can be specified with an openvdb double grid file.

{
  "file": "demo.vdb",
  "geometry_type": "VDB",
  "id": 2,
  "material": "Steel"
}

Units¶

There are several places in the json format where units can be specified. The possible values are listed here.

"MeterKilogramSecond"
"CentimeterGramSecond"
"MillimeterMegagramSecond"
"FootPoundSecond"
"InchPoundSecond"

Boundary Conditions¶

All scenarios require the specification of boundary conditions. Different scenarios support different types of boundary conditions, but all boundary conditions have a couple of common members.

`boundary`¶

All boundary conditions must be applied to a specified surface. The value should be a path to an *.ply or *.stl file. This path can be relative to the location of the scenario json file. For example, if the configuration json file is in the same directory as restraint.ply then the following would be valid.

"boundary": "restraint.ply"

`units`¶

All boundary conditions can optionally specify units.

`type`¶

The type member differentiates the variety of possible boundary conditions. Each specific boundary condition will contain an example json instance that will have the value for type.

Metadata¶

There are a variety of options available that can be configured with metadata. Either resolution or cell_size must be specified, but no other options need to specified. Default values will be used when not specified.

`units`¶

The default units for the scenario, including geometry. Note that this default does not apply to materials, which will default to MKS unless specified there.

`basis_order`¶

The type of finite element used. The default is 1, which would be linear elements. 2 is for quadratic elements.

`max_iterations_multiplier`¶

This parameters changes the max iterations for iterative solvers, it scales with the number of degrees of freedom. Use a parameter less then one for faster solve times, with the tradeoff of accuracy.

`tolerance`¶

The tolerance for iterative solvers. The default value is 1e-20. That value is meant to achieve high accuracy at the cost of solve runtime. Increasing the tolerance will decrease solve time, but will yield less accurate results.

`resolution`¶

The target number of elements. An iterative process is used to determine a cell size that achieves approximately the specified number of elements. The logging output will include the resolved number of elements and cell size. Either resolution or cell_size must be specified.

`cell_size`¶

The cell size to use. The log output will include the resolved number of elements. When possible, specifying cell_size will skip the expensive iterative process when using the resolution parameters.

`omega_cutoff`¶

A parameter to tune the use of solution structure method for enforcing boundary conditions. By default, there is no cutoff, and it is not recommended to tune this parameter without additional input from Intact Solutions.

`solver_override`¶

The solver_override parameter can be used to explicitly specify the solver to use. The default solver for linear elasticity and modal scenarios is AMGCL_amg_rigid_body. The default solver for thermal scenarios is AMGCL_amg.

The following solvers are available:

  // Iterative conjugate gradient solver without preconditioner.
  AMGCL_cg

  // Iterative conjugate gradient solver with ilu0 preconditioner.
  AMGCL_ilu0_cg

  // Iterative conjugate gradient solver with damped jacobi predonditioner.
  AMGCL_damped_jacobi_cg

  // Iterative AMG based solver with smoothed aggregation.
  // This is the default solver for thermal scenarios.
  AMGCL_amg

  // Iterative AMG based solver with rigid body modes based coarsening.
  // This is the default solver for linear elasticity.
  // This solver cannot be used with thermal scenarios.
  AMGCL_amg_rigid_body

  // Direct solver that uses LU decomposition.
  Eigen_SparseLU

  // A sparse direct Cholesky (LDLT) factorization and solver based on the PARDISO library provided by Intel's MKL.
  MKL_PardisoLDLT

  // A sparse direct Cholesky (LLT) factorization and solver based on the PARDISO library provided by Intel's MKL.
  MKL_PardisoLLT

  // A sparse direct LU factorization and solver based on the PARDISO library provided by Intel's MKL.
  MKL_PardisoLU

`integrator_override`¶

For some physics types, there may be multiple integrator implementations available; the integrator_override configuration allows choosing among the available implementations. In general, the default choice is the best choice.

The following integrators are available:

  // Default for modal scenarios.
  IntactModal

  IntactLinearElasticity

  // Default for thermal scenarios.
  MPCStaticThermal

  // Default for linear elasticity scenarios.
  MPCLinearElasticity

`use_caching`¶

By default, Intact.simulation will cache all quadrature rules and material properties for each cell. This can use significant amounts of memory for problems with lots of elements. To really push the problem size that can be run on a given machine, caching can be turned off to decrease the memory footprint of a simulation run at the cost of additional runtime.

"use_caching": false

`verbose_solver`¶

Some of the sparse linear solvers used by intact can provide feedback about their progress. By default this is false, but if set to true some solvers will report their progress to standard out. For AMGCL solvers, every five iterations the iteration number and various error measurements will be printed. This can be useful for long running simulations to observe progress.

Linear Elasticity¶

Linear elasticity requires the scenario json object to have "type": "LinearElasticity".

Materials¶

Linear Elasticity and Modal scenarios both use our structural material types. All materials need a density value, and can optionally include a "units": member. Note that all materials will be specified in MKS unless units are specified.

Isotropic¶

For isotropic materials, the user must specify a failure criterion type. This is used during sampling to calculate the topological sensitivity and danger level, fields which aren’t sampled for other structural material types. The choices for failure criterion type are:

"Unspecified" // Do not calculate the danger level
"VonMises"
"MaximumShearStress"
"Rankine"
"CoulombMohr"
"ModifiedMohr"

An example of how this would look in json:

{
  "compressive_strength": 690000000.0,
  "density": 7200.0,
  "failure_criterion": "CoulombMohr",
  "poisson_ratio": 0.27,
  "tensile_strength": 170000000.0,
  "yield_strength": 0.0,
  "youngs_modulus": 100000000000.0
}

Orthotropic¶

Orthotropic materials have material properties that vary depending on the orientation. The elastic modulus in the x, y and z directions are defined by Ex, Ey and Ez, the Poisson’s ratio by vxy, vxz and vyz, and the shear modulus by Gxy, Gxz and Gyz. The material properties can be transformed by specifying a transform matrix, for example, to simulate composite fibers that are rotated by 45° relative to the x-axis. The type must be Orthotropic.

An example configuration for a composite material of Kevlar and epoxy, with the fibers rotated by 45° relative to the x-axis, is shown below.

{
  "Ex": 85000000000.0,
  "Ey": 5600000000.0,
  "Ez": 5600000000.0,
  "Gxy": 2100000000.0,
  "Gxz": 2100000000.0,
  "Gyz": 2280000000.0,
  "density": 1350,
  "transform":
    [0, 0.7071, 0.7071,
     0, -0.7071, 0.7071,
     1, 0, 0],
  "vxy": 0.34,
  "vxz": 0.23,
  "vyz": 0.34,
  "type": "Orthotropic"
}

Boundary Conditions¶

Fixed¶

Fixes the boundary at 0. Fixed boundary conditions can be applied to both thermal and displacement fields. Fixed displacement boundary conditions are often called restraints in other FEA systems.

{
  "boundary": "restraint_selector.ply",
  "type": "fixed"
}

For thermal scenarios, temperature fields can be fixed to non-zero values with the optional value field.

{
  "boundary": "restraint_selector.ply",
  "type": "fixed",
  "value": 10.0
}

Fixed Vector¶

This boundary condition serves two purposes.

Fixing displacement at some non-zero value.
Partial restraints, also known as axis-aligned sliding restraints.

Displacement is a three dimensional field, and each displacement component can optionally be specified. Any axis not specified will not be restrained. The following example fixes the x component of displacement at 1, while the y and z axis are unrestrained.

{
  "boundary": "restraint_selector.ply",
  "type": "fixed_vector",
  "x_value": 1.0
}

In the following example, the x axis is fixed at 1.0, while the y and z axis are fixed at 0.

{
  "boundary": "restraint_selector.ply",
  "type": "fixed_vector",
  "x_value": 1.0,
  "y_value": 0.0,
  "z_value": 0.0
}

Sliding¶

Sliding boundary conditions prevent displacement in the direction normal to the specified surface, and permit displacement tangential to the surface. A sliding boundary condition can be used to represent a pin joint, for example.

To use a sliding boundary condition, specify the boundary where this boundary condition applies, and specify the type as sliding, as in the following example:

{
  "boundary": "restraint_selector.ply",
  "type": "sliding"
}

Vector Force¶

The vector force boundary conditions will apply a force of a given direction and magnitude evenly over the prescribed surface. Vector force must specify the direction and magnitude.

{
  "boundary": "surface.ply",
  "direction": [
    0.0,
    0.0,
    -1.0
  ],
  "magnitude": 100.0,
  "type": "vector_force",
  "units": "MillimeterMegagramSecond"
}

Pressure Force¶

A pressure force boundary condition applies a pressure of a given magnitude opposing the normal of the boundary.

{
  "boundary": "top_face.ply",
  "magnitude": 100.0,
  "type": "pressure_force",
  "units": "InchPoundSecond"
}

Torque Force¶

Applies a torque force to the boundary. Must specify the axis and origin of the rotation, as well as the magnitude of the torque.

{
  "axis": [
    0.0,
    0.0,
    1.0
  ],
  "boundary": "twist_load_selector.ply",
  "magnitude": 100.0,
  "origin": [
    0.0,
    0.0,
    20.0
  ],
  "type": "torque_force"
}

Hydrostatic Load¶

A hydrostatic load boundary condition simulates a body submerged in liquid, and requires defining the boundary that may be in the liquid, the density of the liquid, and the height the liquid rises above the z = 0 plane.

{
  "boundary": "surface.ply",
  "density": 300.0,
  "height": 30.0,
  "type": "hydrostatic_force",
  "units": "MeterKilogramSecond"
}

Bearing Load¶

A bearing load occurs at the contact between two curved surfaces. The contact pressure is not uniform. It is scaled by the angle of the contact relative to the angle of the force. The specified magnitude is the total force applied over the entire surface.

{
  "boundary": "bearing.ply",
  "direction": [
    0.0,
    -1.0,
    0.0
  ],
  "magnitude": 12.0,
  "type": "bearing_force"
}

Internal Conditions¶

Body Load¶

The body load simulates linear acceleration. This can also be used for gravity. It must specify the direction and magnitude.

{
  "direction": [
    0.0,
    0.0,
    -1.0
  ],
  "magnitude": 9.80665,
  "type": "body_load"
}

Rotational Load¶

The rotational load can be used for both the outward force of velocity and inertial stress from acceleration. The axis and origin of rotation must be specified, as well as the rotational velocity and acceleration.

{
  "angular_acceleration": 100.0,
  "angular_velocity": 0.0,
  "axis": [
    0.0,
    0.0,
    1.0
  ],
  "origin": [
    0.0,
    0.0,
    0.0
   ],
   "type": "rotational_load"
}

Static Thermal¶

Static thermal requires the scenario json object to have "type": "StaticThermal".

Materials¶

All materials need a density value, and can optionally include a "units": member. Note that all materials will be specified in MKS unless units are specified.

ThermalMaterial¶

Thermal materials must specify conductivity and specific heat. A coefficient of thermal expansion can be optionally specified using the expansion_coefficient field. This example is for steel.

{
  "density": 1200.0,
  "specific_heat": 1100.0,
  "thermal_conductivity": 0.17,
  "type": "Thermal"
}

Boundary Conditions¶

Fixed¶

Fixed boundary conditions specify that the boundary is held at a constant temperature and can have a non-zero value.

{
  "boundary": "restraint.stl",
  "type": "fixed",
  "value": 293.15
}

Constant Flux¶

Specifies a heat flow per unit of surface area.

{
  "boundary": "face.ply",
  "magnitude": 28.0,
  "type": "constant_flux"
}

Convection¶

Specifies that transfer of heat from a surrounding medium

{
  "boundary": "thermal_plate.ply",
  "coefficient": 525.0,
  "environment_temperature": 343.15,
  "type": "convection"
}

Thermal Metadata¶

Thermal scenarios have an additional metadata value they must specify.

`environment_temperature`¶

The temperature of the surrounding environment.

OpenMP¶

The intact command line uses OpenMP parallelization. OpenMP can be controlled by several environment variables. In general, users will want to specify the number of threads using the OMP_NUM_THREADS environment variable to be equal to or less than the number of compute cores available.

Analytics¶

Intact Solutions gathers anonymous error reports using Sentry.io and anonymous logs using Betterstack.com. You will be notified when installing Intact.Simulation about this data collection.

What is collected?¶

The collected data include

resolution of simulated model
duration of various steps in the simulation process, such as system assembly, solver setup, solving the linear system
crash dumps

Intact.Simulation does not collect details about your specific model or simulation, nor any personally identifying information.

Why is this data collected?¶

This data is collected to understand the size of problems that Intact.Simulation is being used on, to understand its performance and bottlenecks to guide future improvements, and to capture information about failures and defects to improve the software’s quality.

Opting out¶

If you want to opt out, set the environment variable INTACT_NO_ANALYTICS. For example, using the bash shell, you can do the following to set the environment variable and run Intact.Simulation

INTACT_NO_ANALYTICS=1 ./intact --help

In Windows Powershell, the equivalent command is

$env:INTACT_NO_ANALYTICS=1; .\intact.exe --help

Intact CLI 1.0.5 User’s Manual¶

Introduction¶

Viewing Results¶

Paraview Quick-start¶

Command Line Options¶

-s, --scenario <path/to/scenario.json>¶

-o, --output <path/to/output_dir>¶

--refinement-level <ratio>¶

--build-info¶

Specifying Boundary Conditions¶

Common JSON Keys¶

Geometry¶

Geometry::Mesh¶

Geometry::VDB¶

Units¶

Boundary Conditions¶

boundary¶

units¶

type¶

Metadata¶

units¶

basis_order¶

max_iterations_multiplier¶

tolerance¶

resolution¶

cell_size¶

omega_cutoff¶

solver_override¶

integrator_override¶

use_caching¶

verbose_solver¶

Linear Elasticity¶

Materials¶

Isotropic¶

Orthotropic¶

Boundary Conditions¶

Fixed¶

Fixed Vector¶

Sliding¶

Vector Force¶

Pressure Force¶

Torque Force¶

Hydrostatic Load¶

Bearing Load¶

Internal Conditions¶

Body Load¶

Rotational Load¶

Modal¶

Materials¶

Modal Metadata¶

desired_eigenvalues¶

Boundary Conditions¶

Static Thermal¶

Materials¶

ThermalMaterial¶

Boundary Conditions¶

Fixed¶

Constant Flux¶

Convection¶

Thermal Metadata¶

environment_temperature¶

OpenMP¶

Analytics¶

What is collected?¶

Why is this data collected?¶

Opting out¶

`-s, --scenario <path/to/scenario.json>`¶

`-o, --output <path/to/output_dir>`¶

`--refinement-level <ratio>`¶

`--build-info`¶

`Geometry::Mesh`¶

`Geometry::VDB`¶

`boundary`¶

`units`¶

`type`¶

`units`¶

`basis_order`¶

`max_iterations_multiplier`¶

`tolerance`¶

`resolution`¶

`cell_size`¶

`omega_cutoff`¶

`solver_override`¶

`integrator_override`¶

`use_caching`¶

`verbose_solver`¶

`desired_eigenvalues`¶

`environment_temperature`¶