4.1 Util Array Functions

The Util class is one of the most ubiquitous classes in the framework, and contains all of the generic functions that wouldn’t make sense to add to any particular object in the framework.

The list of utilities functions in the framework has only grown with time. the list presented here is not exhaustive, so I recommend looking at the file itself if you feel something is missing, on top of that feel free to ask for a new feature or better yet send me an implementation and I’ll most likely add it to the repository for everyone to share.

A set of utilities for making array manipulation easier.

ArrToString(arr,delim):
useful for collecting data or print statement debugging, returns the contents of an array as a single string. entries are separated by the delimeter argument
IndicesArray(numEntries):
generates an array of ascending indices starting with 0, up to nEntries.
Mean(arr):
returns the mean of an array
Sum(arr):
returns the sum of an array
Norm(arr):
returns the euclidean norm of an array
NormSq(arr):
returns the squared euclidian norm of an array, somewhat more efficient than Norm
SumTo1(arr):
scales all entries in an array so that their sum is 1.
Normalize(arr):
scales all entries in an array so that their norm is 1.

4.2 Util Neighborhood Functions

a set of utilities for generating neighborhoods. neighborhoods are lists of x,y index pairs, of the form [01,02,...0n,x1,y1x2,y2...xn,yn] in the third dimension these are [01,02,...0n,x1,y1z1,x2,y2z2,...xn,yn,zn] these arrays are useful when finding the indices of the locations that make up the neighborhood around an agent when using Grid/Agent functions such as MapHood. Neighborhood arrays are always padded with 0s at the beginning, for use with the MapHood functions.

These functions should not be called over and over, as this would wastefully create arrays over and over. instead the function should be called once and be stored by the grid.

GenHood2D(int[]coords),GenHood3D(int[]coords):
generates a 2D/3D neighborhood array for use with the MapHood functions. input should be an integer array of the form [x1,y1x2,y2...xn,yn] in 2D, or [x1,y1z1,x2,y2z2,...xn,yn,zn] in 3D.
VonNeumannHood(origin?),MooreHood(origin?):
returns an array that contains the coordinates of the VonNeumann or Moore Neigbhorhood in 2D. the boolean argument specifies whether the center of these neighborhood (0,0) should be included as part of the set of coordinates.
VonNeumannHood3D(origin?),MooreHood3D(origin?):
returns an array that contains the coordinates of the VonNeumann or Moore Neigbhorhood in 3D. the boolean argument specifies whether the center of these neighborhood (0,0) should be included as part of the set of coordinates.
HexHoodEvenY(origin?),HexHoodOddY(origin?):
to simulate a hex lattice on a Grid2D, the neighborhood used for a given agent changes depending on the position of the agent. The hex hood changes depending on whether the agent is on an even or odd Y position. These functions return an array that contains the proper coordinates for a given case.
TriangleHoodSameParity(origin?),TriangleHoodDifParity(origin?):
to simulate a triangle lattice on a Grid2D, the neighborhood used for a given agent changes depending on the position of the agent. The Triangle hood changes depending on whether the parity (“even-ness”) of the agents X and Y position match. These functions return an array that contains the proper coordinates for a given case.
CircleHood(origin?,radius):
generates a neighborhood of all squares within the radius of a starting position at the middle of the (0,0) origin square. the boolean argument specifies wether (0,0) should be included in the return array.
RectangleHood(origin?,radX,radY):
generates a neighborhood of all squares whose x displacement is within radX, and whose y displacement is within radY of a starting position at the middle of the (0,0) origin square. the boolean argument specifies whether (0,0) should be included in the return array.
AlongLineCoords(x1,y1,x2,y2):
returns an array of all squares that touch a line between the two starting positions.

4.3 Util Math Functions

For all of the following functions, and throughout the framework, rn refers to a random number generator.

InfiniteLinesIntersection2D(x1,y1,x2,y2,x3,y3,x4,y4,double[]ret):
computes the intersection of lines between points 1 and 2, and points 3 and 4. puts the coordinates of the intersection point in ret. returns true if the infinite lines intersect (if they are not parallel). returns false if the lines are parallel.
Bound(val,min,max):
returns the value bounded by the min and max.
Rescale(val,min,max):
assumes the starting value is in the 0-1 scale, and rescales it be in the min-max scale.
ModWrap(val,max):
wraps the value provided so that it must be between 0 and max. used to implement wraparound by the framework.
ProtonsToPh(protonConc):
converts proton concentration to ph
PhToProtons(ph):
converts ph to proton concentration
ProbScale(prob,duration):
converts the probability that an even happens in unit time to the probability that that same event happens in duration time.
Sigmoid(val,stretch,inflectionValue,minCap,maxCap):
val is the value that the sigmoid function is being applied to, the stretch argument stretchs or shrinks the sigmoid function along the x axis, the infectionValue governs where the inflection point of the sigmoid is, minCap and maxCap bound the sigmoid along the y axis.

4.4 Util Misc Functions

TimeStamp():
returns a timestamp string with format “YYYY_MM_DD_HH_MM_SS”
PWD():
returns the current working directory as a string
MemoryUsageStr():
returns a string with information about the current memory usage of the program.
QuickSort(sortMe,greatestToLeast):
requires the passed sortMe class to implement the Sortable interface. the passed boolean indicates whether the array should be sorted from greatest to least or least to greatest.

4.5 Util Color Functions

These functions generate integers that store RGBA (Red,Green,Blue,Alpha) color channels internally, 8 bits per channel (integer values 0-255). These so-called “ColorInts” are intended to be used as arguments for the UIGrid, GridWindow, Vis2DOpenGL, and Vis3DOpenGL to set the color of the pixels or objects being displayed. the RGB components set the color, and the alpha component adds transparancy.

All of these functions (except the “Getters”) return a new ColorInt

RGB(r,g,b):
sets the rgb color channels using the continous 0-1 range mapping. the alpha is always set to 1.
RGBA(r,g,b,a):
sets the rgb and alpha channels using the continuous 0-1 range mapping.
RGB256(r,g,b):
sets the rgb color channels using the discrete 0-255 range mapping. the alpha is always set to 1.
RGBA256(r,g,b,a):
sets the rgb and alpha channels using the 0-255 range mapping.
GetRed(color),GetBlue(color),GetGreen(color),GetAlpha(color):
returns the value of a single channel using the continous 0-1 range mapping
GetRed256(color),GetBlue256(color),GetGreen256(color),GetAlpha256(color):
returns the value of a single channel using the discrete 0-255 range mapping
SetRed(color),SetGreen(color),SetBlue(color),SetAlpha(color):
returns a new ColorInt with the one of its channels changed compared to the argument passed in, uses the continuous 0-1 range mapping
SetRed256(color),SetGreen256(color),SetBlue256(color),SetAlpha256(color):
returns a new ColorInt with the one of its channels changed compared to the argument passed in, uses the discrete 0-255 range mapping
CategoricalColor(index):
returns a categorical color from a nice mutually distinct set. Valid indices are 0-19. the color order is (blue,red,green,yellow,purple,orange,cyan,pink,brown,light blue,light red,light green,light yellow,light purple, light orange, light cyan,light pink, light brown, light gray, dark gray
HeatMapRGB(val),HeatMap???(val):
returns a new colorInt using the heatmap color scale. values are distinguished in the 0-1 range. the heatmap color scale is black at 0, white at 1, and transitions between these by changing one color channel at a time from none to full. the order that the channels are changed is dictated by the order of the 3 letters at the end of the function name. the possible orders are RGB, RBG, GRB, GBR, GRB and GBR
HeatMapRGB(val,min,max),HeatMap???(val):
same as the above, but works to distinguish values in the min-max range.
HSBColor(hue,saturation,brightness):
returns a new colorInt using the HSB colorspace. values are distinguished in the continuous 0-1 range.
YCbCrColor(y,cb,cr):
returns a new colorInt using the YCbCr colorspace. values are distinguished in the continous 0-1 range.
CbCrPlaneColor(x,y):
returns a new colorInt using the CbCr plane at Y=0.5. a very nice colormap for distinguishing position in a 2 dimensional space. x,y are expected to be in the continuous 0-1 range.

4.6 Util MultiThread Function

Multithread(nRuns,nThreads,RunFun):
A function so useful that it deserves its own section, the multithread function creates a thread pool and launches a total of nRun threads, with nThreads running simultaneously at a time. the RunFun that is passed in must be a void function that takes an integer argument. when the function is called, this integer will be the index of that particular run in the lineup. This can be used to assign the result of many runs to a single array, for example, if the array is written to once by each RunFun at its run index. If you want to run many simulations simultaneously, this function is for you.

4.7 Util Save and Load Functions

NOTE:SerializableModel_Interface
In order to save and load models, you must first have the model extend the SerializableModel interface (this interface is defined in the Interfaces folder). this interface has one method, called SetupConstructors. all you have to do in this method is call the AgentGrid function _PassAgentConstructor(AGENT.cass) once for each AgentGrid in your model, where AGENT is the type of agent that the AgentGrid holds. see LEARN_HERE/Agents/SaveLoadModel for an example.
SaveState(model):
Saves a model state to a byte array and returns it. The model must implement the SerializableModel interface
SaveState(model,fileName):
Saves a model state to a file with the name specified. creates a new file or overwrites one if the file already exists. The model must implement the SerializableModel interface
LoadState(byte[]state):
Loads a model form a byte array created with SaveState. The model must implement the SerializableModel interface
LoadState(fileName):
Loads a model from a file array created with SaveState. The model must implement the SerializableModel interface