Library Reference¶
ImmersX¶
- page ImmersX

ImmersX is a C++ framework for embedded and mixed-dimensional finite-element simulations. It provides Poisson and elasticity problems, reduced multiplier spaces, immersed coupling, and coupled 3D/1D workflows on top of deal.II 9.7.1 or later.
Read the documentation for guided tutorials, how-to guides, concepts, application reference, and API reference.
Quick start¶
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DDEAL_II_DIR=/path/to/deal.II cmake --build build -j ./build/poisson path/to/input.prm
For a single-config build tree containing both variants, use
-DCMAKE_BUILD_TYPE=DebugRelease. This creates unsuffixed Release targets and_debug-suffixed Debug targets; it is an ImmersX build mode, not a CMake multi-config generator.See the getting-started guide for dependencies, configuration, and the first runnable example.
References¶
Giovanni Alzetta and Luca Heltai, Multiscale modeling of fiber reinforced materials via non-matching immersed methods, Computers & Structures, 239 (2020), 106334. DOI: https://doi.org/10.1016/j.compstruc.2020.106334
Camilla Belponer, Alfonso Caiazzo, and Luca Heltai, Mixed-dimensional modeling of vascular tissues with reduced Lagrange multipliers (2025).
Luca Heltai and Alfonso Caiazzo, Multiscale modeling of vascularized tissues via nonmatching immersed methods, International Journal for Numerical Methods in Biomedical Engineering, 35(12) (2019), e3264. DOI: https://doi.org/10.1002/cnm.3264
Luca Heltai, Alfonso Caiazzo, and Lucas O. Muller, Multiscale Coupling of One-dimensional Vascular Models and Elastic Tissues, Annals of Biomedical Engineering, 49 (2021), 3243-3254. DOI: https://doi.org/10.1007/s10439-021-02804-0
Luca Heltai and Paolo Zunino, Reduced Lagrange multiplier approach for non-matching coupling of mixed-dimensional domains, Mathematical Models and Methods in Applied Sciences, 33(12) (2023), 2425-2462. DOI: https://doi.org/10.1142/S0218202523500525
Yashasvi Verma, Jakob Schattenfroh, Ingolf Sack, Silvia Budday, Paul Steinmann, and Luca Heltai, Simulation Platform to Evaluate Inversion Techniques for Magnetic Resonance Elastography Data (2026).
License¶
See
LICENSE.md.
Class Hierarchy¶
- Namespace ImmersX
- Namespace ImmersX::detail
Template Struct is_field< Field< dim, spacedim, Extractor > >
Template Struct is_lifted_observable< TestLiftedObservable< LiftedObservableType > >
Template Struct is_linear_observable< Observable< SourceFieldType, Operation > >
Template Struct is_observable< Observable< SourceFieldType, Operation > >
Template Struct is_test_expression< TestExpression< SourceFieldType, Operation > >
Template Struct is_test_expression< TestLiftedObservable< LiftedObservableType > >
Template Struct is_weak_term< WeakTerm< ObservableType, TargetField > >
Template Class TensorProductSpace< 0, dim, spacedim, n_components >
File Hierarchy¶
Full API¶
Namespaces¶
Classes and Structs¶
- Template Struct WeakAssembly
- Template Class ExecutionComposition
- Nested Relationships
- Class Documentation
ImmersX::detail::ExecutionCompositionModelBuilderOperatorLocalOperatorSaddlePointMetadataMatrixTypeBlockMatrixTypeExecutionComposition()add()make_state()reinit()field()field()evaluate_residual()jacobian()make_snapshot()make_snapshot()jacobian()differential_components()differential_components()n_fields()model()state_matrix_operator()state_layout()communicator()can_materialize_matrix()block_matrix()monolithic_matrix()monolithic_matrix()monolithic_matrix()monolithic_matrix()has_local_preconditioner()has_complete_local_preconditioners()saddle_points()schur_operator()schur_preconditioner()augmented_lagrangian_operator()augmented_lagrangian_matrix()augmented_lagrangian_preconditioner()local_preconditioner()local_preconditioner()multiplier_preconditioner()block_diagonal_preconditioner()block_triangular_preconditioner()pack()unpack()ImmersX::detail::ExecutionComposition::SnapshotImmersX::detail::ExecutionComposition::StateSnapshot
- Template Class ElasticityProblem
- Inheritance Relationships
- Class Documentation
ImmersX::ElasticityProblemdhowned_dofsrelevant_dofsconstraintsinclusion_constraintsmean_value_constraintsstiffness_matrixnewmark_matrixmass_matrixcoupling_matrixdamping_matrixprec_Aprec_newmarkprec_Cprec_Minclusion_matrixsolutionvelocityaccelerationpredictorcorrectorlocally_relevant_solutionforce_rhsbc_rhsneumann_bc_rhssystem_rhsforcesaverage_displacementsaverage_normalsareassigma_nDistributedTriangulationFullyDistributedTriangulationTriangulationVariantElasticityProblem()make_grid()setup_fe()setup_dofs()setup_constraints()assemble_elasticity_system()add_dynamic_constraint_rhs()assemble_forcing_terms()assemble_forcing_terms()compute_system_rhs()compute_system_rhs()make_newmark_value_constraints()make_newmark_acceleration_constraints()assemble_coupling()run()run_static()run_quasistatic()run_newmark()assemble_coupling_sparsity()solve()solve_static()solve_quasistatic()solve_newmark()refine_and_transfer()refine_and_transfer_around_inclusions()execute_actual_refine_and_transfer()output_solution()output_results()print_parameters()compute_internal_and_boundary_stress()uses_fully_distributed_triangulation()output_lambda()output_stresses()uses_tensor_product_coupling()n_multiplier_dofs()n_multiplier_components_per_coupling_dof()setup_point_coupling_dofs()setup_tensor_product_coupling_dofs()assemble_point_coupling()assemble_tensor_product_coupling()has_immersed_coupling()distribute_multiplier_solution()output_immersed_particles()parmpi_communicatorpcoutcomputing_timertriangulation_storagetriafeinclusionsquadratureface_quadrature_formulaglobal_bounding_boxescycletime_stepdisplacementcurrent_timecoupling_matrices_assembled
- Template Class ElasticityProblemParameters
- Inheritance Relationships
- Class Documentation
ImmersX::ElasticityProblemParametersoutput_directoryoutput_namefe_degreeinitial_refinementdirichlet_idsweak_dirichlet_idsneumann_idsnormal_flux_idsdefault_material_propertiesmaterial_tags_by_material_idmaterial_properties_by_idrhs_material_idsdomain_typetriangulation_typename_of_gridarguments_for_gridgrid_scalerefinement_strategycoarsening_fractionrefinement_fractionn_refinement_cyclesmax_cellsoutput_pressurepenalty_termrhsrhs_by_material_idbcdirichlet_bc_by_idNeumann_bcneumann_bc_by_iddisplacement_solver_controlreduced_mass_solver_controlaugmented_lagrange_solver_controlschur_complement_solver_controlElasticityProblemParameters()get_material_properties()get_dirichlet_bc()get_neumann_bc()get_rhs()set_rhs_times()set_boundary_condition_times()check_model_consistency()time_modeelasticity_modelpressure_couplingexact_solutioninitial_displacementinitial_velocityweight_expressioncoupling_typeestimate_condition_numberoutput_results_before_solvingconvergence_tabletime_parameters
- Template Class ElasticStaticParameters
- Inheritance Relationships
- Class Documentation
ImmersX::ElasticStaticParametersElasticStaticParameters()get_material_properties()get_dirichlet_bc()get_neumann_bc()get_rhs()output_directoryoutput_namefe_degreeinitial_refinementn_refinement_cyclesdirichlet_idsneumann_idsrhs_material_idsdomain_typename_of_gridarguments_for_gridgrid_scaletriangulation_typematerial_tags_by_material_iddefault_material_propertiesmaterial_properties_by_idrhsrhs_by_material_idexact_solutionbcdirichlet_bc_by_idneumann_bcneumann_bc_by_idsolver_controlconvergence_table
- Template Class ElasticStaticProblem
- Class Documentation
ImmersX::ElasticStaticProblemVectorTypeMatrixTypeDistributedTriangulationFullyDistributedTriangulationTriangulationVariantElasticStaticProblem()setup()refine_global()triangulation()locally_owned_dofs()locally_relevant_dofs()dof_handler()constraints()stiffness_operator()forcing()solution()set_forcing()solve()run()set_solution()compute_error()output_results()
- Class Documentation
- Template Class ElastodynamicsParameters
- Inheritance Relationships
- Class Documentation
ImmersX::ElastodynamicsParametersElastodynamicsParameters()output_directoryoutput_namefe_degreeinitial_refinementn_refinement_cyclesdirichlet_idsneumann_idsname_of_gridarguments_for_gridtriangulation_typedensitylame_mulame_lambdadamping_sheardamping_bulktime_parametersfixed_step_parametersida_parametersbody_forcedisplacement_boundaryneumann_boundaryvelocity_boundaryinitial_displacementinitial_velocityexact_solutionsolver_controlconvergence_table
- Template Class ElastodynamicsSolver
- Inheritance Relationships
- Class Documentation
ImmersX::ElastodynamicsSolverVectorTypeMatrixTypeElastodynamicsSolver()make_grid()setup_fe()setup_system()assemble_operators()set_initial_conditions()refine_global()initial_acceleration()advance_one_timestep()solve()output_results()compute_error()run()set_displacement()set_velocity()accept_state()n_dofs()state_is_finite()triangulation()fe()mapping()dof_handler()constraints()velocity_constraints()locally_owned_dofs()locally_relevant_dofs()mass_matrix()stiffness_matrix()damping_matrix()body_force_vector()body_force_at_time()update_constraints()system_matrix()system_rhs()displacement()velocity()current_time()time_step()time_step_number()
- Template Class FiberReinforcedElastodynamics
- Class Documentation
ImmersX::FiberReinforcedElastodynamicsParametersMatrixProblemFiberProblemProblemVectorTypeMatrixTypeFiberReinforcedElastodynamics()setup()set_initial_conditions()advance_one_timestep()run()matrix_problem()fiber_problem()multiplier()residuals()current_time()time_step_number()fiber_excess_elastic_energy()matrix_only_displacement_difference()
- Class Documentation
- Template Class Field
- Nested Relationships
- Class Documentation
ImmersX::Fieldglobal_indexextractor_typeview_typevalue_typespace_typeField()field_id()id()with_id()reindexed()is_registered()name()space()extractor()dof_handler()mapping()triangulation()distributed_triangulation()finite_element()n_dofs_per_cell()constraints()locally_owned_dofs()locally_relevant_dofs()execution_index()has_execution_index()is_reindexed()dimension()space_dimension()spacedimension()spacedim_dimension()
- Template Class ImportedFiniteElementFields
- Nested Relationships
- Class Documentation
ImmersX::ImportedFiniteElementFieldsVectorTypeTriangulationTypeDoFHandlerTypeSpaceViewFieldTypeImportedFiniteElementFields()triangulation()dof_handler()finite_element()locally_owned_dofs()locally_relevant_dofs()coefficients()coefficients()space()catalog()field()mpi_communicator()ImmersX::ImportedFiniteElementFields::FieldView
- Template Class Inclusions
- Inheritance Relationships
- Class Documentation
ImmersX::InclusionsInclusions()n_dofs()n_particles()n_inclusions()n_global_segments()n_local_segments()n_dofs_per_inclusion()initialize()get_dof_indices()setup_inclusions_particles()get_inclusion_id()get_component()get_fourier_component()get_inclusion_data()get_inclusion_data()get_normal()get_JxW()get_fe_values()get_center()get_radius()get_section_measure()get_direction()get_rotation()get_current_support_points()output_particles()update_displacement_hdf5()update_inclusions_data()update_inclusions_data()get_vesselID()update_single_inclusion_data_along_normal()update_single_vessel_data()get_n_vessels()get_n_coefficients()get_offset_coefficients()get_inclusions_in_vessel()get_selected_coefficients()set_n_q_points()set_n_coefficients()set_fourier_coefficients()build_segment_index_vector()get_segment_index()inclusions_rhsmodulation_frequencyphase_shiftinclusions_as_particlesparticles_on_centerlineinclusionsdata_fileinclusions_datareference_inclusion_datamap_vessel_inclusionscluster_with_segments
- Template Class LiftedObservable
- Class Documentation
ImmersX::LiftedObservablesource_field_typevalue_typepoint_value_typestate_typePointLiftSupportOperatorLiftedObservable()LiftedObservable()source()source_field()source_for()dependencies()is_frozen()frozen_values()scale()with_id()lifted_points()locally_owned_quadrature_points()locally_owned_points()locally_relevant_points()point_index()mpi_communicator()evaluate()evaluate_point()linearize_point()linearize()linearize()dimension()spacedimension()is_linear()support_dimensionambient_dimensionrepresentative_dimensionvector_lift
- Class Documentation
- Template Class LinearAdapter
- Class Documentation
ImmersX::LinearAdapterParametersOperatorLocalOperatorMatrixTypeBlockMatrixTypeSaddlePointMetadataSolveFunctionLinearAdapter()solver_options()has_multiplier_metric()setup_direct()add()make_state()reinit()field()field()evaluate_residual()jacobian()can_materialize_matrix()block_matrix()monolithic_matrix()has_local_preconditioner()has_complete_local_preconditioners()saddle_points()schur_operator()schur_preconditioner()augmented_lagrangian_operator()augmented_lagrangian_matrix()augmented_lagrangian_preconditioner()local_preconditioner()block_diagonal_preconditioner()block_triangular_preconditioner()pack()unpack()solve_direct()solve_with_current_direct()solve()
- Class Documentation
- Template Class MetricFlowXVesselWallConstraint
- Class Documentation
ImmersX::MetricFlowXVesselWallConstraintMatrixTypeVectorTypeExternalPressureProviderMetricFlowXVesselWallConstraint()radial_displacement()multiplier_field()make_external_pressure_provider()multiplier_locally_owned_dofs()multiplier_locally_relevant_dofs()set_multiplier()multiplier()output_results()flow_pressure_residual()flow_pressure_jacobian()spacedimflow_pressure_feedback_is_implemented
- Class Documentation
- Template Class NavierStokesParameters
- Inheritance Relationships
- Class Documentation
ImmersX::NavierStokesParametersNavierStokesParameters()set_time()output_directoryoutput_nametime_parametersfixed_step_parametersida_parametersvelocity_degreepressure_degreeinitial_refinementdirichlet_idsname_of_gridarguments_for_gridtriangulation_typedensityviscosityinclude_convective_termanalytical_solution_expressionconvergence_tablerhsbcinitial_conditionsolver_controlinner_solver_max_stepsinner_solver_tolerancelog_solver_iterations
- Template Class NavierStokesSolver
- Inheritance Relationships
- Class Documentation
ImmersX::NavierStokesSolverVectorTypeBlockVectorTypeNavierStokesSolver()make_grid()setup_fe()setup_system()assemble_system()solve()output_results()advance_one_timestep()run()accept_state()n_dofs()n_time_steps()timestep_number()solution_l2_norm()solution_is_finite()system_residual_l2_norm()divergence_l2_norm()current_time()time_step()triangulation()dof_handler()finite_element()mapping()constraints()system_matrix()mass_matrix()continuous_operator()velocity_mass_matrix()pressure_metric_matrix()velocity_forcing_at_time()system_rhs()solution()previous_solution()locally_relevant_solution()locally_owned_dofs()locally_relevant_dofs()locally_owned_dofs_by_block()locally_relevant_dofs_by_block()velocity_extractor()pressure_extractor()velocity_component_mask()density()viscosity()include_convective_term()velocity_block_size()set_solution()
- Template Class Observable
- Class Documentation
ImmersX::Observablesource_field_typeoperation_typeview_typevalue_typeObservable()Observable()Observable()dependencies()source_field()source()source_for()with_id()operation()is_frozen()frozen_values()scale()evaluate_point()linearize_point()scaled()dimension()space_dimension()spacedimension()spacedim()update_flags()is_linear()
- Class Documentation
- Template Class PoissonParameters
- Inheritance Relationships
- Class Documentation
ImmersX::PoissonParametersPoissonParameters()output_directoryoutput_namefe_degreeinitial_refinementdirichlet_idsname_of_gridarguments_for_gridtriangulation_typerefinement_strategycoarsening_fractionrefinement_fractionn_refinement_cyclesmax_cellsrhsbcsolver_controloutput_results_before_solvingestimate_condition_numberconvergence_table
- Template Class PoissonSolver
- Inheritance Relationships
- Class Documentation
ImmersX::PoissonSolverVectorTypePoissonSolver()make_grid()setup_fe()setup_system()assemble_system()solve()output_results()output_results()refine_grid()run()n_dofs()solution_l2_norm()solution_is_finite()triangulation()dof_handler()constraints()system_matrix()system_rhs()locally_owned_dofs()locally_relevant_dofs()solution()set_solution()
- Template Class ProblemParameters
- Inheritance Relationships
- Class Documentation
ImmersX::ProblemParametersoutput_directoryoutput_namefe_degreeinitial_refinementdirichlet_idsname_of_gridarguments_for_gridrefinement_strategycoarsening_fractionrefinement_fractionn_refinement_cyclesmax_cellsrhsbcinner_controlouter_controlProblemParameters()output_results_before_solvingestimate_condition_numberconvergence_table
- Template Class ReducedPoisson
- Inheritance Relationships
- Class Documentation
ImmersX::ReducedPoissonReducedPoisson()make_grid()setup_fe()setup_dofs()assemble_poisson_system()assemble_coupling_system()run()solve()n_reduced_dofs()coupling_matrix_frobenius_norm()bulk_solution_l2_norm()multiplier_solution_l2_norm()bulk_solution_is_finite()multiplier_solution_is_finite()refine_and_transfer()output_solution()output_results()print_parameters()
- Template Class ReducedPoissonParameters
- Inheritance Relationships
- Class Documentation
ImmersX::ReducedPoissonParametersReducedPoissonParameters()output_directoryoutput_namefe_degreedirichlet_idsname_of_gridarguments_for_gridrefinement_strategycoarsening_fractionrefinement_fractionn_refinement_cyclesmax_cellsrhsbcinner_controlouter_controloutput_results_before_solvingestimate_condition_numbersolver_nameassemble_full_AL_systemconvergence_tablereduced_coupling_parameters
- Template Class SemiDiscreteModel
- Nested Relationships
- Class Documentation
ImmersX::SemiDiscreteModelContextOperationOperatorMatrixOperatorResidualFactoryOperatorFactoryMatrixOperatorFactorySaddlePointMetadataVectorReinitializerPreconditionerFactoryevaluate_row()state_operator()state_matrix_operator()derivative_operator()derivative_matrix_operator()has_derivative_terms()has_preconditioner()saddle_points()add_multiplier_metric()has_multiplier_metric()multiplier_metric()preconditioner()has_state_operator()has_derivative_operator()
- Template Class TensorProductSpace
- Inheritance Relationships
- Class Documentation
ImmersX::TensorProductSpaceTensorProductSpace()initialize()get_reference_cross_section()make_reduced_grid_and_properties()get_dof_handler()get_locally_owned_qpoints()get_locally_owned_weights()get_locally_owned_mode_values()get_locally_owned_reduced_qpoints()get_locally_owned_reduced_weights()get_locally_owned_section_measure()update_local_dof_indices()get_dof_indices()particle_id_to_cell_and_qpoint_indices()particle_id_to_representative_indices()register_particle_id_mapping()locally_owned_qpoints()locally_relevant_indices()get_quadrature()compute_points_and_weights()get_triangulation()get_scaling()get_properties()get_properties_dh()get_properties_catalog()get_properties_bindings()get_thickness_expression()get_thickness_evaluator()set_time()n_representative_dofs()locally_owned_representative_dofs()locally_relevant_representative_dofs()n_representative_entities()locally_owned_representative_entities()get_representative_dof_indices()n_representative_q_points_per_entity()n_representative_dofs_per_entity()cross_section_dimsetup_dofs()local_q_point_indices_to_global_cell_indices()mpi_communicatorparreference_cross_sectiontriangulationfequadrature_formuladof_handlerglobal_cell_to_dof_indicesall_qpointsall_weightsall_mode_valuesreduced_qpointsreduced_weightspropertiesproperties_dhproperties_catalogproperties_bindingsthickness_expressionconstant_thicknessevaluation_timethickness_evaluator
- Template Class TensorProductSpace< 0, dim, spacedim, n_components >
- Class Documentation
ImmersX::TensorProductSpace< 0, dim, spacedim, n_components >TensorProductSpace()initialize()prepare()make_reduced_grid_and_properties()set_point_cloud()initialize_representative_particle_handler()get_representative_particles()register_particle_id_mapping()get_reference_cross_section()get_locally_owned_qpoints()get_locally_owned_weights()get_locally_owned_mode_values()get_locally_owned_reduced_qpoints()get_locally_owned_reduced_weights()get_locally_owned_section_measure()update_local_dof_indices()get_dof_indices()particle_id_to_cell_and_qpoint_indices()particle_id_to_representative_indices()locally_owned_qpoints()locally_relevant_indices()compute_points_and_weights()get_scaling()n_representative_dofs()locally_owned_representative_dofs()locally_relevant_representative_dofs()n_representative_entities()locally_owned_representative_entities()get_representative_dof_indices()n_representative_q_points_per_entity()n_representative_dofs_per_entity()get_properties_catalog()get_properties()get_properties_bindings()get_thickness_expression()get_thickness_evaluator()set_time()get_entity_property_values()get_entity_thickness()get_entity_position()get_entity_orientation()cross_section_dimmpi_communicatorparreference_cross_sectionpoint_cloudrepresentative_entity_to_dof_indicesall_qpointsall_weightsall_mode_valuesreduced_qpointsreduced_weightssection_measureparticle_id_to_representativerepresentative_particlesrepresentative_handler_initializedn_global_representative_entitiessource_entity_idsrepresentative_propertiesrelevant_representative_entitieslifted_entity_idslifted_section_indicesall_lifted_entity_idsall_lifted_section_indicesproperties_catalogproperties_bindingsentity_propertiesentity_thicknessthickness_expressionconstant_thicknessevaluation_timethickness_evaluator
- Class Documentation
- Template Class TestExpression
- Class Documentation
ImmersX::TestExpressionsource_field_typeoperation_typeview_typevalue_typeTestExpression()TestExpression()TestExpression()TestExpression()operator=()operator=()source()source_for()source_field()dependencies()operation()is_frozen()scale()scaled()with_id()dimension()space_dimension()spacedimension()spacedim()update_flags()is_linear()
- Class Documentation