Tree Class Reference

A structure holding and managing all data connected to the tree used in the ADDIRRT* algorithm. More...

#include <RobotComponents/components/MotionPlanning/Tasks/AdaptiveDynamicDomainInformedRRTStar/Tree.h>

Classes

struct  NodeType
 Represents a node of thr rrt. More...
 

Public Types

using ConfigType = VectorXf
 The type of configurations.
 
using PendingUpdateLookuptableConstIterator
 Const iterator for the PendingUpdateLookuptable.
 
using PendingUpdateLookuptableIterator = typename PendingUpdateLookuptableType::iterator
 Iterator for the PendingUpdateLookuptable.
 
using PendingUpdateLookuptableType
 Lookuptable for pending updates.
 

Public Member Functions

void addGoalReached (const NodeId &goal, float costToGoToGoal)
 Adds a node to the list of nodes that can reach the goal configuration.
 
NodeId addNode (ConfigType cfg, const NodeId &parent, float fromParentCost)
 Adds a node to the tree.
 
void addPendingUpdate (const Update &u)
 Adds a new update to the list of pending updates.
 
void applyPendingUpdates ()
 Applies all pending updates.
 
template<class LockType, class RemoteUpdateGetter>
void applyPendingUpdates (LockType &&treeLock, RemoteUpdateGetter getRemoteUpdate)
 The same as applyPendingUpdates(LockType, RemoteUpdateGetter, UpdateConsumer) but uses an noop as updateConsumer This overload is needed since the defaultparameter does not work.
 
template<class LockType, class RemoteUpdateGetter, class UpdateConsumer>
void applyPendingUpdates (LockType &&treeLock, RemoteUpdateGetter getRemoteUpdate, UpdateConsumer updateConsumer=[](Update &&) {})
 Applies all pending updates.
 
void applyUpdate (const Update &u)
 Applies the given update.
 
NodeType & at (const NodeId &id)
 
const NodeType & at (const NodeId &id) const
 
NodeType & at (std::size_t index)
 
const NodeType & at (std::size_t index) const
 
bool canApplyUpdate (const Update &u)
 
void decreaseRadius (const NodeId &id)
 Decreases a node's radius.
 
const Ice::LongSeq & getAppliedUpdateIds () const
 
float getBestCost () const
 
PathWithCost getBestPath () const
 
const Update & getCurrentUpdate () const
 
Ice::Long getCurrentUpdateId () const
 
FullIceTree getIceTree () const
 
NodeId getIdOfIndex (std::size_t index) const
 
std::vector< std::pair< NodeId, float > > getKNearestNeighboursAndDistances (const ConfigType &cfg, std::size_t k)
 
const std::deque< Update > & getLocalUpdates () const
 
std::pair< NodeId, float > getNearestNeighbourAndDistance (const ConfigType &cfg)
 
NodeId getNextNodeIdFor (std::size_t workerId)
 
NodeType & getNode (const NodeId &id)
 
const NodeType & getNode (const NodeId &id) const
 
const std::deque< std::deque< NodeType > > & getNodes () const
 
float getNthPathCost (std::size_t n) const
 
NodeIdList getNthPathIds (std::size_t n) const
 
PathWithCost getNthPathWithCost (std::size_t n) const
 
std::size_t getPathCount () const
 
const Update & getPendingUpdate (std::size_t workerId, std::size_t updateId) const
 
Ice::Long getPreviousUpdateId () const
 
bool hasAppliedUpdate (std::size_t workerId, Ice::Long updateId)
 
bool hasGoalNode (const NodeId &nodeId) const
 
bool hasPendingUpdate (std::size_t workerId, std::size_t updateId) const
 
void increaseRadius (const NodeId &id)
 Increases a node's radius.
 
void increaseWorkerCountTo (std::size_t count)
 Increases the storage of all data structures to be appropriate for count workers.
 
void init (const FullIceTree &iceTree, AdaptiveDynamicDomainParameters newaddParams, std::size_t newWorkerId)
 Initailizes the tree from the given tree.
 
template<class LockType, class RemoteUpdateGetter, class UpdateConsumer>
void prepareUpdate (Ice::LongSeq dependetOnUpdateIds, LockType &&treeLock, RemoteUpdateGetter getRemoteUpdate, UpdateConsumer updateConsumer)
 Prepares an update by applying all dependet on updates.
 
void sendCurrentUpdate (TreeUpdateInterfacePrx &prx)
 Sends the current update to the given proxy.
 
void setNodeParent (const NodeId &child, const NodeId &newParent, float fromParentCost)
 Sets the parent node of child to parent.
 
std::size_t size () const
 
 Tree ()=default
 Default ctor.
 
 Tree (const VectorXf &startCfg)
 Creates a tree that can be used to analyze and apply updates.
 

Static Public Attributes

static const NodeId ROOT_ID {0, 0}
 The root node's id.
 

Protected Member Functions

void applyGoalReachedUpdates (const GoalInfoList newGoalNodes)
 Applies multiple goal reached updates to the tree.
 
void applyNodeCreationUpdate (const NodeCreationUpdate &u, std::size_t workerId)
 Applies a node creation update to the tree.
 
template<class LockType, class RemoteUpdateGetter, class UpdateConsumer>
void applyPendingUpdate (std::size_t updateIndex, LockType &&treeLock, RemoteUpdateGetter getRemoteUpdate, UpdateConsumer updateConsumer)
 Applies one pending update from the list of pending updates.
 
void applyRadiusUpdate (const RadiusUpdate &u)
 Applies a radius update to the tree.
 
void applyRewireUpdate (const RewireUpdate &rewireUpdate)
 Applies a rewire update to the tree.
 
void createNewGoalReachedUpdate (const NodeId &goal, float costToGoToGoal)
 Adds a new goal reached update to the current update.
 
void createNewNodeCreationUpdate (const ConfigType &cfg, const NodeId &parent, float fromParentCost)
 Adds a new node creation update to the current update.
 
void createNewRadiusUpdate (const NodeId &id, bool increaseRadius)
 Adds a new radius update to the current update.
 
void createNewRewireUpdate (const NodeId &child, const NodeId &newParent, float fromParentCost)
 Adds a new node creation update to the current update.
 
void doAddGoalReached (const NodeId &goal, float costToGoToGoal)
 Adds a node to the list of nodes that can reach the goal configuration.
 
NodeId doAddNode (ConfigType cfg, const NodeId &parent, float fromParentCost, std::size_t workerId)
 Adds a node to the tree.
 
void doDecreaseRadius (const NodeId &id)
 Decreases a node's radius.
 
void doIncreaseRadius (const NodeId &id)
 Increases a node's radius.
 
void doSetNodeParent (const NodeId &child, const NodeId &newParent, float fromParentCost, bool updateFromStartCost=true)
 Sets the parent node of child to parent.
 
PendingUpdateLookuptableIterator findPendingUpdate (std::size_t workerId, std::size_t updateId)
 
PendingUpdateLookuptableConstIterator findPendingUpdate (std::size_t workerId, std::size_t updateId) const
 
std::deque< GoalInfo >::const_iterator getBestCostIt () const
 
Update & getCurrentUpdateNonConst ()
 
VectorXfSeq getPathTo (NodeId id) const
 
void prepareNextUpdate ()
 Prepares the next update.
 
void pushCosts (const NodeId &root)
 Updates fromStartCosts for all children from root.
 

Protected Attributes

AdaptiveDynamicDomainParameters addParams
 The parameters of adaptive dynamic domain)
 
Ice::LongSeq appliedUpdateIds
 List of ids of applied updates.
 
std::deque< GoalInfo > goalNodes
 List of nodes able to reach the goal configuration.
 
std::deque< Update > localUpdates
 Updates created by this tree.
 
std::size_t nodeCount
 The number of nodes in the rrt.
 
std::deque< std::deque< NodeType > > nodes
 Holds all nodes.
 
std::deque< Update > pendingUpdates
 Updates to apply to the tree.
 
PendingUpdateLookuptableType pendingUpdatesLookupTable
 Speeds up lookup for available updates.
 
std::size_t workerId
 The worker id of this trees owner.
 

Detailed Description

A structure holding and managing all data connected to the tree used in the ADDIRRT* algorithm.

Function overview: [public ] applyXYZUpdate(XYZUpdate u): applies an existing update u to the tree [protected] createNewXYZUpdate(...) : creates a new update and adds it to the tree's current update [public ] addNode/{in,de}creaseRadius/setNodeParent/addGoalReached: modifies the tree (through do functions) and adds the corresponding update to the local tree [protected] doXYZ: performs the actual modification of the tree

Member Typedef Documentation

◆ ConfigType

using ConfigType = VectorXf

The type of configurations.

◆ PendingUpdateLookuptableConstIterator

Initial value:
typename PendingUpdateLookuptableType::const_iterator

Const iterator for the PendingUpdateLookuptable.

◆ PendingUpdateLookuptableIterator

using PendingUpdateLookuptableIterator = typename PendingUpdateLookuptableType::iterator

Iterator for the PendingUpdateLookuptable.

◆ PendingUpdateLookuptableType

Initial value:
std::unordered_map<std::pair<std::size_t, std::size_t>, std::size_t>

Lookuptable for pending updates.

Constructor & Destructor Documentation

◆ Tree() [1/2]

Tree ( )
default

Default ctor.

◆ Tree() [2/2]

Tree ( const VectorXf & startCfg)

Creates a tree that can be used to analyze and apply updates.

Other operations are undefined.

Parameters
startCfgThe start config.

Member Function Documentation

◆ addGoalReached()

void addGoalReached ( const NodeId & goal,
float costToGoToGoal )
inline

Adds a node to the list of nodes that can reach the goal configuration.

(creates an appropriate update)

Parameters
goalThe node to add.
costToGoToGoalThe cost to reach the gol configuration from the given node.

◆ addNode()

NodeId addNode ( ConfigType cfg,
const NodeId & parent,
float fromParentCost )

Adds a node to the tree.

(creates an appropriate update)

Parameters
cfgThe node's configuration.
parentThe node's parent.
fromParentCostThe cost of the edge (node, parent)
Returns
The new node's id.

◆ addPendingUpdate()

void addPendingUpdate ( const Update & u)

Adds a new update to the list of pending updates.

Parameters
uThe update.

◆ applyGoalReachedUpdates()

void applyGoalReachedUpdates ( const GoalInfoList newGoalNodes)
inlineprotected

Applies multiple goal reached updates to the tree.

Parameters
newGoalNodesThe new nodes that can reach the goal configuration.

◆ applyNodeCreationUpdate()

void applyNodeCreationUpdate ( const NodeCreationUpdate & u,
std::size_t workerId )
inlineprotected

Applies a node creation update to the tree.

Parameters
uThe update.
workerIdThe updates source worker.

◆ applyPendingUpdate()

template<class LockType, class RemoteUpdateGetter, class UpdateConsumer>
void applyPendingUpdate ( std::size_t updateIndex,
LockType && treeLock,
RemoteUpdateGetter getRemoteUpdate,
UpdateConsumer updateConsumer )
inlineprotected

Applies one pending update from the list of pending updates.

Parameters
updateIndexThe pending update's index.
treeLockThe lock used to protect the update structures. It will be unlocked when getting a remote update.
getRemoteUpdateFunction used to request a missing update.
updateConsumerFunction used to consume updates after they were added. (will be moved to the consumer)

◆ applyPendingUpdates() [1/3]

void applyPendingUpdates ( )
inline

Applies all pending updates.

Updates are not consumes. If a required update is missing this methode will fail. (no update getter is providet). This function is not thread save! Use it only in a serial/protected environment.

◆ applyPendingUpdates() [2/3]

template<class LockType, class RemoteUpdateGetter>
void applyPendingUpdates ( LockType && treeLock,
RemoteUpdateGetter getRemoteUpdate )
inline

The same as applyPendingUpdates(LockType, RemoteUpdateGetter, UpdateConsumer) but uses an noop as updateConsumer This overload is needed since the defaultparameter does not work.

Parameters
getRemoteUpdateFunction used to request a missing update.
See also
Tree::applyPendingUpdates

◆ applyPendingUpdates() [3/3]

template<class LockType, class RemoteUpdateGetter, class UpdateConsumer>
void applyPendingUpdates ( LockType && treeLock,
RemoteUpdateGetter getRemoteUpdate,
UpdateConsumer updateConsumer = [](Update&&) {} )
inline

Applies all pending updates.

Parameters
treeLockThe lock used to protect the update structures. It will be unlocked when getting a remote update.
getRemoteUpdateFunction used to request a missing update.
updateConsumerFunction used to consume updates after they were added. (will be moved to the consumer)

◆ applyRadiusUpdate()

void applyRadiusUpdate ( const RadiusUpdate & u)
protected

Applies a radius update to the tree.

Parameters
uThe update.

◆ applyRewireUpdate()

void applyRewireUpdate ( const RewireUpdate & rewireUpdate)
protected

Applies a rewire update to the tree.

Parameters
rewireUpdateThe update.

◆ applyUpdate()

void applyUpdate ( const Update & u)

Applies the given update.

Parameters
uThe update.

◆ at() [1/4]

NodeType & at ( const NodeId & id)
inline
Parameters
idThe node's id.
Returns
The requested node.

◆ at() [2/4]

const NodeType & at ( const NodeId & id) const
inline
Parameters
idThe node's id.
Returns
The requested node. (const)

◆ at() [3/4]

NodeType & at ( std::size_t index)
inline
Parameters
indexThe node's index.
Returns
The requested node.

◆ at() [4/4]

const NodeType & at ( std::size_t index) const
inline
Parameters
indexThe node's index.
Returns
The requested node. (const)

◆ canApplyUpdate()

bool canApplyUpdate ( const Update & u)
Parameters
uThe update.
Returns
Whether the given update can be applied.

◆ createNewGoalReachedUpdate()

void createNewGoalReachedUpdate ( const NodeId & goal,
float costToGoToGoal )
inlineprotected

Adds a new goal reached update to the current update.

Parameters
goalThe node that can reach the goal configuration.
costToGoToGoalThe cost to reach the goal configuration from the given node)

◆ createNewNodeCreationUpdate()

void createNewNodeCreationUpdate ( const ConfigType & cfg,
const NodeId & parent,
float fromParentCost )
inlineprotected

Adds a new node creation update to the current update.

Parameters
cfgThe new node's configuration.
parentThe new node's parent node.
fromParentCostThe cost of the edge (node, parent)

◆ createNewRadiusUpdate()

void createNewRadiusUpdate ( const NodeId & id,
bool increaseRadius )
inlineprotected

Adds a new radius update to the current update.

Parameters
idThe node's id.
increaseRadiusWhether the node's radius increases.

◆ createNewRewireUpdate()

void createNewRewireUpdate ( const NodeId & child,
const NodeId & newParent,
float fromParentCost )
inlineprotected

Adds a new node creation update to the current update.

Parameters
childThe rewired child node.
newParentThe new parent node.
fromParentCostThe cost of the edge (child, new parent)

◆ decreaseRadius()

void decreaseRadius ( const NodeId & id)
inline

Decreases a node's radius.

(creates an appropriate update)

Parameters
idThe node.

◆ doAddGoalReached()

void doAddGoalReached ( const NodeId & goal,
float costToGoToGoal )
inlineprotected

Adds a node to the list of nodes that can reach the goal configuration.

Parameters
goalThe node to add.
costToGoToGoalThe cost to reach the gol configuration from the given node.

◆ doAddNode()

NodeId doAddNode ( ConfigType cfg,
const NodeId & parent,
float fromParentCost,
std::size_t workerId )
protected

Adds a node to the tree.

Parameters
cfgThe node's configuration.
parentThe node's parent.
fromParentCostThe cost of the edge (node, parent)
workerIdThe worker creating this node.
Returns
The new node's id.

◆ doDecreaseRadius()

void doDecreaseRadius ( const NodeId & id)
protected

Decreases a node's radius.

Parameters
idThe node.

◆ doIncreaseRadius()

void doIncreaseRadius ( const NodeId & id)
inlineprotected

Increases a node's radius.

Parameters
idThe node.

◆ doSetNodeParent()

void doSetNodeParent ( const NodeId & child,
const NodeId & newParent,
float fromParentCost,
bool updateFromStartCost = true )
protected

Sets the parent node of child to parent.

(costs are updated)

Parameters
childThe cild node.
newParentThe new parent node.
fromParentCostThe cost of the edge (child, new parent)
updateFromStartCostWhether to update the costs of the subtree beneath cild.

◆ findPendingUpdate() [1/2]

PendingUpdateLookuptableIterator findPendingUpdate ( std::size_t workerId,
std::size_t updateId )
inlineprotected
Parameters
workerIdThe update's worker.
updateIdThe update's sub id.
Returns
An iterator tho the pending update. (If it does not exist to end.)

◆ findPendingUpdate() [2/2]

PendingUpdateLookuptableConstIterator findPendingUpdate ( std::size_t workerId,
std::size_t updateId ) const
inlineprotected
Parameters
workerIdThe update's worker.
updateIdThe update's sub id.
Returns
An iterator tho the pending update. (If it does not exist to end.) (const version)

◆ getAppliedUpdateIds()

const Ice::LongSeq & getAppliedUpdateIds ( ) const
inline
Returns
List of ids of applied updates.

◆ getBestCost()

float getBestCost ( ) const
Returns
The cost of the shortest solution.

◆ getBestCostIt()

std::deque< GoalInfo >::const_iterator getBestCostIt ( ) const
inlineprotected
Returns
An iterator to the node that can reach the goal configuration and results in the lowest path cost. (end if no path was found)

◆ getBestPath()

PathWithCost getBestPath ( ) const
Returns
The path with the lowest cost.

◆ getCurrentUpdate()

const Update & getCurrentUpdate ( ) const
inline
Returns
The currently constructed update.

◆ getCurrentUpdateId()

Ice::Long getCurrentUpdateId ( ) const
inline
Returns
The update sub id of the current update. (The one currently constructed, not the last send)

◆ getCurrentUpdateNonConst()

Update & getCurrentUpdateNonConst ( )
inlineprotected
Returns
The currently constructed update. (non const version for internal use)

◆ getIceTree()

FullIceTree getIceTree ( ) const
Returns
The current RRT with all updates applied. (used to transmitt it through ice.)

◆ getIdOfIndex()

NodeId getIdOfIndex ( std::size_t index) const
Parameters
indexThe index.
Returns
The id corresponding to the given node index.

◆ getKNearestNeighboursAndDistances()

std::vector< std::pair< NodeId, float > > getKNearestNeighboursAndDistances ( const ConfigType & cfg,
std::size_t k )
Parameters
cfgThe configuration.
kThe number of neighbours.
Returns
The k nearest neighbours of and their distance to the given configuration.

◆ getLocalUpdates()

const std::deque< Update > & getLocalUpdates ( ) const
inline
Returns
Returns all updates send by this tree.

◆ getNearestNeighbourAndDistance()

std::pair< NodeId, float > getNearestNeighbourAndDistance ( const ConfigType & cfg)
inline
Parameters
cfgThe configuration.
Returns
The nearest neighbour of and its distance to the given configuration.

◆ getNextNodeIdFor()

NodeId getNextNodeIdFor ( std::size_t workerId)
inline
Parameters
workerIdThe worker's id.
Returns
The next node id for the given worker.

◆ getNode() [1/2]

Tree::NodeType & getNode ( const NodeId & id)
Parameters
idThe node's id.
Returns
The requested node.

◆ getNode() [2/2]

const Tree::NodeType & getNode ( const NodeId & id) const
Parameters
idThe node's id.
Returns
The requested node. (const)

◆ getNodes()

const std::deque< std::deque< NodeType > > & getNodes ( ) const
inline
Returns
All nodes.

◆ getNthPathCost()

float getNthPathCost ( std::size_t n) const
inline
Parameters
nThe paths index.
Returns
The cost of the given path.

◆ getNthPathIds()

NodeIdList getNthPathIds ( std::size_t n) const
Parameters
nThe path's index.
Returns
The node ids of nodes contained by the given path.

◆ getNthPathWithCost()

PathWithCost getNthPathWithCost ( std::size_t n) const
Parameters
nN
Returns
The nth path.

◆ getPathCount()

std::size_t getPathCount ( ) const
inline
Returns
The number of paths found.

◆ getPathTo()

VectorXfSeq getPathTo ( NodeId id) const
protected
Parameters
idThe node's id.
Returns
Returns a path to the requested node.

◆ getPendingUpdate()

const Update & getPendingUpdate ( std::size_t workerId,
std::size_t updateId ) const
inline
Parameters
workerIdThe update's worker id.
updateIdThe update's sub id.
Returns
Returns the requested update from the list of pending updates.

◆ getPreviousUpdateId()

Ice::Long getPreviousUpdateId ( ) const
inline
Returns
The update sub id of the last send update.

◆ hasAppliedUpdate()

bool hasAppliedUpdate ( std::size_t workerId,
Ice::Long updateId )
inline
Parameters
workerIdThe update's worker id.
updateIdThe update's sub id.
Returns
Whether the given update was applied.

◆ hasGoalNode()

bool hasGoalNode ( const NodeId & nodeId) const
inline
Parameters
nodeIdThe node to check.
Returns
Whether the given node is a node in the list of nodes able to reach the goal configuration.

◆ hasPendingUpdate()

bool hasPendingUpdate ( std::size_t workerId,
std::size_t updateId ) const
inline
Parameters
workerIdThe update's worker id.
updateIdThe update's sub id.
Returns
Whether the given update is in the list of pending updates.

◆ increaseRadius()

void increaseRadius ( const NodeId & id)
inline

Increases a node's radius.

(creates an appropriate update)

Parameters
idThe node.

◆ increaseWorkerCountTo()

void increaseWorkerCountTo ( std::size_t count)

Increases the storage of all data structures to be appropriate for count workers.

Parameters
countThe number of workers.

◆ init()

void init ( const FullIceTree & iceTree,
AdaptiveDynamicDomainParameters newaddParams,
std::size_t newWorkerId )

Initailizes the tree from the given tree.

Parameters
iceTreeThe tree to use as initial state.
newaddParamsThe new adaptive dynamic domain parameters.
newWorkerIdThe owner's worker id.

◆ prepareNextUpdate()

void prepareNextUpdate ( )
protected

Prepares the next update.

(the update to be send)

◆ prepareUpdate()

template<class LockType, class RemoteUpdateGetter, class UpdateConsumer>
void prepareUpdate ( Ice::LongSeq dependetOnUpdateIds,
LockType && treeLock,
RemoteUpdateGetter getRemoteUpdate,
UpdateConsumer updateConsumer )
inline

Prepares an update by applying all dependet on updates.

Parameters
dependetOnUpdateIdsThe ids of dependet on updates.
treeLockThe lock used to protect the update structures. It will be unlocked when getting a remote update.
getRemoteUpdateFunction used to request a missing update.
updateConsumerFunction used to consume updates after they were added. (will be moved to the consumer)

◆ pushCosts()

void pushCosts ( const NodeId & root)
protected

Updates fromStartCosts for all children from root.

Parameters
rootThe root node for the cost update.

◆ sendCurrentUpdate()

void sendCurrentUpdate ( TreeUpdateInterfacePrx & prx)

Sends the current update to the given proxy.

A new update is prepared afterwards.

Parameters
prxThe proxy to send the update to.

◆ setNodeParent()

void setNodeParent ( const NodeId & child,
const NodeId & newParent,
float fromParentCost )
inline

Sets the parent node of child to parent.

(costs are updated) (creates an appropriate update)

Parameters
childThe cild node.
newParentThe new parent node.
fromParentCostThe cost of the edge (child, new parent)

◆ size()

std::size_t size ( ) const
inline
Returns
The number of nodes in the tree.

Member Data Documentation

◆ addParams

AdaptiveDynamicDomainParameters addParams
protected

The parameters of adaptive dynamic domain)

◆ appliedUpdateIds

Ice::LongSeq appliedUpdateIds
protected

List of ids of applied updates.

◆ goalNodes

std::deque<GoalInfo> goalNodes
protected

List of nodes able to reach the goal configuration.

◆ localUpdates

std::deque<Update> localUpdates
protected

Updates created by this tree.

◆ nodeCount

std::size_t nodeCount
protected

The number of nodes in the rrt.

◆ nodes

std::deque<std::deque<NodeType> > nodes
protected

Holds all nodes.

The node nodes[i][j] is the jth node created by worker i.

◆ pendingUpdates

std::deque<Update> pendingUpdates
protected

Updates to apply to the tree.

◆ pendingUpdatesLookupTable

PendingUpdateLookuptableType pendingUpdatesLookupTable
protected

Speeds up lookup for available updates.

(O(log(n)) instead of O(n))

maps from UpdateId to the corresponding index in the pendingUpdates vector

◆ ROOT_ID

const NodeId ROOT_ID {0, 0}
static

The root node's id.

◆ workerId

std::size_t workerId
protected

The worker id of this trees owner.

(only used for sending updates and skipping updates send by this tree)


The documentation for this class was generated from the following files: