Description

Base class for all preCICE adapters.

#include <ChPreciceAdapter.h>

Inheritance diagram for chrono::ch_precice::ChPreciceAdapter:
Collaboration diagram for chrono::ch_precice::ChPreciceAdapter:

Classes

struct  CouplingDataInfo
 Definition of a coupling data block. More...
 
struct  CouplingMeshInfo
 Definition of a coupling mesh. More...
 

Public Types

enum  CouplingMeshType {
  CouplingMeshType::GENERIC, CouplingMeshType::RIGID_BODY_REFS, CouplingMeshType::RIGID_BODY_POINTS, CouplingMeshType::FEA_MESH_NODES,
  CouplingMeshType::FEA_MESH_POINTS
}
 Chrono coupling mesh types (mesh vertex semantics). More...
 
enum  CouplingDataType {
  CouplingDataType::GENERIC, CouplingDataType::POSITIONS, CouplingDataType::ROTATIONS, CouplingDataType::DISPLACEMENTS,
  CouplingDataType::LINEAR_VELOCITIES, CouplingDataType::ANGULAR_VELOCITIES, CouplingDataType::FORCES, CouplingDataType::TORQUES
}
 Chrono coupling data type. More...
 
enum  CouplingReadTime { CouplingReadTime::WINDOW_START, CouplingReadTime::WINDOW_END }
 Point within the coupling time window at which data from other participants is sampled. More...
 

Public Member Functions

void SetVerbose (bool verbose)
 Enable/disable verbose terminal output (default: false).
 
void EnableVisualization (bool vis)
 Enable/disable run-time visualization (default: false). More...
 
void EnableOutput (bool out)
 Enable/disable simulation output (default: false). More...
 
void SetOutputDir (const std::string &out_dir)
 Set root output directory (default: "."). More...
 
void SetOutputSettings (const ChOutput::Settings &settings)
 Set Chrono simulation output settings. More...
 
void SetOutputSettings (ChOutput::Format format, ChOutput::Mode mode, double output_fps)
 Set Chrono simulation output settings. More...
 
void SetModelName (const std::string &name)
 Set the Chrono model name.
 
const std::string & GetModelName () const
 Get the name of the Chrono model.
 
int GetCouplingMeshDimensions (const std::string &mesh_name) const
 Get the number of spatial dimensions for the mesh with specified name. More...
 
size_t GetNumVertices (const std::string &mesh_name)
 Get the number of vertices for the mesh with specified name.
 
CouplingMeshType GetCouplingMeshType (const std::string &mesh_name) const
 Get the type (vertex semantics) for the mesh with specified name.
 
std::string GetCouplingMeshTypeAsString (const std::string &mesh_name) const
 Get the type (vertex semantics) for the mesh with specified name.
 
int GetCouplingDataDimensions (const std::string &mesh_name, const std::string &data_name) const
 Get the data dimensions for the data with specified name on the mesh with specified name. More...
 
CouplingDataType GetCouplingDataType (const std::string &mesh_name, const std::string &data_name) const
 Get the type for the coupling data with specified name on the mesh with specified name.
 
bool GetCouplingDataUsed (const std::string &mesh_name, const std::string &data_name) const
 Get the used flag for the coupling data with specified name on the mesh with specified name. More...
 
std::string GetCouplingDataTypeAsString (const std::string &mesh_name, const std::string &data_name) const
 Get the type for the coupling data with specified name on the mesh with specified name.
 
double GetMaxTimeStepSize () const
 Get the maximum time step size from preCICE.
 
void SetCouplingReadTime (CouplingReadTime read_time)
 Set the point within the coupling time window at which data from other participants is read (default: CouplingReadTime::WINDOW_START). More...
 
CouplingReadTime GetCouplingReadTime () const
 Get the point within the coupling time window at which data from other participants is read.
 
const std::string & GetParticipantName () const
 Get the preCICE participant name.
 
std::vector< std::string > GetCouplingMeshNames () const
 Get the coupled mesh names on this participant.
 
std::vector< std::string > GetReadDataNamesOnMesh (const std::string &mesh_name) const
 Get the data names for reading on the mesh with specified name.
 
std::vector< std::string > GetWriteDataNamesOnMesh (const std::string &mesh_name) const
 Get the data names for writing on the mesh with specified name.
 
bool MustWriteInitialData ()
 Check if the participant is required to provide initial data. More...
 
bool IsCouplingOngoing ()
 Check if coupling is ongoing.
 
bool IsTimeWindowComplete ()
 Check if the time window has completed.
 
void InitializeSimulation (int process_index=0, int process_size=1)
 Create the participant (using the specified solver process size and index) and initialize the coupled simulation for this participant. More...
 
void RunSimulation ()
 Wrapper function for performing the simulation loop. More...
 
void FinalizeSimulation ()
 Wrapper function for finalizing the coupled simulation for this participant. More...
 

Static Public Member Functions

static std::string GetCouplingDataTypeAsString (CouplingDataType type)
 Return the data type as a string.
 

Protected Types

using CouplingData = std::map< std::string, CouplingDataInfo >
 Data type to hold information for all data blocks in a coupling mesh, indexed by the data name.
 
using CouplingMeshes = std::map< std::string, CouplingMeshInfo >
 Data type to hold data for all coupling meshes, indexed by the mesh name.
 
using MeshDataNames = std::map< std::string, std::vector< std::string > >
 Data type to hold data names associated with a given mesh name.
 

Protected Member Functions

 ChPreciceAdapter (const std::string &precice_config_filename, const std::string &model_name="", bool verbose=false)
 
 ChPreciceAdapter (const ChPreciceAdapter &)=delete
 
void operator= (const ChPreciceAdapter &)=delete
 
void SetParticipantName (const std::string &participant_name)
 Set the participant name. More...
 
void AddCouplingMeshInterface (const std::string &mesh_name, CouplingMeshType data_type, const std::vector< std::string > &data_write_names, const std::vector< std::string > &data_read_names)
 Add a coupling mesh with specified data type, using the given lists of data names for writing and reading. More...
 
void RegisterMesh (const std::string &mesh_name, const std::vector< ChVector3d > &positions)
 Register a coupling mesh with preCICE, using the specified mesh name and its vertex positions (of ChVector3d type). More...
 
void RegisterMesh (const std::string &mesh_name, const std::vector< double > &positions)
 Register a coupling mesh with preCICE, using the specified mesh name and its vertex positions (as a flattened vector of doubles). More...
 
void ReadData ()
 Receive data from other participant(s) via preCICE. More...
 
void WriteData ()
 Send data to other participant(s) via preCICE. More...
 
void SetDataBlock (const std::string &mesh_name, const std::string &data_name, const std::vector< double > &data)
 Set the (write) data vector for the specified mesh and data names.
 
void WriteDataBlock (const std::string &mesh_name, const std::string &data_name)
 Write (send) a block of data to preCICE.
 
void WriteDataBlock (const std::string &mesh_name, const std::string &data_name, const std::vector< double > &data)
 Set and write (send) a block of data to preCICE. More...
 
void ReadDataBlock (const std::string &mesh_name, const std::string &data_name, double relative_read_time)
 Read (receive) a block of data from preCICE.
 
const std::vector< double > & GetDataBlock (const std::string &mesh_name, const std::string &data_name) const
 Get the (read) data vector for the specified mesh and data names.
 
const std::vector< double > & ReadDataBlock (const std::string &mesh_name, const std::string &data_name)
 Read (receive) a block of data from preCICE and return the data vector. More...
 
bool WriteCheckpoint (double time)
 Write the solver state to a checkpoint if required by preCICE. More...
 
bool ReadCheckpoint (double time)
 Read the solver state from a checkpoint if required by preCICE. More...
 
void WriteOutput (int frame, double time)
 Prepare output database (if needed) and let the concrete participant write output.
 
virtual void InitializeParticipant ()=0
 Let the derived class perform any necessary operations during the simulation initialization. More...
 
virtual void OnReadData ()=0
 Process data received from other solvers. More...
 
virtual void OnWriteData ()=0
 Prepare data to be sent to other solvers. More...
 
virtual void OnReadCheckpoint (double time)=0
 Read a previously saved checkpoint (if required by preCICE). More...
 
virtual void OnWriteCheckpoint (double time)=0
 Write a checkpoint (if required by preCICE).
 
virtual double GetSolverTimeStep (double max_time_step) const
 Let the derived class implement the actual computation of the solver time step based on the maximum time step provided by preCICE. More...
 
virtual void AdvanceParticipant (double time, double time_step)=0
 Let the derived class implement the actual solver time-stepping by the given time step.
 
virtual void FinalizeParticipant ()
 Let the derived class perform any necessary operations during simulation shutdown. More...
 
virtual void OnWriteOutput (int frame, double time)=0
 Write output from the Chrono preCICE participant. More...
 
void Output (double time)
 Save output at the current frame is output is enabled. More...
 
void Render (double time)
 Render the current frame if run-time visualization is available and enabled. More...
 
virtual size_t GetNumFsiBodies () const
 Return dimension of one added mass block. More...
 
virtual void OnReadDataAM (const std::vector< ChMatrix66d > &blocks)
 Process added mass data received via preCICE. More...
 
virtual void OnWriteDataAM (std::vector< ChMatrix66d > &blocks)
 Prepare added mass data to be sent via preCICE. More...
 

Static Protected Member Functions

static std::vector< double > SetVerticesToData (const std::vector< ChVector2d > &vertices)
 Convert a vector of ChVector2d to a vector of doubles in the format (x0, y0, x1, y1, ...).
 
static std::vector< double > SetVerticesToData (const std::vector< ChVector3d > &vertices)
 Convert a vector of ChVector3d to a vector of doubles in the format (x0, y0, z0, x1, y1, z1, ...).
 
static std::vector< ChVector3dReadPoints (const std::string &filename)
 Read a set of 3D points from an ASCII file (one point per line, space-delimited).
 

Protected Attributes

std::string m_model_name
 Chrono model name.
 
std::string m_precice_config_filename
 name of the preCICE configuration file
 
bool m_use_added_mass
 
bool m_use_dynamic_added_mass
 
CouplingReadTime m_coupling_read_time
 where in the time window read data is sampled
 
std::unique_ptr< precice::Participant > m_participant
 preCICE instance
 
std::string m_participant_name
 name of the Chrono preCICE participant/solver
 
CouplingMeshes m_coupling_meshes
 data for all coupling meshes
 
MeshDataNames m_data_read
 input data names for all coupling meshes
 
MeshDataNames m_data_write
 output data names for all coupling meshes
 
bool m_interfaces_created
 true if the data interfaces were created
 
bool m_participant_created
 true if the preCICE participant was created
 
bool m_initialized
 true if preCICE participant was initialized
 
bool m_verbose
 verbose terminal output
 
std::string m_prefix1
 prefix for terminal messages (first line)
 
std::string m_prefix2
 prefix for terminal messages (subsequent lines)
 
bool m_visualize
 enable/disable run-time visualization
 
bool m_output
 enable/disable run-time output
 
std::string m_output_dir
 output directory name
 
ChOutput::Settings m_output_settings
 output settings
 
std::unique_ptr< ChOutputm_output_db
 output database
 

Member Enumeration Documentation

◆ CouplingDataType

Chrono coupling data type.

Enumerator
GENERIC 

generic data

POSITIONS 

3D positions (of body ref frames, body points, or FEA nodes)

ROTATIONS 

3D rotations (of body ref frames, expressed as rotation vectors)

DISPLACEMENTS 

3D displacements (relative to initial position)

LINEAR_VELOCITIES 

3D velocities (of body ref frames, body points, or FEA nodes)

ANGULAR_VELOCITIES 

3D angular velocities (of body ref frames)

FORCES 

3D forces (on body ref frames, body points, or FEA nodes)

TORQUES 

3D torques (on body ref frames)

◆ CouplingMeshType

Chrono coupling mesh types (mesh vertex semantics).

Enumerator
GENERIC 

generic mesh

RIGID_BODY_REFS 

set of points corresponding to rigid body reference frames

RIGID_BODY_POINTS 

set of points on rigid bodies

FEA_MESH_NODES 

set of points corresponding FEA mesh nodes

FEA_MESH_POINTS 

set of points on FEA meshes

◆ CouplingReadTime

Point within the coupling time window at which data from other participants is sampled.

preCICE associates data written by a participant during a time window with the end of that window; reading at the start of the window therefore returns the value produced during the previous window.

Enumerator
WINDOW_START 

Read data valid at the beginning of the coupling time window (default).

Every participant then consumes data produced by the others during the previous window, so a force sent from a fluid to a solid phase lags the solid state it was evaluated at by one window.

WINDOW_END 

Read data valid at the end of the coupling time window.

Only meaningful for the participant listed as second in a serial coupling scheme: that participant runs after the first one within each window, so the data the first participant produced in the current window is already available. This removes the one-window lag described above.

Member Function Documentation

◆ AddCouplingMeshInterface()

void chrono::ch_precice::ChPreciceAdapter::AddCouplingMeshInterface ( const std::string &  mesh_name,
CouplingMeshType  data_type,
const std::vector< std::string > &  data_write_names,
const std::vector< std::string > &  data_read_names 
)
protected

Add a coupling mesh with specified data type, using the given lists of data names for writing and reading.

This function can be called more than once. Notes:

  • if the Chrono preCICE participant is created from a YAML specification file, interface information is read from that file.

◆ EnableOutput()

void chrono::ch_precice::ChPreciceAdapter::EnableOutput ( bool  out)
inline

Enable/disable simulation output (default: false).

A concrete Chrono preCICE adapter may or may not support simulation output.

◆ EnableVisualization()

void chrono::ch_precice::ChPreciceAdapter::EnableVisualization ( bool  vis)
inline

Enable/disable run-time visualization (default: false).

A concrete Chrono preCICE adapter may or may not support run-time visualization.

◆ FinalizeParticipant()

virtual void chrono::ch_precice::ChPreciceAdapter::FinalizeParticipant ( )
inlineprotectedvirtual

Let the derived class perform any necessary operations during simulation shutdown.

This function is called before the preCICE coupling is finalized.

◆ FinalizeSimulation()

void chrono::ch_precice::ChPreciceAdapter::FinalizeSimulation ( )

Wrapper function for finalizing the coupled simulation for this participant.

The operations performed by this function are:

  • let participant finalize (shutdown)
  • finalize preCICE coupling

◆ GetCouplingDataDimensions()

int chrono::ch_precice::ChPreciceAdapter::GetCouplingDataDimensions ( const std::string &  mesh_name,
const std::string &  data_name 
) const

Get the data dimensions for the data with specified name on the mesh with specified name.

This information is obtained from the preCICE configuration.

◆ GetCouplingDataUsed()

bool chrono::ch_precice::ChPreciceAdapter::GetCouplingDataUsed ( const std::string &  mesh_name,
const std::string &  data_name 
) const

Get the used flag for the coupling data with specified name on the mesh with specified name.

Return true if the data block is referenced in the preCICE configuration file and false otherwise.

◆ GetCouplingMeshDimensions()

int chrono::ch_precice::ChPreciceAdapter::GetCouplingMeshDimensions ( const std::string &  mesh_name) const

Get the number of spatial dimensions for the mesh with specified name.

This information is obtained from the preCICE configuration.

◆ GetNumFsiBodies()

size_t chrono::ch_precice::ChPreciceAdapter::GetNumFsiBodies ( ) const
protectedvirtual

Return dimension of one added mass block.

Called only is using dynamic added mass.

◆ GetSolverTimeStep()

virtual double chrono::ch_precice::ChPreciceAdapter::GetSolverTimeStep ( double  max_time_step) const
inlineprotectedvirtual

Let the derived class implement the actual computation of the solver time step based on the maximum time step provided by preCICE.

The default implementation simply returns the maximum time step provided by preCICE, but derived classes can override this to implement custom time-stepping logic.

◆ InitializeParticipant()

virtual void chrono::ch_precice::ChPreciceAdapter::InitializeParticipant ( )
protectedpure virtual

Let the derived class perform any necessary operations during the simulation initialization.

This function is called before the solver writes initial data (if requested) and before the preCICE coupling is initialized. After the call to InitializeParticipant, it is assumed that the coupling meshes have been set.

◆ InitializeSimulation()

void chrono::ch_precice::ChPreciceAdapter::InitializeSimulation ( int  process_index = 0,
int  process_size = 1 
)

Create the participant (using the specified solver process size and index) and initialize the coupled simulation for this participant.

The participant initializes the output data (if needed), after which the coupling is initialized. The operations performed by this function are:

  • initialize the participant solver
  • let participant to write initial data (if requested)
  • initialize the preCICE coupling for this participant

◆ MustWriteInitialData()

bool chrono::ch_precice::ChPreciceAdapter::MustWriteInitialData ( )

Check if the participant is required to provide initial data.

If true, the participant needs to write initial data to defined vertices prior to calling Initialize().

◆ OnReadCheckpoint()

virtual void chrono::ch_precice::ChPreciceAdapter::OnReadCheckpoint ( double  time)
protectedpure virtual

Read a previously saved checkpoint (if required by preCICE).

The solver from a derived class must restore its state at the values in the last saved checkpoint and, if needed, reset its internal time to the provided value.

◆ OnReadData()

virtual void chrono::ch_precice::ChPreciceAdapter::OnReadData ( )
protectedpure virtual

Process data received from other solvers.

A derived class must:

  • perform any necessary processing of the data now stored in m_coupling_meshes
  • only access data from entries with names in m_data_read

◆ OnReadDataAM()

void chrono::ch_precice::ChPreciceAdapter::OnReadDataAM ( const std::vector< ChMatrix66d > &  blocks)
protectedvirtual

Process added mass data received via preCICE.

Called only if using dynamic added mass on a receiving participant. Must be overridden if using dynamic added mass and this is a sending participant; the default implementation throws in that case.

◆ OnWriteData()

virtual void chrono::ch_precice::ChPreciceAdapter::OnWriteData ( )
protectedpure virtual

Prepare data to be sent to other solvers.

A derived class must:

  • prepare the data to be sent and load it in m_coupling_meshes
  • only access data from entries with names in m_data_write

◆ OnWriteDataAM()

void chrono::ch_precice::ChPreciceAdapter::OnWriteDataAM ( std::vector< ChMatrix66d > &  blocks)
protectedvirtual

Prepare added mass data to be sent via preCICE.

Called only if using dynamic added mass on a sending participant. Must be overridden if using dynamic added mass and this is a sending participant; the default implementation throws in that case. On entry, blocks is sized to the number of FSI bodies (as reported by GetNumFsiBodies) and is zero-initialized. The override is expected to set the 6x6 added mass block for every FSI body; any block left untouched is sent as a zero block.

◆ OnWriteOutput()

virtual void chrono::ch_precice::ChPreciceAdapter::OnWriteOutput ( int  frame,
double  time 
)
protectedpure virtual

Write output from the Chrono preCICE participant.

A derived class must:

  • write output to the DB

◆ Output()

void chrono::ch_precice::ChPreciceAdapter::Output ( double  time)
protected

Save output at the current frame is output is enabled.

This function ensures that output occurs at the specified frequency.

◆ ReadCheckpoint()

bool chrono::ch_precice::ChPreciceAdapter::ReadCheckpoint ( double  time)
protected

Read the solver state from a checkpoint if required by preCICE.

If requested by preCISE, this function invokes the solver-specific checkpoint reading function. The return value indicates whether a checkpoint was read.

◆ ReadData()

void chrono::ch_precice::ChPreciceAdapter::ReadData ( )
protected

Receive data from other participant(s) via preCICE.

The received data is then passed to the concrete participant (via OnReadData).

◆ ReadDataBlock()

const std::vector< double > & chrono::ch_precice::ChPreciceAdapter::ReadDataBlock ( const std::string &  mesh_name,
const std::string &  data_name 
)
protected

Read (receive) a block of data from preCICE and return the data vector.

This is a convenience function that combines ReadDataBlock and GetDataBlock into a single call. It is assumed that the data is always read at the beginning of the time step (relative_read_time = 0).

◆ RegisterMesh() [1/2]

void chrono::ch_precice::ChPreciceAdapter::RegisterMesh ( const std::string &  mesh_name,
const std::vector< ChVector3d > &  positions 
)
protected

Register a coupling mesh with preCICE, using the specified mesh name and its vertex positions (of ChVector3d type).

If the mesh dimension is 2, the z component of the given position vectors is discarded. With the mesh size, the data maps inside the adapter initialize the relevant data vector to size of mesh_size*data_dimension.

◆ RegisterMesh() [2/2]

void chrono::ch_precice::ChPreciceAdapter::RegisterMesh ( const std::string &  mesh_name,
const std::vector< double > &  positions 
)
protected

Register a coupling mesh with preCICE, using the specified mesh name and its vertex positions (as a flattened vector of doubles).

This method can be used for both 2D and 3D meshes by providing the appropriate positions vector. The positions vector is expected to be in the format:

  • (x0, y0, x1, y1, ...) for 2D meshes, and
  • (x0, y0, z0, x1, y1, z1, ...) for 3D meshes. With the mesh size, the data maps inside the adapter initialize the relevant data vector to size of mesh_size*data_dimension.
  • scalar data (declared with <data:scalar ...>) has data_dimension = 1; e.g., temperature, pressure, etc.
  • vector data (declared with <data:vector ...>) has data_dimension equal to the mesh dimension; e.g., velocity, displacement, etc.

◆ Render()

void chrono::ch_precice::ChPreciceAdapter::Render ( double  time)
protected

Render the current frame if run-time visualization is available and enabled.

This function ensures that frames are rendered at the specified frequency. If requested, snapshots are saved to disk.

◆ RunSimulation()

void chrono::ch_precice::ChPreciceAdapter::RunSimulation ( )

Wrapper function for performing the simulation loop.

While coupling is ongoing, at each iteration, the participant:

  • writes a checkpoint if requested
  • agrees on the simulation time step size
  • reads data
  • advances the underlying solver dynamics
  • writes data
  • advances the preCICE coupling
  • reads a checkpoint if requested, otherwise advances time

◆ SetCouplingReadTime()

void chrono::ch_precice::ChPreciceAdapter::SetCouplingReadTime ( CouplingReadTime  read_time)
inline

Set the point within the coupling time window at which data from other participants is read (default: CouplingReadTime::WINDOW_START).

The setting is checked against the coupling scheme declared in the preCICE configuration file during initialization; see CouplingReadTime. Must be set before InitializeSimulation().

◆ SetOutputDir()

void chrono::ch_precice::ChPreciceAdapter::SetOutputDir ( const std::string &  out_dir)

Set root output directory (default: ".").

The specified directory must exist.

◆ SetOutputSettings() [1/2]

void chrono::ch_precice::ChPreciceAdapter::SetOutputSettings ( ChOutput::Format  format,
ChOutput::Mode  mode,
double  output_fps 
)

Set Chrono simulation output settings.

Note: If the Chrono preCICE adapter is created from a YAML specification file, these settings are read from that file.

Parameters
formatoutput DB format
modeoutput mode
output_fpsoutput frequency

◆ SetOutputSettings() [2/2]

void chrono::ch_precice::ChPreciceAdapter::SetOutputSettings ( const ChOutput::Settings settings)

Set Chrono simulation output settings.

Note: If the Chrono preCICE adapter is created from a YAML specification file, these settings are read from that file.

◆ SetParticipantName()

void chrono::ch_precice::ChPreciceAdapter::SetParticipantName ( const std::string &  participant_name)
inlineprotected

Set the participant name.

Notes:

  • if the Chrono preCICE participant is created from a YAML specification file, its name is read from that file.

◆ WriteCheckpoint()

bool chrono::ch_precice::ChPreciceAdapter::WriteCheckpoint ( double  time)
protected

Write the solver state to a checkpoint if required by preCICE.

If requested by preCISE, this function invokes the solver-specific checkpoint writing function. The return value indicates whether a checkpoint was written.

◆ WriteData()

void chrono::ch_precice::ChPreciceAdapter::WriteData ( )
protected

Send data to other participant(s) via preCICE.

The concrete participant first prepares the data to be sent (via OnWriteData).

◆ WriteDataBlock()

void chrono::ch_precice::ChPreciceAdapter::WriteDataBlock ( const std::string &  mesh_name,
const std::string &  data_name,
const std::vector< double > &  data 
)
protected

Set and write (send) a block of data to preCICE.

This is a convenience function that combines SetDataBlock and WriteDataBlock into a single call.


The documentation for this class was generated from the following files:
  • /builds/uwsbel/chrono/src/chrono_precice/ChPreciceAdapter.h
  • /builds/uwsbel/chrono/src/chrono_precice/ChPreciceAdapter.cpp