FISH Model

The FISH contact model can facilitate contact model development. This model can be installed for any contact types, and is referred to in commands and FISH by the name fish.

Introduction

The FISH scripting language is a powerful tool for adding custom physics. This contact model is a blank slate for users to implement their own contact physics via a FISH function. The function takes nine arguments that are filled inside the force-displacement computation. The FISH function must modify the contact model force and/or moment. If effective stiffnesses are provided, then the timestep is determined automatically. Contact extra variables or global FISH symbols can be used to manage the contact model properties. It is also strongly suggested that the contact property indices be used to set the properties in the FISH model while cycling, as string properties are very slow to resolve during cycling (see contact.model.prop.index and contact.prop.index).

Behavior Summary

The FISH model does not encapsulate any contact physics. Instead, the user must specify a FISH function that is called during the force-displacement law. The force and moment properties should be specified in the FISH function for the pieces to react to the forces/moments computed. Please set these properties via the contact property indices (see contact.model.prop.index and contact.prop.index).

Activity-Deletion Criteria

An unbonded contact with the FISH model is active if and only if the surface gap is less than or equal to zero. If the bonding property is set, the contact remains active until the bonding property is removed. Once removed, the surface gap is queried to determine activity. The force-displacement law is skipped for inactive contacts, and consequently the FISH function will not be called. When the reference gap is zero, the notional surfaces coincide with the piece surfaces.

Force-Displacement Law

The contact state information is fed into the specified FISH function during the force-displacement law computation. The nine values are, in this order:

  • contact pointer
  • relative linear displacement in the local coordinate system
  • relative angular displacement in the local coordinate system
  • curvature of the first piece
  • curvature of the second piece
  • inertial mass
  • contact gap
  • fail flag
  • activated flag

For balls and pebbles, the curvature is the reciprocal of the radius. For wall facets, the curvature is 0. The default curvature for rigid blocks is the reciprocal of the enclosing sphere radius. If the rblock contact-resolution update-area command is given, then the curvature is the reciprocal of the equivalent sphere radius of the computed contact area. The fail flag is used to specify whether the contact can fail; this can be modified with the model solve elastic keyword. The activated flag is true for the first cycle that the contact is active. It is important to note that the contact force and moment are in the local contact coordinate system. In other words, the \(x\)-component of the contact force is in the contact normal direction. To convert quantities between the local and global coordinate systems in FISH, see contact.to.local and contact.to.global.

Energy Partitions

The FISH model does not support energy tracking. This must be done with the user-defined FISH function.

Properties

The properties defined by the FISH contact model are listed in the table below as a concise reference. See the Contact Properties section for a description of the information in the table columns. The mapping from the surface inheritable properties to the contact model properties is also discussed below.

Table 1: FISH Model Properties
Keyword Symbol Description Type Range Default Modifiable Inheritable
fish Model name
bond NA Bond state [-] BOOL {false,true} false YES NO
force NA Force (contact plane coord. system) VEC \(\mathbb{R}^3\) \(\mathbf{0}\) YES NO
moment NA Moment (contact plane coord. system) VEC \(\mathbb{R}^3\) \(\mathbf{0}\) YES NO
rgap \(g_r\) Reference gap [length] FLT \(\mathbb{R}\) 0.0 YES NO
stifft NA Effective translational stiffness VEC \(\mathbb{R}^2\) \(\mathbf{0}\) YES NO
stiffa NA Effective rotational stiffness VEC \(\mathbb{R}^2\) \(\mathbf{0}\) YES NO
symbol NA FISH symbol name STR NA NA YES NO

Note

Out-of-balance forces acting on bodies are accumulated during force-displacement calculations.

Methods

The FISH model does not support methods.

Callback Events

Table 2: FISH Model Callback Events
Event Array Slot Value Type Range Description
contact_activated Contact has become active
  1 C_PNT N/A Contact pointer

Usage and Verification Examples

The tutorial “FISH Contact Model” demonstrates the use of the FISH contact model to implement a simple linear force-displacement law behavior.

to do items below

Model Summary

An alphabetical list of the FISH model properties is given here.