Scene

The Scene is the place where nodes live and work. It takes care of all the book-keeping such as saving and loading, adding, deleting, selecting, copying, sorting and more.

When working with the GUI this all happens in the background. If you are not into programming or scripting DAVE then it is sufficient to know that the Scene is the world.

The remainder of this section will be about working with a scene from python.

Creating

An empty Scene is constructed using its constructor. Typically a scene is named s

s = Scene()

A scene can also be created as a copy of another scene, from a file or from python code by passing these as arguments to the constructor.

To deep-copy a scene and all the nodes in it use:

s2 = s.copy()

General

method
clear	empties the scene
load_scene	loads a scene from file
save_scene	saves a scene to file
print_node_tree	prints the node tree to screen
run_code ( code )	This is the method that is used by the GUI to modify the nodes in the scene. When working from python directly it is unlikely that it is needed. executes the given python code with the scene itself aliased as s and all imports from DAVE and DAVE_ADDITIONAL_RUNTIME_MODULES present as locals.

Node names and getting a node

Nodes are stored in the scene. A reference to a specific node can be obtained using its name. This is why node names need to be unique.

To get a reference to a node use one of the following methods.

Code	Does
s[‘node name’]	returns a node with that name
node_by_name	returns a node with that name

The following functions can be used to check availability of node names:

Node name functions
assert_name_available name_available	asserts that a given name is not yet in use
node_names	list of node names
available_name_like (string )	returns the requested name if it is available, otherwise it returns something similar.
node_exists ( node or name)	This function is useful to check if a node reference is still valid (the node may have been deleted in the meantime)

Typical uses:

point = s['Point 1']

new_point_name = s.available_name_like('Point')

for circle in s.nodes_of_type(Circle):
    print(node.name)  
   
ice = s['ice']
s.delete('ice')
s.node_exists(ice) # --> False, node is not in the scene anymore
    

Getting multiple nodes

There are some convenience functions for getting groups of nodes meeting certain criteria.

The most complete one is

nodes_where which accepts the following arguments:

argument		does
name	string	filters on name, accepts wildcards (see fnmatch)
kind	Class	defines the node type to be instances of the given base type(s)
tag	string	defines the tag to match the provided tag(s). Wildcards allowed, Multiple tags may be supplied when separated in string using ,
managed	bool or none	nodes that are managed (true), unmanaged (false) or either (None)
family_of	node with parent	nodes that share a common ancestor (parent) with the given node
on	node	nodes are a child of the given node (note: may be completely free to move if intermediate degrees of freedom are present)
core_connected_to	Node	nodes have a dependency connection in the core (can not exist without). For example cables to points. (*1)
fixed_to	Node or “world”	node will not move relative to provided node (if Node supplied) or World (if world is supplied) Note: the node itself is excluded

Footnote 1:

• Consider two frames connected by a connector, the connector depends on both of the frames, but the frames themselves do not depend on each-other even though they are physically connected. So nodes core_connected_to=Frame1 will only return the connector and not Frame2.

Examples:

nodes = s.nodes_where(name='*demo*')  # all nodes with "demo" in name

# all buoyancy nodes that are rigidly connected to node 'Vessel'
nodes = s.nodes_where(kind = Buoyancy,
                      fixed_to = s['Vessel'])

# all cables connected to a point
nodes = s.nodes_where(kind = Cable,
                      core_connected_to = s['anchor_point'])

You may also directly use one of the following:

method	does
using tags
nodes_tagged ( tag )	Returns a list of all nodes with a given tag
nodes_tag_and_type ( tag , type )	Returns all nodes of type ‘type’ with tag ‘tag’
using type
nodes_of_type	returns all nodes of a certain (base) class or classes.
using managers
unmanged_nodes	Returns a tuple containing references to all nodes that do not have a manager
managed_nodes	Returns a tuple containing references to all nodes that do have a manager

Documentation

Documentation of node properties is build into DAVE and is used by different parts of the GUI as well as the reporting modules.

method	does
give_properties_for_node ( node )	returns the names of all documented properties of the given node
give_documentation ( node , property )	returns a NodePropertyInfo object

Example uses:

s = Scene()
p = s.new_point('point')

for prop in s.give_properties_for_node(p):
    print('----')
    print(prop)
    docs = s.give_documentation (p, prop)
    print(docs.doc_long)

Sorting and dependencies

These are mainly for internal bookkeeping and used for exporting to file or python code.

method	does
sort_nodes_by_parent	Sorts the nodes such that the parent of this node (if any) occurs earlier in the list.
sort_nodes_by_dependency	Sorts the nodes such that a nodes creation only depends on nodes earlier in the list.
get_created_by_dict	Returns a dictionary containing the nodes created by each manager.
get_implicitly_created_nodes	Returns a list of nodes that are created by a manager
nodes_managed_by	list of nodes directly managed by
nodes_depending_on	dependencies by creation order
node_A_core_depends_on_B_core	faster version by only works on core-connected nodes.
common_ancestor_of_nodes	checking if nodes are family
nodes_with_parent	all children
nodes_with_dependencies_in_and_satifsfied_by	for copying branches

Tags

Managing tags of nodes. See tags

method	does
nodes_tagged	all nodes with given tag
nodes_tag_and_type	all nodes of a given type with given tag
delete_tag	removes given tag from all nodes
tags	all tags in the scene

Checks

Some self-checks. Used internally but can be useful for debugging.

method	does
assert_unique_names	Asserts that all names are unique
assert_no_external_managers	Asserts that the managers of all nodes are also present in the Scene

Resources and packaging

See resources

method	does
add_resources_paths	adds a path to the resources system for this scene
current_directory	gets / sets the current directory
is_valid_resource_path	checks if a url is valid
get_resource_path	retrieves the full path to a resource url
get_used_resources	obtains a list of all resources required by the current scene.
get_resource_list	returns a list with all available resources of a given extension
create_standalone_copy load_package	create or load a stand-alone DAVE package including all resources.
obfuscate_names	renames all nodes to random names

Environmental settings

The following settings control the environment of the Scene:

setting	does
g	gravity in [\(kg \cdot m / s^2\)]
rho_water rho_air	densities in [\(t / m^3 \)]
wind_velocity current_velocity	wind and current velocity [m/s]
wind_direction current_direction	wind and current direction, going to [deg]. Direction 0 means flowing in the direction of the global x-axis, 90 is along global y axis.
waterlevel	Water-levels other than 0 are not supported yet

Direction conversions

Compass, coming from	Mathematical from	DAVE (mathematical TO)
0 (North)	90	270
90 (East)	0	180
180 (South)	270	90
270 (West)	180	0
\(D_{compass,from} = 270- D_{DAVE}\)		\(D_{DAVE} = 270 - D_{compass, from}\)

Checking degrees of freedom

To check if a node is fixed to another node or the world, we have to verify that all the intermediate nodes are fixed as well. This can be done using the following functions

Method	Does
node_is_fully_fixed_to_world	Returns true if this node will never move
node_is_fully_fixed_to	Returns true if node is fully fixed to another node

Duplicating branches

Mainly for GUI use.

Method	Does
duplicate_node	Duplicates a node
duplicate_branch	Duplicates a branch (family or nodes)

Deleting and dissolving

Deleting a node or dissolving a nodes. See dissolving and flattening

method	does
delete	deletes a node and its dependencies
dissolve	tries to dissolve a node
delete_empty_frames_and_bodies	deletes all obsolete frames and bodies
flatten (experimental, may fail)	dissolves as much as possible

Solving and state

The state is the values of all free degrees of freedom. Solving a scene adjusts the state such that the model is in an equilibium.

method	does
solve_statics	Solves statics
update	Updates the interface between the nodes and the core. This includes the re-calculation of all forces, buoyancy positions, ballast-system cogs etc
verify_equilibrium	checks that the current state is an equilibrium state
goal_seek	goal seeks a property to a value
plot_effect	plots the effect of a property on another property
state	gets the state
get_free_frame_state_dict	gets the state as a dictionary
maximum_relative_rotation	compares the current state to a given reference state and compares the rotations

Node renaming and changing

Node names can be changed in the node itself: s['old_name'].name = "new name"

method	does
prefix_element_names	applies a prefix to all nodes.
to_frame	converts a rigidbody to a frame
to_rigidbody	converts a frame to a rigidbody
insert_frame_before	inserts a frame before this frame and sets it as parent of this frame

Exporting

method	does
export_points_to_csv	Writes the names and global positions of all points to a comma separated file. Used for example for importing points into CAD programs

Dynamics

M and K are the inertia and stiffness matrices of the system. The rows/column correspond to the degrees of freedom of nodes and modes. So M[i,i] is the inertia of node nodes[i] in mode modes[i].

method	does
dynamics_M	returns the inertia matrix based on the inertia of the nodes. Does not include added mass from hydrodynamic databases.
dynamics_K	returns the stiffness matrix for the degrees
dynamics_nodes	nodes for indices
dynamics_modes	modes for indices