Tychos Python Language Reference
The following reference guide identifies the language syntax, built in variables, functions, and classes that are used to code your simulations using the Python Language. We have included documentation here for some of the helpful functions defined in the Python language. This is not a complete list of all functions available in Python, just ones that might be commonly used in Tychos for building scenarios as well as defining goals for those scenarios.
Comments
Comments are statements that you can insert in your code that do not get interpreted and executed by Tychos. To create a comment, you simply indicate a comment by using a hashtag:
Variables
To define a variable in Tychos all you need to do is identify a name for the variable. You then type an =
sign to assign a value to the variable. The following demonstrates various variable declarations
Built-in Scenario Variables
There are a few variables that are built into Tychos. These variables are:
t
— How many seconds has passed since this Scenario was started?dt
— Time between frames as seconds, e.g. 0.1 is 1/10th of a second.frame_count
— How many frames have passed? e.g. 1, 2, 3...
Common Math Operators and Functions
These are some common mathematical operators and functions for performing various calculations.
Mathematical Operators
Tychos uses the following operators to perform basic math calculations:
+
— Addition-
— Subtraction*
- Multiplication/
- Division** - Exponent
%
- Modulo
Basic Math Functions
You can also use the following basic math functions:
sqrt(positive_number)
The sqrt(positive_number)
function takes a single non negative number and returns the real square root of the number.
exp(power)
The exp(power)
function calculates Euler's number (e) to the given power.
log(x)
The log(x)
returns the natural log (base e) of x.
ceil(x)
The ceil(x)
function rounds a number up to the nearest integer.
floor(x)
The floor(x)
function rounds a number down to the nearest integer.
sign(x)
The sign(x)
function returns +1 if x is less than 0, -1 if x is greater than 0, and 0 if x is equal to 0.
abs(x)
The abs(x)
function returns the absolute value of a number.
random()
The random()
function returns a semi random number between 0 and 1.
randrange(a, b)
The randrange(a,b)
function returns a semi random number between a
and b
.
factorial(x)
The factorial(x)
function calculates the product of all positive integers less than or equal to the given positive integer.
combin(n, r)
The combin(x,y)
function calculates the number of ways to choose a sample of r elements from a set of n distinct objects where order does not matter and replacements are not allowed.
Trigonometric Functions
The following functions all use radians as the angle measurement. You can use pi
to represent PI.
sin(angle)
The sin(angle)
function is used to evaluate the trigonometric sine value for a given input angle. The input angle must be provided in radians.
cos(angle)
The cos(angle)
function is used to evaluate the trigonometric cosine value for a given input angle. The input angle must be provided in radians.
tan(angle)
The tan(angle)
function is used to evaluate the trigonometric tangent value for a given input angle. The input angle must be provided in radians.
asin(value)
The asin(value)
function is used to evaluate the trigonometric arcsine value (inverse sine) for a given input. The output angle is given in radians.
acos(value)
The acos(value)
function is used to evaluate the trigonometric arccosine value (inverse cosine) for a given input. The output angle is given in radians.
atan2(x, y)
The atan2(value)
function is used to evaluate the trigonometric arctangent value (inverse tangent) for a given x and y input. The output angle is given in radians.
radians(angle)
The input is an angle measurement in degrees and the output is the angle measurement in radians.
degrees(angle)
The input is an angle measurement in radians and the output is the angle measurement in degrees.
Vector and Vector Functions
The following functions provide operations for creating and using vectors in calculations.
vec(x, y), or vec(x,y,z)
Creates a Vector object representing a 3d vector with components identified as x, y, and z.
Adding and Subtracting Vectors
Vectors can be added or subtracted from one another using standard +, - operators:
Multiplying and Dividing By A Scalar
Vectors can also by scaled using the standard *, / operators:
dot(v1, v2)
Calculates the dot product of two Vector objects.
cross(v1, v2)
Calculates the cross product for two vectors in three dimensional space.
norm(vec)
Same as hat
. See below.
hat(vec)
This function returns a unit vector representation of the given input vector. Its magnitude is 1 and the direction matches the direction of the input vector. This can be useful if you need just the direction of a vector, but not its magnitude.
vec
- any two or three dimensional vector.
Example:
mag(vec)
This function returns the scaler magnitude of any given vector. This is helpful when you want to know the length of a vector, for example, if you want the magnitude of a vector, but not the direction.
vec
- any two or three dimensional vector.
Example:
mag2(vec)
This function returns the scaler squared magnitude of any given vector.
vec
- any two or three dimensional vector.
Example:
diff_angle(vec1, vec2)
This function returns the angle between two vectors. The angle is returned in radians.
vec1
- any two or three dimensional vector.vec2
- any two or three dimensional vector.
Example:
diff_angle(vec1, vec2)
This function returns the angle between two vectors. The angle value is returned in radians.
vec1
- any two or three dimensional vector.vec2
- any two or three dimensional vector.
Example:
proj(vec1, vec2)
This function returns the vector projection of vec1
along vec2
.
vec1
- any two or three dimensional vector.vec2
- any two or three dimensional vector.
comp(vec1, vec2)
This function returns the scalar projection of vec1
along vec2
.
vec1
- any two or three dimensional vector.vec2
- any two or three dimensional vector.
distance(point1, point2)
This function returns a scalar quantity representing the distance between two points.
point1
- any two or three dimensional vector representing a point in space.point2
- any two or three dimensional vector representing a point in space.
Example:
direction(vec)
This function returns a scalar angle measurement. This is helpful when you want to know the direction of a vector, like the direction of a velocity vector, or the direction of a force vector. The returned angle is given in radians, measured from the positive x axis.
vec
- any two or three dimensional vector.
Example:
polar(radius, angle)
This function returns a two-dimensional vector representing the cartesian components of a polar coordinate corresponding to the magnitude of the radius and the radial angle.
radius
- scalar quantity representing the scalar distance of the radius of theangle
- scalar quantity representing the angle measurement of the polar coordinate.
Example:
get_rotated_position(position, angle, axis)
This function is simply used for finding a point that has been rotated a given angle about a specific axis. It is just a utility function that could be performed by doing some simple trigonometry calculations, but hey, why not make it easier for you?
position
- A vector representing the point that is rotated.angle
- scalar quantity representing the angle measurement of rotation.axis
- A 2D vector that identifies the axis point about which the position has been rotated.
Example:
Other Useful Functions
Some other useful functions..._
rgb(r, g, b)
This function returns a hexadecimal value for the red, green, and blue input values. This can be useful for setting the color of an object based on the RGB color model.
r
- a value between 0 and 255 representing the RED of RGB.g
- a value between 0 and 255 representing the GREEN of RGB.b
- a value between 0 and 255 representing the BLUE of RGB.
Example:
stop()
This function interrupts the simulation and stops it at the current frame.
stop()
-> stops the simulation.
Example:
Collision Functions
Currently circle
,rectangle
, and line
objects work with any of the collision functions. We are working to add other objects soon.
The following functions are meant to help users model collisions more easily. These functions could be used for other purposes rather than modeling collisions as Tychos is not a physics engine. These functions could be thought of as "overlap" functions. They return information about the overlap of objects.
has_collided(source, target)
This function returns a boolean true/false value when two objects are given as the source and target. It returns false if the two objects are not determined to be overlapping.
source
-circle
orrectangle
orline
objecttarget
-circle
orrectangle
orline
object
Example:
get_mtv(source, target)
This function returns a two dimensional vector representing the minimum translation vector (MTV) that would be needed to separate two objects when they overlap. This can be used to simulate collision forces or to move objects apart based on the magnitude and direction of the MTV.
source
-circle
orrectangle
orline
objecttarget
-circle
orrectangle
orline
object
Example:
get_intersections(source, target)
This function returns a list containing all the points where the object boundaries intersect. The points are vectors corresponding with the coordinates of those intersection locations. This can be used to identify exactly where the overlap is occurring in your scenarios.
source
-circle
orrectangle
orline
objecttarget
-circle
orrectangle
orline
object
The image below shows an example of the points of intersection between a rectangle and a line, but note, those points are being showed for demonstration only, and would not be visible unless you assign them to a visible object, in this case the position of two small circle objects.
Example:
Logical Operators
The following operators are used to execute logical AND and OR comparisons for the use of evaluating logical statements.
and
This is used for performing a logical AND conjunction. For example, "A and B" is true only if A is true and B is true. "A and B" is false if either A or B is false.
You can use the and
operator to test if two comparisons are both true:
or
This is used for performing a logical OR conjunction. For example, "A or B" is true if A or B is true. "A or B" is false only if A and B are both false.
You can use the or
operator to test if one of two comparisons are true:
Built-in Classes
Tychos has only a few classes that are used to create the basic simulated objects in the Tychos universe as well as a few tools for analyzing those objects in the simulated world. The graphical objects in Tychos that can be used are the circle
, the rectangle
, the arrow
, the line
, the label
, the spring
and the poly_line
.
circle
A circle
is drawn as a colored circle in the World View. Circle objects can have borders, labels, or even image overlays (see below).
Below is the constructor for the circle
object that shows its default values:
pos
— The initial position of yourcircle
as a vector withx,y,z
coordinates.radius
— The radius of thecircle
.color
— Thecircle
will be drawn in this color. Use HTML colors e.g. "#ff3300", "blue".no_fill
— If set toTrue
, the area inside thecircle
will be transparent.fill
— Optional argument for rendering thecircle
filled with either alinear_gradient
orradial_gradient
.image
— A URL that identifies a JPEG, GIF, SVG or PNG image.opacity
— Thecircle
will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent.visible
— Thecircle
can be hidden from view by setting this flag toFalse
.motion_map
— This flag tells Tychos to attach a series of strobe images called a motion map.label_text
- The text of an attached label.label_color
- The color of the attached label text.label_font
- The font family of the attached label text.label_style
- A dictionary whose key-value pairs match CSS font styling attributes of the attached label text.border_size
— The border thickness in pixels.border_color
— The border will be drawn in this color. Use HTML colors e.g. "#ff3300", "blue".border_style
— Sets the border as either solid (default = "none") or "dash" for a dashed border, or "dot" for a dotted border.
These attributes may also be modified on the circle
after it is created. In particular, one will usually change the pos
attribute of a circle
in the Calculations editor to show movement. e.g.
circle.remove()
circle
objects, like all Tychos objects can be removed from the scenario world scope. Once this done, you will not be able to reference the object as it will be removed from your scenario's collection of viewable objects.
circle.rotate()
circle
objects can be rotated.
circle.rotate(angle=0, axis=vec(0, 0))
— Rotates the circle
object by a given angle value in radian units. You can also provide an optional vector that identifies the axis of rotation. This method should only be called from the Calculations code editor.
circle.image
circle
objects can also be represented with an image by setting the image attribute of the object. The text must be a URI link to a graphic file that can be a PNG, SVG, GIF, or JPEG image.
The above image also demonstrates the use of the direction
function as well as the rotate
method:
rocket.rotate(direction(rocket.v))
ellipse
An ellipse
is drawn as a colored ellipse in the World View.
Below is the constructor for the ellipse
class that shows its default values:
pos
— The initial position of yourellipse
as a vector withx,y,z
coordinates.size
— The size of theellipse
given as a vector withx,y,z
coordinates.color
— Theellipse
will be drawn in this color. Use HTML colors e.g. "#ff3300", "blue".no_fill
— If set toTrue
, the area inside theellipse
will be transparent.fill
— Optional argument for rendering theellipse
filled with either alinear_gradient
orradial_gradient
.border_size
— The border thickness in pixels.border_color
— The border will be drawn in this color. Use HTML colors e.g. "#ff3300", "blue".border_style
— Sets the border as either solid (default = "none") or "dash" for a dashed border, or "dot" for a dotted border.image
— A URL that identifies a JPEG, GIF, SVG or PNG image.opacity
— Theellipse
will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent.visible
— Theellipse
can be hidden from view by setting this flag toFalse
.motion_map
— This flag tells Tychos to attach a series of strobe images called a motion map.label_text
- The text of an attached label.label_color
- The color of the attached label text.label_font
- The font family of the attached label text.label_style
- A dictionary whose key-value pairs match CSS font styling attributes of the attached label text.
These attributes may also be modified on the ellipse
after it is created, just like the circle
.
ellipse.remove()
ellipse
objects, like all Tychos objects can be removed from the scenario world scope. Once this done, you will not be able to reference the object as it will be removed from your scenario's collection of viewable objects.
ellipse.rotate()
ellipse
objects can be rotated, just like the circle.
ellipse.rotate(angle=0, axis=vec(0, 0))
— Rotates the ellipse
object by a given angle value in radian units. You can also provide an optional vector that identifies the axis of rotation. This method should only be called from the Calculations code editor.
ellipse.image
ellipse
objects can also be represented with an image by setting the image attribute of the object. The text must be a URI link to a graphic file that can be a PNG, SVG, GIF, or JPEG image. See the circle
above for more detail
rectangle
A rectangle
is very similar to a circle
but it is represented as a colored rectangle in the World View.
Below is the constructor for the rectangle
object that shows its default values:
pos
— The initial position of yourrectangle
as a vector withx,y,z
coordinates.size
— The size of therectangle
given as a vector withx,y,z
coordinates.color
— Therectangle
will be drawn in this color. Use HTML colors e.g. "#ff3300", "blue".no_fill
— If set toTrue
, the area inside therectangle
will be transparent.fill
— Optional argument for rendering therectangle
filled with either alinear_gradient
orradial_gradient
.border_size
— The border thickness in pixels.border_color
— The border will be drawn in this color. Use HTML colors e.g. "#ff3300", "blue".border_style
— Sets the border as either solid (default = "none") or "dash" for a dashed border, or "dot" for a dotted border.image
— A URL that identifies a JPEG, GIF, SVG or PNG image.opacity
— Therectangle
will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent.visible
— Therectangle
can be hidden from view by setting this flag toFalse
.motion_map
— This flag tells Tychos to attach a series of strobe images called a motion map.label_text
- The text of an attached label.label_color
- The color of the attached label text.label_font
- The font family of the attached label text.label_style
- A dictionary whose key-value pairs match CSS font styling attributes of the attached label text.
These attributes may also be modified on the rectangle
object after it is created. In particular, one will usually change the pos
attribute in the Calculations editor to show movement. e.g.
rectangle.remove()
rectangle
objects, like all Tychos objects can be removed from the scenario world scope. Once this done, you will not be able to reference the object as it will be removed from your scenario's collection of viewable objects.
rectangle.rotate
You can also rotate a rectangle
object in order to simulate rotational behavior.
rectangle.rotate(angle=0, axis=vec(0, 0))
— Rotates the rectangle
object by a given angle value in radian units. You can also provide an optional matrix that identifies the center of rotation. This method should only be called from the Calculations code editor.
Example:
rectangle.image
Just as with circle
objects, rectangle
objects can also be represented with an image by setting the image attribute of the object.
arc
The arc
object represents a graphical elliptical arc that sweeps out from a starting angular position to an ending angular position.
Below is the constructor for the arc
object that shows its default values:
pos
— The initial center position of yourarc
as a vector withx,y,z
coordinates.size
— The size of thearc
ellipse given as a vector withx,y,z
coordinates.start
— The starting angular value for the arc sweep.end
— The ending angular value of the arc sweep.mode
— The render mode which can be "chord
", "open
", or "pie
".no_fill
— If set toTrue
, the area inside thearc
will be transparent.fill
— Optional argument for rendering thearc
filled with either alinear_gradient
orradial_gradient
.color
— Thearc
will be filled in this color. Use HTML colors e.g. "#ff3300", "blue".border_size
— The border thickness in pixels.border_color
— The border will be drawn in this color. Use HTML colors e.g. "#ff3300", "blue".border_style
— Sets the border as either solid (default = "none") or "dash" for a dashed border, or "dot" for a dotted border.opacity
— Thearc
will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent.visible
— Thearc
can be hidden from view by setting this flag toFalse
.motion_map
— This flag tells Tychos to attach a series of strobe images called a motion map.
arc.remove()
arc
objects, like all Tychos objects can be removed from the scenario world scope. Once this done, you will not be able to reference the object as it will be removed from your scenario's collection of viewable objects.
arc.rotate
You can also rotate an arc
object in order to simulate rotational behavior.
arc.rotate(angle=0, axis=vec(0, 0))
— Rotates the arc
object by a given angle value in radian units. You can also provide an optional vector that identifies the center of rotation. This method should only be called from the Calculations code editor.
arrow
The arrow
object represents a graphical arrow and is commonly used to illustrate vectors, but can be used for representing anything in your simulations.
Below is the constructor for the arrow
object that shows its default values:
pos
— The initial position of yourarrow
tail as a vector withx,y,z
coordinates.size
— The size of thearrow
given as a vector withx,y,z
coordinates.color
— Thearrow
will be drawn in this color. Use HTML colors e.g. "#ff3300", "blue".stroke
— Thearrow
thickness in pixels.style
— Anarrow
can have a "dash" style, or a "dot" style, or "none" which is the default.opacity
— Thearrow
will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent.show_components
— This flag tells Tychos to attach additional x and y component arrows.visible
— Thearrow
can be hidden from view by setting this flag toFalse
.motion_map
— This flag tells Tychos to attach a series of strobe images called a motion map.
arrow.remove()
arrow
objects, like all Tychos objects can be removed from the scenario world scope. Once this done, you will not be able to reference the object as it will be removed from your scenario's collection of viewable objects.
line
The line
class draws a line and is commonly used to illustrate some connecting member like a string or cable, but could really represent anything you like.
Below is the constructor for the line
class that shows its default values:
pos
— coordinates for the starting point of theline
as vectorpos2
— coordinates of the termination point of theline
as a vector.color
— HTML color value for yourline
, e.g. "red" or "#ff0000".stroke
— Stroke value that determines the visual thickness of theline
. This is measured in pixels.style
— Sets theline
as either solid (default = "none") or "dash" for a dashed line, or "dot" for a dotted line.opacity
— Theline
will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent.visible
— Theline
can be hidden from view by setting this flag toFalse
.motion_map
— This flag tells Tychos to attach a series of strobe images called a motion map.
line.remove()
line
objects, like all Tychos objects can be removed from the scenario world scope. Once this done, you will not be able to reference the object as it will be removed from your scenario's collection of viewable objects.
poly_line
The poly_line
class draws a series of connected lines between a given set of points. This object can be used to represent a complex path or a shape other than a circle or rectangle.
Below is the constructor for the poly_line
class that shows its default values:
pos
— coordinates for the starting point of thepoly_line
as a vector.color
— HTML color value for yourpoly_line
, e.g. "red" or "#ff0000".stroke
— Stroke value that determines the visual thickness of thepoly_line
. This is measured in pixels.style
— Can be"none"
for solid segments,"dash"
for dashed line segments or"dot"
for dotted line segments.fill
— Boolean value (True or False) for displaying thepoly_line
object as a filled in solid with a color, or an optional argument for rendering the inside area with either alinear_gradient
orradial_gradient
object.opacity
— Thepoly_line
will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent.visible
— Thepoly_line
can be hidden from view by setting this flag tofalse
.motion_map
— This flag tells Tychos to attach a series of strobe images called a motion map.
poly_line
objects have a number of methods for manipulating the poly_line
points, like adding new points, changing existing points, removing points, etc:
set_points: (points)
-> Set the points for thepoly_line
given aList
of points.translate: (delta_position)
-> Move all the points according to a vector.rotate: (angle, axis)
-> Transform the points a certain angle measurement about an axis. This axis is relative to the first point in thepoly_line
.npoints():
-> Returns the number of points in thepoly_line
.append: (*points)
-> Add a point (or many points) to the end of thepoly_line
.unshift: (*points)
-> Add a point (or many points) at the beginning of thepoly_line
.shift: ()
-> Remove the first point in thepoly_line
object.splice: (start, how_many, *points)
-> Insert a point or several points anywhere at the specific index position. You can also identify how many points you would like to remove from thepoly_line
as well.pop: (n)
-> Get the vector for point number n and remove it. Can use negative values, where -1 is the last point, -2 the next to the last, etc.clear: ()
-> Remove all the points in thepoly_line
.modify: (n, point)
-> Modify the point at the specified n position, replacing it with the given vector.slice: (start, end)
-> Returns the set of points (but does not remove them) from thepoly_line
object beginning at thestart
value and ending at theend
index position.
poly_line.remove()
poly_line
objects, like all Tychos objects can be removed from the scenario world scope. Once this done, you will not be able to reference the object as it will be removed from your scenario's collection of viewable objects.
spring
A spring
is a visual representation of a common elastic connector that displays a given number of coils that dynamically change shape once the dimensions of the spring
are changed in the Calculations Pane.
The code below shows the three different spring
objects above that have different lengths, widths and coil numbers. The circle
objects are shown just for reference.
Below is the constructor for the spring
class that shows its default values:
pos
— coordinates for the starting point of thespring
as a 2D vector.pos2
— coordinates of the termination point of thespring
as 2D vectorcolor
— HTML color value for yourspring
, e.g. "red" or "#ff0000".coils
— The number "coil" zig-zags.width
— The width of the "coil" zig-zags.stroke
— Stroke value that determines the visual thickness of thespring
. This is measured in pixels.opacity
— Thespring
will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent.visible
— Thespring
can be hidden from view by setting this flag tofalse
.motion_map
— This flag tells Tychos to attach a series of strobe images called a motion map.
These attributes may also be modified after the spring
is created.
spring.remove()
spring
objects, like all Tychos objects can be removed from the scenario world scope. Once this done, you will not be able to reference the object as it will be removed from your scenario's collection of viewable objects.
label
You can add text labels to any scenario using the label
object.
Below is the constructor for the label
class that shows its default values:
pos
— coordinates for the center point of thelabel
as a 2D vector.size
— The width and height of thelabel
as a 2D vector.text
— The text of thelabel
as a string.color
— HTML color value for yourlabel
, e.g. "red" or "#ff0000".font
— CSS font family identifier, e.g. "Times", or "Courier"style
— A dictionary with key value pairs that represent CSS font styling rules.opacity
— Thelabel
will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent.visible
— Thelabel
can be hidden from view by setting this flag toFalse
.motion_map
— This flag tells Tychos to attach a series of strobe images called a motion map.
These attributes may also be modified after the label
object is created.
label.remove()
label
objects, like all Tychos objects can be removed from the scenario world scope. Once this done, you will not be able to reference the object as it will be removed from your scenario's collection of viewable objects.
label.rotate(angle=0)
You can rotate a label as shown below:
World
The world object represents the viewable area of the scenario.
world.set_extents
You can set the viewable extents of the world in the Settings Pane, or by calling the following method on the world object:
The inputs are two vector objects representing the center position of the view of the world, and secondly the size of the viewable world.
Gradient Fills
The radial_gradient
and linear_gradient
objects are used as fill parameters for the following objects:
circle
rectangle
ellipse
arc
poly_line
radial_gradient
Below is the constructor for the radial_gradient
object that shows its default values:
radial_gradient(
start_x=50,
start_y=50,
end_x=50,
end_y=50,
colors=[]
offsets=[]
)
start_x
— This attribute defines the relative x position (as a percentage) of the start the radial gradient.start_y
— This attribute defines the relative y position (as a percentage) of the start the radial gradient.end_x
— This attribute defines the relative x position (as a percentage) of the end the radial gradient.end_y
— This attribute defines the relative y position (as a percentage) of the end the radial gradient.colors
— A list of HTML color values for yourradial_gradient
, e.g. "red" or "#ff0000".offsets
— A list of corresponding numerical values defining where the associated gradient stop is placed along the gradient.
Example:
linear_gradient
Below is the constructor for the linear_gradient
object that shows its default values:
linear_gradient(
angle=0,
colors=[]
offsets=[]
)
angle
— This attribute transforms the linear gradient by rotating the gradient from the relative center position of the filled object. The value is defined in radians.colors
— A list of HTML color values for yourradial_gradient
, e.g. "red" or "#ff0000".offsets
— A list of corresponding numerical values defining where the associated gradient stop is placed along the gradient.
Interface Widgets
Tychos also provides several "widgets" for displaying data in different ways as well as adding user interactivity so that your simulations can respond to input.
graph
A graph
is a 2-dimensional chart of data that you specify in the Initial State editor. Each graph
that is created will appear by default on the right side of the World View, but can be aligned to the left instead. Your program needs to add points to the graph with the plot
command.
Here is the constructor for creating a graph
object
title
= Optional text that will appear at the top of the graph.align
= Optional value of "left
" or "right
" to align the graph to the corresponding side of the view window.y_axis
= Optional text that will appear on the left side of the graph as the vertical axis label.x_axis
= Optional text that will appear at the bottom of the graph as the horizontal axis label.width
= Optional numeric value in pixels for setting the width, or a text value percentage e.g. "50%" or "90%".height
= Optional numeric value in pixels for setting the height, or a text value percentage e.g. "50%" or "90%".plot_rate
= Optional numerical value greater than 0 that sets the individual graph's plotting schedule. This over rides the default Graph Strobe Rate value set in the Settings tab.
Plotting Values
To plot values for the graph, the plot
method is used. You can either plot points by calling the plot method with the x and y arguments set to single numerical inputs, or to plot more than a single point, you can instead set the x and y arguments to be lists of numerical values.
When plotting, Tychos will plot the points you specify when the simulation plot timer has expired. This is called "strobing" the graph. There is a default plot timer set in the Settings tab called Graph Strobe Rate for the scenario, but this can be over ridden by setting the graph's plot rate.
Note that depending on the simulation step time and the graph plot rate, graph plots may not appear on the graph at the exact time specified by the graph plot rate. For example, if the plot rate is actually faster than the animation step rate, the plotting of the points will not appear to be in sync because the animation is actually running slower than rate at which points should be plotted.
The arguments for the plot method are shown below:
x
= This is either a single numerical value or a list of numerical values.y
= This is either a single numerical value or a list of numerical values.color
= Optional "line" or "scatter" that will either display the points as connected with lines, or not. The default is to connect the plotted points with lines.mode
= Optional "line" or "scatter" that will either display the points as connected with lines, or not. The default is to connect the plotted points with lines.fill
= Optional boolean value for filling in the plotted area.
Clearing Values
To clear values for the graph, the clear
method is used. Clearing the plotted values occurs immediately when the method is called, clearing all the plotted values from the graph:
bar_chart
A bar_chart
is a chart of data that is displayed as a set of bars representing an array of data values. Each bar_chart
that is created will appear on the right side of the World View.
title
= Optional text that will appear at the top of thebar_chart.
align
= Optional value of "left
" or "right
" to align the bar chart to the corresponding side of the view window.min
= Optional minimum value whose default is 0. If any bar data value is less than this minimum, the bar will be truncated.max
= Optional maximum value whose default is 1. This sets the maximum viewable bar height. If any bar data value is greater than this maximum, the bar will be truncated.width
= Optional numeric value in pixels for setting the width, or a text value percentage e.g. "50%" or "90%".height
= Optional numeric value in pixels for setting the height, or a text value percentage e.g. "50%" or "90%".
bar_chart.data
bar_chart.data
— Sets the data values for the bars in the bar chart.
bar_chart.labels
bar_chart.labels
— Defines a set of labels - one label corresponding to each data bar in the chart. If the number of labels does not match the number of bars set by the number of data values, then a numbered label will be assigned to the extra data value.
bar_chart.colors
bar_chart.colors
— List of colors, one color corresponding to each data bar in the chart. If the number of colors does not match the number of bars set by the number of data values, then any extra bars will be given the default HTML color of #aaa
.
pie_chart
A pie_chart
is a chart of data that is displayed as circle that is "sliced" into different pieces of a "pie" representing the relative proportion to the sum of all the values in the chart's data. Each pie_chart
that is created will appear on the right side of the World View by default, but can be aligned to the left.
The constructor options for adding a pie_chart
to your scenario are the following:
title
= Optional text that will appear at the top of thepie_chart.
align
= Optional value of "left
" or "right
" to align thepie_chart
to the corresponding side of the view window.width
= Optional numeric value in pixels for setting the width, or a text value percentage e.g. "50%" or "90%".height
= Optional numeric value in pixels for setting the height, or a text value percentage e.g. "50%" or "90%".
pie_chart.data
pie_chart.data
— Sets the data values for the pie slices in the pie chart.
pie_chart.labels
pie_chart.labels
— Defines a set of labels - one label corresponding to each data slice in the chart. If the number of labels does not match the number of data values, then a numbered label will be assigned to the extra data value.
pie_chart.colors
pie_chart.colors
— List of colors, one color corresponding to data value in the chart. If the number of colors does not match the number of data values, then any extra values will be given the default colors.
table
A table
displays data organized in columns and rows.
Each table
that is created will appear on the right side of the World View. When creating a table
you can give it a title, and will need to define the column names for the table
. You can also optionally define the precision for the numerical values being displayed in the table.
Below is the constructor for the table
widget and default values:
table(title="Table", align="right", columns=[], precision=4)
title
= Optional text that will appear at the top of thetable
widget.align
= Optional value of "left
" or "right
" to align the table to the corresponding side of the view window.columns
— A list of strings representing the column names that will appear in the table.precision
— Optional precision level for representing numerical values.
table.add_row([value1, value2, ...])
table.add_row([values])
— This adds a row of data to the table. Keep in mind that you must supply a list of values whose length is equal to that of the columns in the table.
values
= A list of values corresponding to the columns in the table.
Example:
meter
A meter
is a numeric display of data. Each meter
that is created will appear on the left side of the World View. Your program needs to tell the meter
what value it needs to display by using the display
command.
Below is the constructor for the meter
widget and default values:
meter(title="Meter", align="left", color="black", suffix="")
title
= Optional text that will appear at the top of themeter
widget.align
= Optional value of "left
" or "right
" to align the meter to the corresponding side of the view window.color
— HTML color value for yourmeter
, e.g. "red" or "#ff0000".suffix
— text added at the end of the data value display.
meter.display()
meter.display(value)
— Displays the value on the meter
.
value
= Numeric value to be displayed.
Example:
gauge
A gauge
is an analog display of data that is very similar to a meter
that you specify in the Initial Sate pane. Each gauge
that is created will appear on the left side of the World View. Gauges also need to to be set up with a specific minimum and maximum value for identifying the range of the gauge
. Your scenario needs to tell the gauge
what value it needs to display by using the display
command.
Below is the constructor for the Gauge
widget and default values:
gauge(title="Gauge", align="left", min=0, max=100, color="black")
title
= Optional text that will appear at the top of thegauge
widget.align
= Optional value of "left
" or "right
" to align the gauge to the corresponding side of the view window.min
= The minimum value of thegauge
max
= The maximum value of thegauge
color
— HTML color value for yourgauge
, e.g. "red" or "#ff0000".
gauge.display()
gauge.display(value)
— Displays the value in the Gauge.
Example: