Summary of Fundamentals#
This section is a quick and abstract deep dive into DAVEs structure and terminology. If you understand it then you have probably worked with similar software before and it will help you to quickly understand the depths of the program.
If you do not then no problem. Just skip though and maybe come back later. All the things that are summarized below will be explained in more detail in the remaining sections of this chapter.
Terminology and structure#
A DAVE model contains objects in a world. These objects have properties and can have a relation to each-other.
If you happen to know what a “Scene graph” is then is it good to know that DAVE uses a scene graph. If you do not know what it is then do not worry, it is a common concept in computer and data science that DAVE borrows its terminology from.
A Scene is a collection of Nodes. A single Node represents a single element of the model, for example a point or a cable. Multiple nodes together can be used to represent larger objects such as ships or lifting beams.
Nodes within a Scene are organized in a tree structure. A node may have one or more children but can only have a single parent.
The nifty thing is that children determine their position based on the position of their parent. If their parent moves or rotates the child moves with it. Geometrically children are connected to their parents. Forces work in the other direction. A force on a child is passed onto its parent via that same connection.
All nodes on the same branch are a family. The top-most node (grandest parent) is the root node of that branch.
Connectors#
Elastic connections between can physically connect members from different families. The connector nodes themselves are not part of any of the families but do depend on the nodes they connect.
Properties#
The properties of a node can be settable or read-only. Sometimes the same property is exposed in multiple ways. For example, the mass of a cable node can be specified by setting the mass or by setting the mass-per-length. But only the mass-per-length is a real property. Mass is a derived property which is calculated from the length and the mass-per-length. If the length of the cable is changed then the mass-per-length will stay the same but the total mass will change.
Another example is the global position of a node. The global position is derived from the local position and the transform of the nodes parent. Setting the global position will update the local position such that the global position matches the set value.
There can also be aliases. That are properties with different names controlling the same physical property. Examples are x and position. Position is a vector (x,y,z) and x is just the x-component. This is just for convenience.
Geometry#
The geometry and degrees of freedom are defined using kinematic trees where the rigid bodies are Frame nodes and the joints are defined by freeing degrees of freedom of a frame.
The geometry of a Scene is made using Frame nodes. Each frame node has a position, an orientation and optionally a parent. If a Frame node has no parent then the position and orientation are in the global axis system. If the node has a parent, its position and orientation are in the reference frame (local axis system) of the parent node.
Each Frame node has a position (x,y,z) and an orientation (rx, ry, rz) vector. The definition used for rotations is the rotation vector. Here the direction of the vector defines the axis of rotation while the length of the vector defines the angle in degrees.
Joints and degrees of freedom#
The three individual components of the position can either be fixed or free. If set to free then it becomes a degree of freedom or DOF. This means that the static solve is allowed to move the frame in that direction to find an equilibrium position.
Setting x to free creates a
sliderin x-direction.Setting y and z to free creates a frame that can move in both y and z directions.
For the orientation it is allowed to have the following combinations:
all three components fixed
all three components free: this creates a
balljointone of the components free and the other two fixed to zero. This creates a
hinge.
If a hinge about a non-principal axis is required then an intermediate frame (a frame between the hinge and its parent) is needed with a non-zero rotation.
Equilibrium#
Frame nodes define the geometry of the model while the other nodes apply forces to those frames. The forces may be position or orientation dependent.
Equilibrium is reached when the summation of forces and moment for each of the degrees of freedom is below a given tolerance.
Equilibrium may not exist. For example, a block with a weight but not connected to anything fill fall down forever. Same for a cart on a slider with a fixed force on it.
Equilibrium may not be unique. It is very well possible for multiple or even infinite equilibrium positions to exist. For example, a block with a mass on a horizontal slider is in equilibrium for any position on the slider. Or a block suspended on a single wire.
Groups, managers and dissolving#
The most fundamental nodes are kept as simple as possible. For example a Point node contains only a location and a Visual node contains only a visual. This means that often multiple nodes are needed to create something physical such as a shackle. In such cases a super-node may be used. A super-node is basically a group of nodes that, together, model something typical.
In this case the Shackle node manages the nodes below it. The Shackle (1) is a Body node with a position, orientation, cog and weight. pin_point, bow_point and inside_circle_center (2) are Point nodes and model three position on the shackle. Pin, bow and inside are three circle nodes that have the three point nodes as parent. They model circles around their parent points. Finally visual attaches a visual to the shackle. This is just for beauty. The nodes that are green (all expect Shackle) are managed by Shackle. The user can not change their properties directly. Their properties are controlled by their Manager. The user can simply select the type of shackle (e.g. Wide-Body 300t) and the manager will adjust the positions, radii and visual accordingly.
The user can dissolve managers. This evaporates the management structure and allows the user to change or even delete the individual nodes directly. But this also means that the way to control the shackle type via the manager is lost. The collection of nodes that that used to be a shackle is now just a normal collection of nodes.
Dissolving is a destructive operation. It removes information from the model as it cuts the implicit link between the nodes. The information that the nodes represent a shackle is lost. After dissolving they are just a group of nodes.
Deleting and dissolving#
When a node is deleted, all nodes depending on it are deleted as well. Sometimes a node can be dissolved. Dissolving involves removing a node from a model while keeping the rest of the model the same. Dissolving removes information from the model without physically changing it.
Limits#
Limits can be assigned to properties of nodes that have a single, numerical value. If a limit is defined then a unity check UC is given based on the actual value of that property divided by the limit. If multiple limits are defined for a single node, then the one resulting in the highest UC determines the governing UC
Time-line or load-cases#
A Scene can contain a Timeline. A timeline is can be used to define a number of discrete steps or load-cases. Different values for properties of the nodes can be defined for each step of the time-line or load-case.
Time-lines can be used for animations or load-cases.
Watch#
A Watch is a snippet of python code that can be evaluated to yield some text or number. This is used for feedback to the user or client only. A watch is defined on a node and can refer to that node as self. Similarly the scene is aliased with s. For example, "{self.tension / s.g:.3f}t" on a cable will evaluate to the tension divided by the gravity resulting in the cable tension in tons.
Reports, Sections and Analysis(Sections)#
Each Scene can have zero or more Reports.
Each Report can have zero or more Sections
Each section can do something with the Scene. For example present a table of all the masses in the model or make a 3d render of the model.
When a report is produced, the sections are executed and their results are combined into a pdf report.
Sections can also produce a section_result which is a Scene. Typically this is a copy of the original scene with some modifications. This section result is passed onto the next section in the report.
The result of a report is only saved as pdf. It is not possible to buffer the intermediate results. This ensures that there is never a mismatch between intermediate results and the model.
Analysis#
A Scene represents a single equilibrium state of a model.
Many practical problems can be engineered by analyzing a series of model variations or load-cases. Or by goal-seeking a property of the model (optimization).
This is what a typical analysis section does: It makes a copy of the model, performs a variation study on it and presents the results.
For example a hydrostatic stability section calculates the equilibrium positions of a system under a range of heel angles and from that derives the stability curves.
A rigging analysis section performs length, cog, weight, crane block height and friction variations and report the occurring loads from the governing situations.
A mooring analysis goal-seeks the wind-speed such that the highest unity check in a model is 1.0. And repeats this for a range of wind directions and broken line cases.
Resources#
Some information is stored in external files. Example are visuals, meshes, hydrodynamic databases and standard components.
DAVE uses a resources system to flexibly locate these resources without having to use global paths. A resource url stating with res: is supposed to be present in or relative to one of the defined resources folders. For example res: cheetah/tanks/sb1.stl. The paths on the resources system are ordered.
Environment#
The Scene itself has properties defining the environment such as wind, current, gravity and water density.