This is a list of Elle functions. It is not complete, and some functions may be out of date. But it is still very useful.
1 Initialisation functions
ElleInit
Synopsis: #include “init.h”
int ElleInit()
Description: Initialises the Elle data structures. This function must be called at the beginning of an Elle process.
Returns: 0 if successful( failure will cause the program to exit).
ElleReinit
Synopsis: #include “init.h”
int ElleReinit()
Description: Reinitialises data arrays and deletes attribute lists so that a new file can be read or a run restarted.
2 Update and display functions
ElleUpdateDisplay
Synopsis: #include “display.h”
void ElleUpdateDisplay()
Description: Updates the graphical display of the microstructure, using the settings shown in the Display->Set Options menu.
3 Topology functions
ElleCrossingsCheck
Synopsis: #include “crossings.h”
int ElleCrossingsCheck(int node, Coords *pos_incr);
Description: Determines whether boundary crossings result if the node is moved according to the data in pos_incr. If crossings are found the topology is altered to remove them.
Input: node Specifies the node to move.
pos_incr The distance and direction to move.
Returns: 0.
ElleCheckDoubleJ
Synopsis: #include “check.h”
int ElleCheckDoubleJ(int node)
Description: If the node is more than ElleMaxNodeDistance() from a neighbour, a new double node is inserted halfway along that boundary. If the node is less than ElleMinNodeDistance() from a neighbour, the node itself is deleted.
Input: node Specifies the node to be checked.
Returns: 0 if successful, else non-zero error number.
ElleCheckTripleJ
Synopsis: #include “check.h”
int ElleCheckTripleJ(int node)
Description: If the node is more than ElleMaxNodeDistance() from a neighbour, a new double node is inserted halfway along that boundary. If the node is less than ElleMinNodeDistance() from a triple junction neighbour, a “triple switch” is carried out.
Input: node Specifies the node to be checked.
Returns: 0 if successful or a non-zero error number.
4 File functions
ElleReadData
Synopsis: #include “file.h”
int ElleReadData(char *filename);
Description: Reads the Elle data from filename.
Input: filename The name of the file to be read (may include path).
Returns: 0 if successful else non-zero error number.
ElleWriteData
Synopsis: #include “file.h”
int ElleWriteData(char *filename)
Description: Writes the current Elle data to filename.
Input: filename The name of the file to be written (may include path).
Returns: 0 if successful else non-zero error number.
ElleAutoWriteFile
Synopsis: #include “file.h”
int ElleAutoWriteFile(int cnt)
Description: Creates a filename from the file “root” and the parameter cnt then calls ElleWriteData, eg if the root is set to test and cnt is 20, this function will call ElleWriteData(“test020.elle”).
Input: cnt The number of stages (to be incorporated into the file name).
Returns: 0 if successful else non-zero error number.
5 Flynn functions
ElleAddFlynnChild
Synopsis: #include “interface.h”
int ElleAddFlynnChild(int index, int child)
Description: Adds an entry to a flynn’s list of children if the child is not already in the list.
Input: index Specifies the parent flynn.
child Specifies the new child.
ElleCheckFlynnDefaults
Synopsis: #include “interface.h”
void ElleCheckFlynnDefaults(int id)
Description: Checks that active flynns, which do not have parents, have a value for this attribute.
Input: id Specifies the attribute.
ElleCleanFlynnArray
Synopsis: #include “interface.h”
void ElleCleanFlynnArray()
Description: Reinitialize all the flynns ie all inactive.
ElleDefaultFlynnRealAttrib
Synopsis: #include “interface.h”
double ElleDefaultFlynnRealAttribute(int id)
Description: The above functions return the default value for the flynn attribute.
Returns: The attribute value. The variable holding the return value should be of the correct type for the attribute.
ElleFindFlynnMinArea
Synopsis: #include “interface.h”
double ElleFindFlynnMinArea(int flynnindex)
Description: Retrieves the minimum area from the mineral database if the MINERAL attribute is active, else gets the global minimum flynn area value.
Input: flynnindex Specifies the flynn
Returns: the minimum flynn area.
ElleFindSpareFlynn
Synopsis: #include “interface.h”
int ElleFindSpareFlynn()
Description: Searches the flynns (low to high index) to find an inactive one.
Returns: The index of an inactive flynn.
ElleFlynnAttributeActive
Synopsis: #include “interface.h”
unsigned char ElleFlynnAttributeActive(int id)
Description: Determines whether the specified flynn attribute is active.
Input: id Specifies the attribute.
Returns: 1 if active, else 0.
ElleFlynnDfltAttributeList
Synopsis: #include “interface.h”
void ElleFlynnDfltAttributeList(int **active, int *maxa)
Description: Creates a list of the currently active flynn attributes. Memory is allocated for the array and should be released when no longer needed.
Output: active Array of attributes identifiers (see flynn attributes).
maxa The size of the array.
ElleFlynnHasAttribute
Synopsis: #include “interface.h”
unsigned char ElleFlynnHasAttribute(int index,int id)
Description: Determines whether the specified flynn has the attribute in its list (i.e. it has no parent or the value of the attribute differs from that of its parent).
Input: index Specifies the flynn.
id Specifies the attribute.
Returns: 1 if the attribute is found, else 0.
ElleFlynnIsActive
Synopsis: #include “interface.h”
unsigned char ElleFlynnIsActive(int index)
Description: Finds the state of a flynn.
Inputs: index Specifies the flynn.
Returns: True if the flynn is active else false.
ElleFlynnNbRegions
Synopsis: #include “interface.h”
void FlynnNbRegions(int index, list<int> &nbflynns)
Description: Creates a list of the flynns which share a boundary with the specified flynn. The flynns are ordered by the number of segments in the shared boundary, high to low.
Input: index Specifies the flynn.
nbflynns The list of neighbouring regions.
ElleFlynnNodeCount
Synopsis: #include “interface.h”
int ElleFlynnNodeCount(int index)
Description: Finds the number of nodes on the flynn boundary (ie num in ElleFlynnNodes).
Input: index Specifies the flynn.
Returns: The number of boundary nodes.
ElleFlynnNodes
Synopsis: #include “interface.h”
void ElleFlynnNodes(int index, int **ids, int *num)
Description: Finds the boundary nodes of a flynn. *num is set to the number of nodes. Ids is the list of node numbers and is allocated storage by a call to malloc(). A call to free(ids) must be made when the information is no longer required.
Input: index Specifies the flynn.
Output: ids Is set to the address of storage for the list of nodes.
num Is set to the number of nodes in the list.
ElleGetFlynnCAxis, ElleGetFlynnEuler3
Synopsis: #include “interface.h”
void ElleGetFlynnCAxis(int index, Coords_3D *valptr)
void ElleGetFlynnEuler3(int index, double *alpha, double *beta, double *gamma)
Description: The above functions get the value of a flynn attribute. If the attribute is not active or the flynn does not have the attribute the program will terminate. Always check using the functions ElleFlynnAttributeActive and ElleFlynnHasAttribute
Input: index Specifies the flynn.
Output: The attribute value. The variable holding the return value should be of the correct type for the attribute.
ElleGetFlynnIntAttribute
Synopsis: #include “interface.h”
void ElleGetFlynnIntAttribute(int index, int *valptr, int id)
Description: This function gets the value of an integer flynn attribute. If the attribute is not active or the flynn does not have the attribute the program will terminate. Always check using the functions ElleFlynnAttributeActive and ElleFlynnHasAttribute ElleGetFlynnIntAttribute accepts only integer attributes as the third parameter (see the section on Flynn Attributes).
Input: index Specifies the flynn.
id Specifies the attribute
Output: The attribute value. The variable holding the return value, valptr, should be of type integer.
ElleGetFlynnRealAttribute
Synopsis: #include “interface.h”
void ElleGetFlynnRealAttribute(int index, double *valptr, int id)
Description: This function gets the value of a real flynn attribute. If the attribute is not active or the flynn does not have the attribute the program will terminate. Always check using the functions ElleFlynnAttributeActive and ElleFlynnHasAttribute ElleGetFlynnIntAttribute accepts only real attributes as the third parameter (see the section on Flynn Attributes).
Input: index Specifies the flynn.
id Specifies the attribute
Output: The attribute value. valptr should be the address of a variable of type double.
ElleInitFlynnAttribute
Synopsis: #include “interface.h”
void ElleInitFlynnAttribute(int id)
Description: The attribute is added to the list of active attributes. Active flynns which do not have parents are given the default value for this attribute. If the attribute is already active, nothing is done.
Input: id Specifies the attribute.
ElleMaxFlynns
Synopsis: #include “interface.h”
int ElleMaxFlynns()
Description: Finds the total number of flynns, both active and inactive. This function is used when looping over the flynn array.
Returns: The number of flynns.
ElleMergeFlynns
Synopsis: #include “interface.h”
int ElleMergeFlynns(int keepflynn, int removeflynn)
Description: Merges the second flynn into the first by removing the longest common boundary. The merge will only be carried out if the flynns are both on the lowest level, have the same parent (or no parent) and have the same values for their integer attributes.
Input: index Specifies the flynn.
maxarea The maximum flynn area limit.
Returns: 1 if the flynns are merged, else 0.
ElleMergeFlynnsNoCheck
Synopsis: #include “interface.h”
int ElleMergeFlynnsNoCheck(int keepflynn, int removeflynn)
Description: Merges the second flynn into the first by removing the longest common boundary. The merge is forced with no checks. Only used for removing tiny flynns
Input: keepflynn Specifies the flynn to survive the merge.
removeflynn Specifies the flynn to be removed.
Returns: 1 if the flynns are merged, else 0.
ElleNucleateFlynnFromNode
Synopsis: #include “interface.h”
void ElleNucleateFlynnFromNode(int node, int *new)
Description: Creates a new flynn around the node by adding double nodes on the boundaries and joining these new nodes. The position of the original node is changed. The variable new returns the index of the new flynn.
Input: node Specifies the node.
Output: new Specifies the new flynn.
ElleNumberOfGrains
Synopsis: #include “interface.h”
int ElleNumberOfGrains()
Description: Counts the number of active flynns. This functions is used by the statistics routine for a microstructure without parent flynns (single level)
Returns: The number of active flynns.
ElleNumFlynnAttributes
EllePromoteFlynn
Synopsis: #include “interface.h”
void EllePromoteFlynn(int flynnindex)
Description: Raise the flynn one level in the hierarchy.
Input: flynnindex Specifies the flynn to be promoted.
ElleRemoveFlynn
Synopsis: #include “interface.h”
void ElleRemoveFlynn(int flynnindex)
Description: Makes a flynn inactive after removing it from the hierarchy. Assumes the attributes have been removed.
Input: flynnindex Specifies the flynn to be removed.
ElleRemoveFlynnAttribute
Synopsis: #include “interface.h”
void ElleRemoveFlynnAttribute(int index, int idval)
Description: Removes the attribute from the flynn’s attribute list. No action if the attribute is not in the list of the specified flynn.
Input: index Specifies the flynn.
idval Specifies the attribute.
ElleSetDefaultFlynnRealAttrib
Synopsis: #include “interface.h”
void ElleSetDefaultFlynnRealAttrib(double val,int id)
Description: Set the default value for a flynn attribute. Commonly called when the “Default” keyword occurs in an Elle file. Could also be used if a new attribute is initialised in a program and the program default value needs to be overridden.
Input: The value should be the correct type for the attribute.
ElleSetFlynnActive
Synopsis: #include “interface.h”
int ElleSetFlynnActive(int index)
Description: Makes a flynn active.
Inputs: index Specifies the flynn to be flagged as active.
ElleSetFlynnCAxis, ElleSetFlynnEuler3
Synopsis: #include “interface.h”
void ElleSetFlynnCAxis(int index, Coords_3D *val)
void ElleSetFlynnEuler3(int index, double alpha, double beta, double gamma)
Description: The above functions set the value of a flynn attribute. If the attribute is not active or the flynn does not have the attribute the program will terminate. Always check using the functions ElleFlynnAttributeActive and ElleFlynnHasAttribute.
Input: The attribute value(s). The variables should be of the correct number and type for the attribute.
ElleSetFlynnFirstNode
Synopsis: #include “interface.h”
void ElleSetFlynnFirstNode(int index, int first)
Description: Sets the value of the flynn’s first node (used to walk around the flynn).
Inputs: index Specifies the flynn.
first The node number of the first node.
ElleSetFlynnIntAttribute
Synopsis: #include “interface.h”
void ElleSetFlynnIntAttribute(int index, int val, int id)
Description: This function sets the value of an integer flynn attribute. If the attribute is not active or the flynn does not have the attribute the program will terminate. Always check using the functions ElleFlynnAttributeActive and ElleFlynnHasAttribute. ElleSetFlynnIntAttribute accepts only integer attributes as the third parameter (see the section on Flynn Attributes).
Input: index Specifies the flynn.
val The value for the attribute
id Specifies the attribute
ElleSetFlynnRealAttribute
Synopsis: #include “interface.h”
void ElleSetFlynnRealAttribute(int index, double val, int id)
Description: This function sets the value of a flynn attribute. If the attribute is not active or the flynn does not have the attribute the program will terminate. Always check using the functions ElleFlynnAttributeActive and ElleFlynnHasAttribute. ElleSetFlynnRealAttribute accepts only real attributes as the third parameter (see the section on Flynn Attributes).
Input: index Specifies the flynn.
val The value for the attribute
id Specifies the attribute
ElleSplitFlynn
Synopsis: #include “interface.h”
int ElleSplitFlynn(int index, int *child1, int *child2)
Description: Splits a flynn into 2 sub flynns by a random walk. The new flynns are children of the original flynn.
Input: index Specifies the flynn.
Ouput: child1, child2 Are set to the indices of the new flynns.
Returns: 0 if successful, else > 0.
ElleSplitFlynnandPromote
Synopsis: #include “interface.h”
int ElleSplitFlynnandPromote(int index, int *c1, int *c2)
Description: Splits a flynn into 2 sub flynns by a random walk. The new flynns are given the attributes of the original flynn which is then deleted.
Input: index Specifies the flynn.
Ouput: c1, c2 Are set to the indices of the new flynns.
Returns: 1 if successful, else 0.
ElleSplitFlynnChildrenOnArea
Synopsis: #include “interface.h”
void ElleSplitFlynnChildrenOnArea(int index, double maxarea)
Description: Attempts to split each child of a flynn by calling ElleSplitFlynnOnArea.
Input: index Specifies the flynn.
maxarea The maximum flynn area limit.
ElleSplitFlynnOnArea
Synopsis: #include “interface.h”
void ElleSplitFlynnOnArea(int type, int index, double dx, double dy)
Description: Attempts to split a flynn by recursively calling ElleSplitFlynnandPromote until all the new flynns have an area smaller than that set in the mineral database, if MINERAL attribute is active, or the global setting. dx, dy are used to control the direction of the split. If dx=dy=0, the function will generate a random vector to follow otherwise the flynn will be split in the direction specified by these parameters. The function will try the boundary nodes in turn until it can split the flynn in the specified direction with both new flynns having an area greater then the minimum area. The minimum area is taken from the mineral database, if MINERAL attribute is set, or from the global setting (see ElleSetFlynnMinArea())
Input: type type of walk, random (type=RANDOM) or directed (type=DIRECT)
index Specifies the flynn.
dx, dy Specify the walk direction
ElleSplitFlynnOnArea
Synopsis: #include “interface.h”
void ElleSplitFlynnOnArea(int type, int index, double maxarea, double dx, double dy)
Description: Attempts to split a flynn by recursively calling ElleSplitFlynnandPromote until all the new flynns have an area smaller than the specified limit. dx, dy are used to control the direction of the split. If dx=dy=0, the function will generate a random vector to follow otherwise the flynn will be split in the direction specified by these parameters. The function will try the boundary nodes in turn until it can split the flynn in the specified direction with both new flynns having an area greater then the minimum area. The minimum area is taken from the mineral database, if MINERAL attribute is set, or from the global setting (see ElleSetFlynnMinArea())
Input: type type of walk, random (type=RANDOM) or directed (type=DIRECT)
index Specifies the flynn.
maxarea The maximum flynn area limit.
dx, dy Specify the walk direction
ElleSplitWrappingFlynn
Synopsis: #include “interface.h”
int ElleSplitWrappingFlynn(int index, int node1, int node2, int *child1, int *child2)
Description: Splits a flynn into 2 sub flynns by a random walk starting on the shortest path from node1 to node2. The new flynns are given the attributes of the original flynn which is then deleted.
Input: index Specifies the flynn.
Ouput: child1, child2 Are set to the indices of the new flynns.
Returns: 0 if successful, else > 0.
ElleWriteFlynnPolyFile
Synopsis: #include “interface.h”
int ElleWriteFlynnPolyFile(int flynnid, char *fname)
Description: Writes the flynn nodes in poly file format to the file, fname. The node identifier is the last entry on the line. The file can be viewed with Triangle’s showme utility
Input: flynnid Specifies the flynn.
fname The output filename.
ElleWriteParentFlynn
Synopsis: #include “interface.h”
int ElleWriteParentFlynn(int index, FILE *fp)
Description: Used to write the list of child flynn numbers to an Elle file.
Input: index Specifies the parent flynn.
fp Pointer to the FILE structure of the output file.
Returns: 0 if successful, non-zero error number on failure.
hasParent
Synopsis: #include “interface.h”
unsigned char hasParent(int flynn1)
Description: Finds whether the flynn has a parent (is a child).
Input: flynn1 Specifies the flynn.
Returns: True if flynn1 has a parent, else false.
isChildOf
Synopsis: #include “interface.h”
unsigned char isChildOf(int flynn1,int flynn2)
Description: Finds whether flynn1 is a sub-region of flynn2.
Input: flynn1 Specifies the child flynn.
flynn2 Specifies the parent flynn.
Returns: True if flynn1 is a descendant of flynn2, else false.
isFlynnIntegerAttribute
Synopsis: #include “interface.h”
unsigned char isFlynnIntegerAttribute(int attribid)
Description: Finds whether the attribute is one that store discrete values e.g. MINERAL. This type of attribute must have the same value for flynns to merge (see 3.1.1).
Input: attribid Specifies the attribute.
Returns: True if attribid is an attribute that represents integer values
isParent
Synopsis: #include “interface.h”
unsigned char isParent(int flynn1)
Description: Finds whether the flynn is a parent (has at least one child).
Input: flynn1 Specifies the flynn.
Returns: True if flynn1 is a parent, else false.
6 Node functions
ElleAddDoubles
Synopsis: #include “nodes.h”
int ElleAddDoubles()
Description: Inserts new double nodes (see ElleInsertDoubleJ) halfway along segments which are longer than the maximum node separation. The active nodes are checked until no new nodes need to be added.
Returns: 0.
ElleCopyToPosition
Synopsis: #include “nodes.h”
void ElleCopyToPosition(int node, Coords *position)
Description: Sets the new node location without translating into the unit cell. The previous position is updated.
Input: node Specifies the node.
position Points to a structure holding the new position.
ElleCopyToPrevPosition
Synopsis: #include “nodes.h”
void ElleCopyToPrevPosition(int node, Coords *position)
Description: Sets the previous node location without translating into the unit cell.
Input: node Specifies the node.
position Points to a structure holding the new values.
ElleDeleteDoubleJ
Synopsis: #include “nodes.h”
int ElleDeleteDoubleJ(int id)
Description: Deletes the specified node.
Input: id Specifies the index of the node to be deleted.
Returns: 0 (topological inconsistencies cause the program to exit).
ElleFindSpareNode
Synopsis: #include “nodes.h”
int ElleFindSpareNode()
Description: Searches the node array for the first inactive entry (allocates a larger array if all entries are active).
Returns: The index of an inactive entry.
ElleInitNodeAttribute
Synopsis: #include “nodes.h”
void ElleInitNodeAttribute(int id)
Description: Activates a node attribute.
Input: id Specifies the attribute (see node attribute values).
ElleInsertDoubleJ
Synopsis: #include “nodes.h”
int ElleInsertDoubleJ(int node1,int node2,int *nn,float frac)
Description: Inserts a new double node between two neighbouring nodes and gives it attributes interpolated linearly from the neighbours.
Input: node1, node2 The nodes to be separated by the new node.
frac Determines the distance along the segment (from node1) to locate the new node.
Output: nn This will be set to the index of the new node.
Returns: 0
ElleIntrpAttributes
Synopsis: #include “nodes.h”
void ElleIntrpAttributes(int n)
Description: Performs a linear interpolation of active attributes for a new double node (assume triples are not inserted)
Input: n specifies the new node
ElleMaxNodeAttributes
Synopsis: #include “nodes.h”
int ElleMaxNodeAttributes()
Description: Finds the number of node attributes activated.
Returns: Number of node attributes (an active node attribute is assigned to all nodes).
ElleMaxNodes
Synopsis: #include “nodes.h”
int ElleMaxNodes()
Description: Finds the current size of the node array.
Returns: The total number of entries in the node array, both active and inactive.
ElleNeighbourNodes
Synopsis: #include “nodes.h”
int ElleNeighbourNodes(int node, int *nbnodes)
Description: Finds the indices of a nodes neighbours
Input: node Specifies the node.
Output: nbnodes An existing array of 3 integers into which the neighbour indices are copied. If the node is double, the blank entry may be in any position.
Returns: 0, if node is inactive the program terminates.
ElleNeighbourRegion
Synopsis: #include “nodes.h”
void ElleNeighbourRegion(int node, int nb, ERegion *region)
Description: Finds the flynn to the left of the node->nb boundary.
Input: node Specifies the node.
nb Specifies the boundary.
Output: region Set to the flynn id.
ElleNodeAttribute
Synopsis: #include “nodes.h”
double ElleNodeAttribute(int node, int id)
Description: Finds the value of a node attribute.
Input: node Specifies the node.
id Specifies the attribute (see node attribute values).
Returns: The value of the attribute (an invalid id will terminate the program).
ElleNodeAttributeList
Synopsis: #include “nodes.h”
void ElleNodeAttributeList(int **active, int *max)
Description: Creates a list of active node attributes. Memory is allocated for the list so should be released when no longer needed.
Output: active The address of a pointer to the list of attributes.
max Set to the number of attributes.
ElleNodeIsActive
Synopsis: #include “nodes.h”
int ElleNodeIsActive(int node)
Description: Finds the state of the specified node.
Input: node The specified node.
Returns: If node is valid (<ElleMaxNodes()), returns 1 if active else 0.
ElleNodeIsDouble
Synopsis: #include “nodes.h”
int ElleNodeIsDouble(int node)
Description: Counts the neighbours of the specified node.
Input: node The specified node.
Returns: 1 if there are two neighbours, else 0.
ElleNodeIsTriple
Synopsis: #include “nodes.h”
int ElleNodeIsTriple(int node)
Description: Counts the neighbours of the specified node.
Input: node The specified node.
Returns: 1 if there are three neighbours, else 0.
ElleNodeNumAttributes
Synopsis: #include “nodes.h”
int ElleNodeNumAttributes()
Description: Counts the number of active node attributes.
Returns: The number of node attributes.
ElleNodeOnRgnBnd
Synopsis: #include “nodes.h”
int ElleNodeOnRgnBnd(int node, ERegion id)
Description: Determines if the node is on the boundary of the flynn.
Input: node Specifies the node.
id An integer specifying the flynn.
Returns: 1 if true else 0.
ElleNodePlotXY
Synopsis: #include “nodes.h”
void ElleNodePlotXY(int node, Coords *xy, Coords *prevxy)
Description: Find the position of a node relative to a given location. This allows for wrapping around the unit cell and the coordinates returned may no be inside the unit cell. One example where this function is used: finding the locations of all nodes on a flynn boundary as the flynn may cross the edge of the unit cell.
Input: node Specifies the node.
prevxy The node position will be given relative to this location.
Output: xy The node position.
ElleNodePosition
Synopsis: #include “nodes.h”
void ElleNodePosition(int node, Coords *position)
Description: Finds the node location
Input: node Specifies the node.
Output: position Set to the node’s location.
ElleNodePrevPosition
Synopsis: #include “nodes.h”
void ElleNodePrevPosition(int node, Coords *previous)
Description: Finds the node’s previous location.
Input: node Specifies the node.
Output: position Set to the node’s previous location.
ElleNodeSeparation
Synopsis: #include “nodes.h”
double ElleNodeSeparation(int node1, int node2)
Description: Calculates the absolute distance between 2 nodes using the position of node2 relative to node1 (not the unit cell location).
Input: node1, node2 The 2 nodes.
Returns: The distance between the nodes.
ElleNodeUnitXY
Synopsis: #include “nodes.h”
void ElleNodeUnitXY(Coords *xy)
Description: Converts x, y coordinates to unit cell coordinates.
Input/Output: xy x and y values in a Coords structure.
ElleNumberOfNodes
Synopsis: #include “nodes.h”
void ElleNumberOfNodes(int *doubles, int *triples)
Description: Counts the number of currently active nodes.
Output: doubles Set to the number of active double nodes.
Triples Set to the number of active triple nodes.
ElleRegions
Synopsis: #include “nodes.h”
int ElleRegions(int node, ERegion *rgn)
Description: Finds the flynns to the left of each segment (neighbour boundary).
Input: node Specifies the node.
Output: rgn An array of 3 integers into which the flynn indices are copied. If the node is double, the blank entry may be in any position.
Returns: 0, if node is inactive the program terminates.
ElleRelPosition
Synopsis: #include “nodes.h”
void ElleRelPosition(Coords *orig, int nb, Coords *xyrel, double *sep)
Description: Finds the node location relative to a specified point and calculates the distance from this new origin. The relative location may not be within the unit cell.
Input: orig x,y coordinates of the new origin.
nb Index of the node.
Output: xyrel The recalculated position of nb.
sep The absolute distance from the point (*orig) to nb.
ElleSetNodeActive
Synopsis: #include “nodes.h”
void ElleSetNodeActive(int node)
Description: Sets the state of the specified node, allocating a larger node array if there are no spare entries.
Input: node The index of the node.
ElleSetNodeAttribute
Synopsis: #include “nodes.h”
void ElleSetNodeAttribute(int node, double val, int id)
Description: Set the value of a floating point node attribute.
Input: node Specifies the node.
val The attribute value.
id Specifies the attribute (see node attribute values).
ElleSetPosition
Synopsis: #include “nodes.h”
void ElleSetPosition(int node, Coords *position)
Description: Sets the x, y coordinates of the node to the values in the position structure. The position is translated into the unit cell, if necessary. The current position is stored as the previous position before updating.
Input: node specifies the node
position points to a structure holding the new position
ElleSetPrevPosition
Synopsis: #include “nodes.h”
void ElleSetPrevPosition(int node, Coords *position)
Description: Sets the x, y coordinates of the node’s previous position. Normally done automatically to save the last position when a node is moved.
Input: node Specifies the node.
position Points to a structure holding the new values.
ElleSwitchTripleNodes
Synopsis: #include “nodes.h”
int ElleSwitchTripleNodes(int node1,int node2)
Description: Perform a triple switch of the specified nodes. The routine assumes they are both triples and will report topological problems if this is not true.
Input: node1, node2 Specify the nodes to switch.
Returns: 0 if successful.
Non-zero if it could not resolve a valid topological problem (e.g. a wrapping region which could not be split.
ElleSwitchTriples
Synopsis: #include “nodes.h”
void ElleSwitchTriples(int modfactor)
Description: Forces switching of neighbouring triple nodes. Used to generate a starting structure from a regular grid.
Input: modfactor Specifies how many pairs of triples are switched (modfactor is 6 then every 6th pair is switched).
ElleTotalNodeMass
Synopsis: #include “nodes.h”
double ElleTotalNodeMass(int attrib_id)
Description: Find the total mass for concentration attribute
Input: attrib_id Specifies the attribute (assumes the attribute is a concentration).
Returns: the mass for the nodes
ElleUpdatePosition
Synopsis: #include “nodes.h”
void ElleUpdatePosition(int node, Coords *increment)
Description: Moves the node by the increment x, y values. It is the same as ElleSetPosition once the new location is calculated but it also updates node and unode concentration attributes.
Input: node Specifies the node.
Increment Specifies the changes to the x, y location.
7 Unode Functions
ElleGetFlynnUnodeList
Synopsis: #include “interface.h”
void ElleGetFlynnUnodeList(int flynn_id, vector<int> &l)
Description: Find the unconnected nodes that lie inside the flynn specified by flynn_id.
Input: flynn_id Specifies the flynn.
Output: l The list of the unode identifiers.
ElleGetUnodeAttribute
Synopsis: #include “unodes.h”
void ElleGetUnodeAttribute(int id, double *val, const int attrib_id)
Description: Find the value of the attribute specified by attrib_id for the unconnected node specified by id.
Input: id Specifies the unode.
attrib_id The attribute identifier.
Output: val The value of the specified attribute.
ElleGetUnodePosition
Synopsis: #include “unodes.h”
void ElleGetUnodePosition(int id, Coords *xy)
Description: Find the position of the unconnected node specified by id.
Input: id Specifies the unode.
Output: xy The position of the unode.
ElleInitUnodeAttribute
Synopsis: #include “unodes.h”
void ElleInitUnodeAttribute(int id)
Description: This attribute will become active for all unodes. All unodes will have the default value of this attribute unless the value is changed using ElleSetUnodeAttribute
Input: id specifies the attribute
ElleInitUnodes
Synopsis: #include “unodes.h”
int ElleInitUnodes(int num_per_row)
Description: Create unodes, arranged in the unit cell such that a unode is equidistant from its neighbours
Input: num_per_row number of unodes in a row (preferably a multiple of 15)
Returns: 0
ElleMaxUnodes
Synopsis: #include “unodes.h”
int ElleMaxUnodes()
Description: Find the number of active unodes
Returns: the maximum index for the unconnected nodes
ElleSetUnodeAttribute
Synopsis: #include “unodes.h”
void ElleSetUnodeAttribute(int id, double val, const int attrib_id)
Description: Set the value of the attribute specified by attrib_id for the unconnected node specified by id.
Input: id Specifies the unode.
attrib_id The attribute identifier.
val Set to the value of the specified attribute.
ElleTotalUnodeMass
Synopsis: #include “unodes.h”
double ElleTotalUnodeMass(int attrib_id)
Description: Find the total mass for concentration attribute
Input: attrib_id Specifies the attribute (assumes the attribute is a concentration).
Returns: the mass for the unconnected nodes
ElleUnodeAttributeActive
Synopsis: #include “unodes.h”
unsigned char ElleUnodeAttributeActive(int id)
Description: Find whether the attribute is active
Returns: 1, if the attribute is active, else 0
ElleUnodeROI
Synopsis: #include “unodes.h”
double ElleUnodeROI()
Description: The ROI is twice the spacing between unodes (see 4.2.2)
Returns: the radius of the region of interest for an unconnected node
ElleUnodesActive
Synopsis: #include “unodes.h”
int ElleUnodesActive()
Description: Test whether unconnected nodes have been initialised for this experiment
Returns: 1, if unconnected nodes are active, else 0
8 Triangulation functions
TriangulateUnodes
Synopsis: #include “unodes.h”
void TriangulateUnodes(int flynn_id, struct triangulateio *out)
Description: Triangulate the unconnected nodes within a flynn with its boundary nodes. No new nodes are inserted on the flynn boundary. The triangle attribute is calculated from the unode values for the attr parameter and node margin values, if active.
Input: flynn_id Specifies the flynn.
out pointer to a triangulateio structure. This should be Mesh.tri if the functions in triattrib.h are to be used (See 3.5).
attr specifies the triangle attribute to be calculated
Returns: 1, if unconnected nodes are active, else 0
TriangulateUnodes
Synopsis: #include “unodes.h”
void TriangulateUnodes(int flynn_id, struct triangulateio *out)
Description: Triangulate the unconnected nodes within a flynn and its boundary nodes. No new nodes are inserted on the flynn boundary. The triangle attribute will be calculated from the CONC_A values of the unodes and the margin values (N_MCONC_A) at the nodes, if active. It is equivalent to TriangulateUnodes(Flynn_id,out,CONC_A)
Input: flynn_id Specifies the flynn.
out pointer to a triangulateio structure. This should be Mesh.tri if the functions in triattrib.h are to be used (see 8).
Returns: 1, if unconnected nodes are active, else 0
ElleClearTriAttributes
Synopsis: #include “triattrib.h”
void ElleClearTriAttributes()
Description: Clear the attributes from Mesh
ElleGetTriPtNeighbours
Synopsis: #include “triattrib.h”
void ElleGetTriPtNeighbours(int index, vector<int> &nbnodes,
unsigned char bnd)
Description: Puts the Elle identifiers of the triangulation neighbours in nbnodes. If bnd is set to 1 then all neighbours are included. If bnd is zero, only the non-boundary neighbours are listed. The neighbours are listed in anticlockwise order.
Input: index Specifies the Elle unode identifier of the triangulation point.
bnd 0, do not include flynn boundary nodes
1, include flynn boundary nodes
Output: nbnodes The list of nodes connected to the triangulation point with the Elle identifier, index.
on_bnd corresponds to nbnodes, 0 for a unode, 1 for a boundary node
ElleGetNodeTriPtNeighbours
Synopsis: #include “triattrib.h”
void ElleGetNodeTriPtNeighbours(int index, vector<int> &nbnodes,
vector<int> &on_bnd, int nb_id,
unsigned char bnd)
Description: Puts the Elle identifiers of the triangulation neighbours in nbnodes. If bnd is set to 1 then all neighbours are included. If bnd is zero, only the non-boundary neighbours are listed. The neighbours are listed in anticlockwise order starting with nb_id, if found.
Input: index Specifies the Elle node identifier of the triangulation point.
bnd 0, do not include flynn boundary nodes
1, include flynn boundary nodes
nb_id neighbouring flynn boundary node
Output: nbnodes The list of nodes connected to the triangulation point with the Elle identifier, index.
on_bnd corresponds to nbnodes, 0 for a unode, 1 for a boundary node
EllePlotTriangles
Synopsis: #include “display.h”
void EllePlotTriangles()
Description: Plots triangulation data – currently used to plot the unode triangulation and by the diffusion example.
9 Runtime settings
ElleSetSaveFileRoot
Synopsis: #include “runopts.h”
void ElleSetSaveFileRoot(char *name)
Description: Specifies the root of the filename for any files written.
Input: String to be used.
ElleSetSaveFrequency
Synopsis: #include “runopts.h”
void ElleSetSaveFrequency(int freq)
Description: Specifies how often an Elle file should be saved eg if freq is n, a file will be saved after every nth stage. The filename will be a concatenation of the file root, the stage number and the “.elle” suffix.
Input: freq Specifies the interval for saving Elle files.
ElleSetVerbose
Synopsis: #include “runopts.h”
void ElleSetVerbose(int state)
Description: Sets a flag specifying whether the process should output information to the terminal during execution (Not properly implemented).
Input: 0 or 1.
ElleSetDisplay
Synopsis: #include “runopts.h”
void ElleSetDisplay(int state)
Description: Sets a flag specifying whether the process should open an X window or run in batch mode. Display is usually set to 1 (for graphical display) while developing a process and set to 0 for background execution.
ElleSetStages
Synopsis: #include “runopts.h”
void ElleSetStages(int state)
Description: Sets the number of times to run through a loop in the process [20] . See the template files.
ElleSetInitFunction
Synopsis: #include “runopts.h”
void ElleSetInitFunction(ElleRunFunc myfunc)
Description: Sets the function to be run when the process is initialised (on startup, when an Elle data file is opened or when the process is rerun.
Input: myfunc The name of the function of type ElleRunFunc.
ElleInitFunction
Synopsis: #include “runopts.h”
ElleRunFunc ElleInitFunction()
Description: Returns a pointer to the function set by ElleSetInitFunction.
Returns: The function of type ElleRunFunc. Returns 0 if ElleSetInitFunction has not been called.
ElleSetRunFunction
Synopsis: #include “runopts.h”
void ElleSetRunFunction(ElleRunFunc myfunc)
Description: Sets the function to be run when the process is started or when the process is rerun. See the template files.
Input: myfunc The name of the function of type ElleRunFunc.
ElleRunFunction
Synopsis: #include “runopts.h”
ElleRunFunc ElleRunFunction()
Description: Returns a pointer to the function set by ElleSetRunFunction.
Returns: The function of type ElleRunFunc. Returns 0 if ElleSetRunFunction has not been called.
ElleSetExitFunction
Synopsis: #include “runopts.h”
void ElleSetExitFunction(ElleRunFunc myfunc)
Description: Sets the function to be run when the process is terminated. See the template files.
Input: myfunc The name of the function of type ElleRunFunc.
ElleExitFunction
Synopsis: #include “runopts.h”
ElleRunFunc ElleExitFunction()
Description: Returns a pointer to the function set by ElleSetExitFunction.
Returns: The function of type ElleRunFunc. Returns 0 if ElleSetExitFunction has not been called.
ElleSetFile
Synopsis: #include “runopts.h”
void ElleSetFile(char *filename)
Description: Sets the Elle data file to be read when the process is started or when the process is rerun.
Input: filename The name of the Elle data file.
ElleFile
Synopsis: #include “runopts.h”
char *ElleFile()
Description: Returns a pointer to the name of the Elle data file. This may be an empty string if a file has not been opened.
Returns: Pointer to the Elle data file name.
ElleSetSwitchdistance
Synopsis: #include “runopts.h”
void ElleSetSwitchdistance(double val)
Description: Sets the minimum separation distance for triple nodes. The value is used in the topology check routines to control triple switching. This function sets the minimum separation for double nodes to val and the maximum separation for double nodes to val*2.2
Input: val The minimum separation distance for triple nodes.
ElleSwitchdistance
Synopsis: #include “runopts.h”
double ElleSwitchdistance()
Description: Returns the setting for the minimum separation distance for triple nodes [0.025]. The value is used in the topology check routines to control triple switching.
Returns: The switch distance for triple nodes.
ElleSetSpeedup
Synopsis: #include “runopts.h”
void ElleSetSpeedup(double val)
Description: Limits the distance a node may move in any one time step.
Input: val The speedup value.
ElleSpeedup
Synopsis: #include “runopts.h”
double ElleSpeedup()
Description: Returns the speedup value – a parameter which limits the distance a node may move in any one time step.
Returns: The speedup value.
EllemaxNodeSep
Synopsis: #include “runopts.h”
double EllemaxNodeSep()
Description: Returns the maximum separation distance for double nodes. Check routines may insert nodes if this distance is exceeded. This value is set when the switch distance is set.
Returns: The maximum node separation.
ElleminNodeSep
Synopsis: #include “runopts.h”
double ElleminNodeSep()
Description: Returns the minimum separation distance for double nodes. Check routines may remove nodes if boundaries become shorter than the minimum. This value is set when the switch distance is set.
Returns: The minimum node separation.
ElleReadOptionData
Synopsis: #include “runopts.h”
int ElleReadOptionData(FILE *fp,char *str)
Description: Reads the data in the OPTIONS section of an Elle file.
Input: fp The pointer to the file stream opened for reading
str A buffer into which lines from the file are read
Returns: 0, if it reads the section successfully, else an error number
ElleWriteOptionData
Synopsis: #include “runopts.h”
int ElleWriteOptionData(FILE *fp)
Description: Writes the OPTIONS section of an Elle file.
Input: fp The pointer to the file stream opened for writing
Returns: 0, if it writes the section successfully, else an error number
ElleSaveFileRoot
Synopsis: #include “runopts.h”
char *ElleSaveFileRoot(void)
Description: Returns a pointer to the string used as the root of the name for any files written
Returns: A char pointer. (This is the address of the field in the global structure)
EllemaxStages
Synopsis: #include “runopts.h”
int EllemaxStages(void)
Description: This function returns the setting for stages. The default is 20 and it may be reset by calling the function ElleSetStages() or via the Set Options dialog box (Run menu)
Returns: an integer value
ElleDisplay
Synopsis: #include “runopts.h”
int ElleDisplay(void)
Description: Returns the value of a flag specifying whether the process should open an X window or run in batch mode
Returns: 0 or 1
ElleTemperature
Synopsis: #include “runopts.h”
double ElleTemperature(void)
Description: Returns the current temperature value
Returns: a double value
EllePressure
Synopsis: #include “runopts.h”
double EllePressure(void)
Description: Returns the current pressure value
Returns: a double value
ElleBoundaryWidth
Synopsis: #include “runopts.h”
double ElleBoundaryWidth(void)
Description: Returns the boundary width value (assumed to be in metres). Default is 1e-9m.
Returns: a double value
ElleUnitLength
Synopsis: #include “runopts.h”
double ElleUnitLength(void)
Description: Returns the length of the unit cell (assumed to be in metres). Default is 1cm.
Returns: a double value
ElleSetUnitLength
Synopsis: #include “runopts.h”
void ElleSetUnitLength(double val)
Description: Sets the value used to scale the unit cell
Input: val The length value (assumed to be metres).
ElleSetBoundaryWidth
Synopsis: #include “runopts.h”
void ElleSetBoundaryWidth(double val)
Description: Changes the boundary width value applied to all grain boundaries
Input: val The pressure value.
ElleSetPressure
Synopsis: #include “runopts.h”
void ElleSetPressure(double val)
Description: Sets the current pressure value
Input: val The new value.
ElleSetTemperature
Synopsis: #include “runopts.h”
void ElleSetTemperature(double val)
Description: Sets the current temperature value
Input: val The new value.
ElleSetCellBBox
Synopsis: #include “runopts.h”
int ElleSetCellBBox(Coords *baseleft, Coords *baseright,
Coords *topright, Coords *topleft)
Description: Sets the bounding box for the unit cell.
Returns: 0 if the values are set. Returns 1 if the coordinates of the corners do not seem topologically correct
ElleCellBBox
Synopsis: #include “runopts.h”
void ElleCellBBox(CellData *data)
Description: Copies the bounding box structure to the input variable.
Input: The address of a variable of type CellData
Last Updated on Monday, 21 April 2008 11:30