# 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.

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

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.

Was this helpful? ... | PFC © 2021, Itasca | Updated: Feb 25, 2024 |