# 4.10. Coupling

## 4.10.1. File Based Coupling

In a file-based coupling, information is exchanged across apps via results files. This typically implies running one app, then using those results to run the other app. In a one-way coupling that is the end of the simulation, otherwise this process can be cycled until some user-determined convergence metric is met. Within a single simulation, the data from the coupled simulation(s) are typically incorporated by transfering from an IO Region. The IO region handles interpolating data to the current simulation time and mesh. The simulation results can write to an output database to feed into the coupled application.

Note

A file-based coupling is useful for time-varying data generated from an external app. If it is only necessary to apply initial conditions from an external source (e.g. a steady simulation fed into a transient IC), the Ic Input_Output_Region and/or Ic Read_File ICs can be a much simpler alternative.

A file-based coupling input deck will look similar to the example below

    Begin Sierra sierra

      #! 1) The domain Aria solves
      Begin Finite Element Model The_Mesh
        Database Name = mesh.g
        Decomposition Method = rcb

        use material foo for block_1
        use material bar for block_2
        ...
      End

      #! 2) The coupled domain (includes results)
      Begin Finite Element Model The_Coupled_Subdomain
        Database Name = coupling_surf.e
        Decomposition Method = rcb
      End

      ...
      Begin Procedure proc
        Begin Solution Control Description
          Use system main
          Begin system main
            #! 3) Define how a step is taken
            Begin Transient my_transient
              Advance coupled_app_region
              Transfer coupled_to_aria
              Advance aria_region
            End
            ...
          End
        End

        ...

        Begin Aria Region aria_region
          #! 1) The entire Aria domain
          Use Finite Element Model The_Mesh

          #! 4) Set up a user field to be used (also created expressions)
          user field real node scalar my_coupled_qnt on coupled_surface

          ...

          #! 5) Write out the information needed by coupled app
          Begin Results Output out
            database name = to_coupled_app.e
            at step 0, increment = 1
            nodal variables = solution->temperature as T
            ...
          End
        End

        #! 6) Create an IO region to manage coupled interface
        Begin Input_Output Region coupled_app_region
          Use Finite Element Model The_Coupled_Subdomain
        End

        #! 4) Transfer relevant information from couple app to Aria
        Begin transfer coupled_to_aria
          interpolate volume nodes from coupled_app_region to aria_region
          Send block surface_1 to coupled_surface
          Send Field my_coupled_qnt State None to my_coupled_qnt State none
          ...
        End
      End Procedure
    End Sierra

1. Just like a typical simulation, one must specify the finite element model defining the Aria domain

2. Typically, the coupling occurs only on a subset of the domain. Rather than interpolate over the entire domain, one can specify only the subdomain of interest as the finite element model of the Input_Output region. In any case, this database should contain not only the mesh information of the coupled interface, but also the relevant results needed to run the Aria simulation.

3. As part of the transient, the IO region must be advanced so that the appropriate information can be transferred to the aria region.

4. Set up the information transfer from the IO region to the appropriate Aria region fields. The receiving field on the Aria side is typically a DOF field (defined as an XFER EQ) or a user field which can then be used in the Aria expression system.

5. In order to provide the results of this simulation to the coupled app, write an output database.

6. Create the IO region with the data and geometry specified in 2.

## 4.10.2. Sierra Coupling

Unlike a file-based coupling, Sierra coupling means that information is being exchanged during simulation. In general, it will be fairly similar syntactically to a File Based Coupling with the exception that the information comes not from an IO Region but rather other Sierra app regions (still using Transfer between them).

Examples of this include:

- Arpeggio/ Arpeggitar for coupling with Adagio.

- `fuego_aria` for coupling with Fuego.

## 4.10.3. MPMD Coupling

Similar to a Sierra Coupling, MPMD coupling exchanges information during simulation. The key difference however, is that information is exchange not via Sierra framework transfers, but rather external coupled apps using MPMD defined in the Mpmd Coupling block. For more details on MPMD couplings with individual applications, see the respective coupling manuals:

- PMR

- Sparc-Aria

For information on launching an MPMD simulation, see Running MPMD Jobs.