> For the complete documentation index, see [llms.txt](https://docs.tychos.org/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tychos.org/docs/learn/language-reference-api-1.md). # Tychos MathJs Language Reference The following reference guide identifies the language syntax, built in variables, functions, and classes that are used to code your simulations in Tychos. Tychos uses the [MathNotepad language](http://mathnotepad.com/docs/functions.html). We have included documentation here for some of the helpful functions defined in the MathNotepad language. This is not a complete list of all functions available in MathNotepad, 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: ``` # This is a comment. ``` ## 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 ```coffeescript # Assigns a variable called x the value of 10 x = 10 # Assign a new variable y the value of the x y = x # Assign x the value of itself plus 1 x = x + 1 ``` ## 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... * `X`, `Y` , `Z`— These are shortcuts for indexing the first two elements of 3-D matrices, e.g. `my_particle.pos[X]` ## 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: #### **pow(base, power)** The `pow(base, power)` function takes two arguments, raising the `base` by the `power`. ```coffeescript # returns number 8 pow(2,3) ``` #### **sqrt(positive\_number)** The `sqrt(positive_number)` function takes a single non negative number and returns the real square root of the number. ```coffeescript # returns number 2 sqrt(4) ``` #### **abs(number)** The `abs(number)` function returns the absolute value of a number. ```coffeescript # returns number 2 abs(-2) ``` ### 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. ```coffeescript # returns number 1 sin(PI/2) ``` #### **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. ```coffeescript # returns number 1 cos(0) ``` #### **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. ```coffeescript # returns number 1 tan(PI/4) ``` #### **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. ```coffeescript # returns number 1.57 asin(1) ``` #### **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. ```coffeescript # returns number 0 acos(1) ``` #### **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. ```coffeescript # returns number -0.785 atan2(-1, 1) # returns 2.36 atan2(1, -1) ``` #### **deg\_to\_rad(angle)** See below. **radians(angle)** The `deg_to_rad(angle)` function is not part of the MathNotepad language but is provided as a helper function to make the conversion from degree angles to radians easier. The input is an angle measurement in degrees and the output is the angle measurement in radians. ```coffeescript # returns number .785 deg_to_rad(45) ``` #### **rad\_to\_deg(angle)** See below. **degrees(angle)** The `degrees(angle)` function is not part of the MathNotepad language but is provided as a helper function to make the conversion from radian angles to degrees easier. The input is an angle measurement in radians and the output is the angle measurement in degrees. ```coffeescript # returns number 180 degrees(PI) ``` ### Matrix Functions The following functions provide operations for matrix calculations. #### **dot(x, y)** Calculates the dot product of two vectors. The dot product of `x = [a1, a2, a3, ..., an]` and `y = [b1, b2, b3, ..., bn]` is defined as: `dot(x, y) = a1 * b1 + a2 * b2 + a3 * b3 + … + an * bn` ```coffeescript # Work is the dot product of Force (F) and displacement (r) F = [2, 2] r = [3, 3] # returns 12 Work = dot(F, r) ``` #### **cross** Calculates the cross product for two vectors in three dimensional space. The cross product of `x = [a1, a2, a3]`and `y = [b1, b2, b3]` is defined as: `cross(x, y) = [ a2 * b3 - a3 * b2, a3 * b1 - a1 * b3, a1 * b2 - a2 * b1 ]` If one of the input vectors has a dimension greater than 1, the output vector will be a 1x3 (2-dimensional) matrix. ```coffeescript # Torque is the cross product of Force and moment arm (r) F = [2, 0, 0] r = [0, 2, 0] # returns matrix [0, 0, 4] cross(F, r) ``` ## Other Useful Functions Some other useful functions... **random(min, max)** Return a random number larger or equal to min and smaller than max using a uniform distribution. If now min or max are given, then it returns a random value from 0 to 1. If just one value is given, then it returns a random number between 0 and the input value. ```coffeescript # returns a random number between 0 and 1 random() # returns a random number between 0 and 100 random(100) # returns a random number between 30 and 40 random(30, 40) # returns a 2x3 matrix with random numbers between 0 and 1 random([2, 3]) ``` #### string(object) Create a string or convert any object into a string. Elements of Arrays and Matrices are processed element wise. #### format(value, precision) Formats a value into a string. You have several options for how this value will be formatted: ```coffeescript # returns '0.333' format(1/3, 3) # returns '21000' format(21385, 2) # returns '1200000000' format(12e8, {notation: 'fixed'}) # returns '2.3000' format(2.3, {notation: 'fixed', precision: 4}) ``` #### **concat(A, B...*****dim*****)** Concatenate two or more matrices. This function can also be used to concatenate strings together. `dim: number` is a zero-based dimension over which to concatenate the matrices. By default the last dimension of the matrices. ```coffeescript A = [1, 2] B = [3, 4] concat(A, B) # returns [1, 2, 3, 4] math.concat(A, B, 0) # returns [[1, 2], [3, 4]] math.concat('hello', ' ', 'world') # returns 'hello world' ``` #### **unit\_vector** 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. `unit_vector(vec)` -> returns a vector of length 1, and in same direction as `vec`. * `vec` - any two dimensional vector as a \[X, Y] matrix. Example: ```coffeescript u = unit_vector([3, 4]) # returns [0.6, 0.8] magnitude(u) # returns 1 ``` #### **magnitude** 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 its direction. `magnitude(vec)` -> returns the scaler magnitude of the vector `vec`. * `vec` - any two dimensional vector as a \[X, Y] matrix. Example: ```coffeescript magnitude([3, 4]) # returns 5 ``` #### **direction** 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 default return angle is given in radians, but can also be expressed in degrees. `direction(vec, units="rad")` -> returns the scaler angle measurement of the vector `vec` heading in radian form or in degree form. * `vec` - any two dimensional vector as a \[X, Y] matrix. * `units` - optional `deg` for degree measurement or the default of `rad` for radians. Example: ```coffeescript direction([4, 4]) # returns .785 direction([4, 4], "deg") # returns 45 ``` #### polar This function returns a two-dimensional matrix representing the cartesian components of a polar coordinate corresponding to the magnitude of the radius and the radial angle. `polar(radius, angle, units="rad")` -> returns a two dimensional vector as a \[X, Y] matrix. * `radius` - scalar quantity representing the scalar distance of the radius of the * `angle` - scalar quantity representing the angle measurement of the polar coordinate. * `units` - optional `deg` for degree measurement or the default of `rad` for radians. Example: ```coffeescript polar(10, 45, "deg") # returns [7.07, 7.07] polar(10, PI/4) # returns [7.07, 7.07] ``` #### stop This function actually evaluates a boolean test and then stops the simulation once the boolean test succeeds. This can be useful if you want the simulation to stop when some condition has been met within your simulation. `stop(test)` -> returns a either false or true. If true is returned, the simulation stops. * `test` - a boolean statement that can be evaluated to `true` or `false`. Example: ```coffeescript stop(t > 10) # simulation stops at 10 seconds stop(buggy.pos[X] == 100) # simulation stops when X position of particle equals 100 ``` #### between This function tests whether a value is strictly between a minimum and maximum value. It returns `true` if `min < value < max`, otherwise `false`. `between(value, min, max)` -> returns a boolean `true` or `false`. * `value` - a scalar number to test. * `min` - the lower bound (exclusive). * `max` - the upper bound (exclusive). Example: ```coffeescript between(5, 0, 10) # returns true between(0, 0, 10) # returns false (0 is not strictly greater than 0) between(10, 0, 10) # returns false (10 is not strictly less than 10) ``` ### Collision Functions 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. #### hasCollided 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.* `hasCollided(source, target)` -> returns a boolean `true` or `false`. * `source` - `Circle` or `Rectangle` object * `target` - `Circle` or `Rectangle` object Example: ![](/files/-M1H2ldqYMhdQkM2Jgls) ```coffeescript # Setup Code p1 = Circle({pos:[15, 0], radius:10, color:rgba(0, 200, 200, .6)}) b1 = Rectangle({pos:[0, 0], size:[15, 15], color:rgba(200, 0, 200, .6)}) b1.rotate(radians(45)) p3 = Circle({pos:[-15, 0], radius:10, color:rgba(0, 0, 200, .6)}) ``` ```coffeescript # Loop Code hasCollided(p1, b1) # returns true hasCollided(b1, p3) # returns true hasCollided(p1, p3) # returns false ``` #### getIntersect This function returns a two dimensional matrix 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. `getIntersect(source, target)` -> returns a two dimensional matrix. * `source` - `Circle` or `Rectangle` object * `target` - `Circle` or `Rectangle` object Example: ![](/files/-M1H6tG9DYavjNO3G2O5) ```coffeescript # Setup Code p1 = Circle({pos:[0, 0], radius:10, color:rgba(200, 200, 200, .6)}) p2 = Circle({pos:[12, 10], radius:10, color:rgba(0, 200, 0, .6)}) b1 = Rectangle({pos:[-12, 0], size:[15, 15], color:rgba(200, 0, 0, .6)}) mtv1 = Arrow({pos:[p1.pos], color:"green"}) mtv2 = Arrow({pos:[p1.pos], color:"red"}) ``` ```coffeescript # Loop Code mtv1.size = getIntersect(p1, p2) mtv2.size = getIntersect(p1, b1) ``` #### getMTV This function returns a two-dimensional matrix representing the *minimum translation vector* (MTV) needed to separate two overlapping objects. `getIntersect` is an alias for this function. `getMTV(source, target)` -> returns a two dimensional matrix. * `source` - `Circle` or `Rectangle` object * `target` - `Circle` or `Rectangle` object Example: ```coffeescript # Loop Code mtv = getMTV(p1, p2) # same as getIntersect(p1, p2) ``` #### getRotatedPosition This function returns the new position of a point after being rotated by a given angle around an axis point. This is useful for simulating rotational motion of objects orbiting a fixed center. `getRotatedPosition(pos, angle, axis)` -> returns a two dimensional matrix. * `pos` - the original position as an `[X, Y]` matrix. * `angle` - the rotation angle in radians. * `axis` - the center of rotation as an `[X, Y]` matrix. Example: ```coffeescript # Setup Code p = Circle({pos:[10, 0], radius:3}) ``` ```coffeescript # Loop Code p.pos = getRotatedPosition(p.pos, 0.05, [0, 0]) # orbit around origin ``` ### Comparison Functions The following functions are used to compare two values as being equal or unequal as well as testing if one value is larger or smaller than another. These are very helpful when writing goals for students. #### `equal(a, b)` **or** `a == b` The function tests if two values (x and y) are equal. It returns a boolean value of `true` or `false`. ```coffeescript 2 + 2 == 3 # returns false 2 + 2 == 4 # returns true t == 10 # returns true if t is 10, or false if it is not. equal(2 + 2, 4) # same as 2 + 2 == 4 ``` #### **deepEqual(a, b)** This function is similar to `equal`, but it tests element wise whether two matrices are equal. It returns a boolean value of `true` or `false`. The code below demonstrates the difference between `equal` and `deepEqual`: ```coffeescript p1 = Circle({pos:[10, 10]}) p2 = Circle({pos:[10, 0]}) deepEqual(p1.pos, p2.pos) # returns false equal(p1.pos, p2.pos) # returns [true, false] ``` #### `larger(a, b)` or `a > b` The function tests if one value (a) is larger than another (b). It returns a boolean value of `true` or `false`. ```coffeescript 2 > 3 # returns false 3 > 2 # returns true 2 > 2 # returns false larger(2, 2) # same as 2 > 2 ``` #### `smaller(a, b)` or `a < b` The function tests if one value (a) is smaller than another (b). It returns a boolean value of `true` or `false`. ```coffeescript 2 < 3 # returns true 3 < 2 # returns false 2 < 2 # returns false smaller(2, 2) # returns false ``` #### `unequal(a, b)` or `a != b` The function tests if two values (a and b) are unequal. It returns a boolean value of `true` or `false`. ```coffeescript 2 + 2 != 3 # returns true unequal(2 + 2, 3) # true -- same as 2 + 2 != 3 2 + 2 != 4 # returns false t != 10 # returns false if t is 10, or true if it is not. ``` Comparison operators return `true` or `false` but these also evaluate to 1 (true) or 0 (false). This can allow you to conditionally assign a value to a variable depending on the evaluation of the comparison. See the code below as an example: ```coffeescript # If t is larger than 10, then the value of F is [10, 10], otherwise it is 0. F = (t > 10) * [10, 10] ``` #### `if(test, true_result, false_result)` The `if()` function returns `true_result` or `false_result` depending on `test`. ```coffeescript if(true, 3, 44) # returns 3 if(false, 3, 44) # returns 44 if(1 > 2, 3, 44) # test is false; therefore returns 44 a = 1 b = 1 if(a == b, "YAY", "darn") # test is true; therefore returns "YAY" ``` ### 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. ```coffeescript A = true B = true A and B # returns true B = false A and B # returns false ``` You can use the `and` operator to test if two comparisons are both true: ```coffeescript x = 2 (x < 3) and (x == 2) # returns true (x < 3) and (x != 2) # returns false ``` #### **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. ```coffeescript A = true B = false A or B # returns true A = false A or B # returns false ``` You can use the `or` operator to test if one of two comparisons are true: ```coffeescript x = 2 smaller(x, 3) or equal(x, 3) # one is true, so returns true (x < 1) or (x == 3) # both are false, so returns false ``` ## Built-in Classes Tychos has several classes for creating simulated objects and analyzing them. The graphical objects available are the `Circle`, the `Rectangle`, the `Ellipse`, the `Arc`, the `Arrow`, the `Line`, the `PolyLine`, the `Label`, the `Spring`, and the `Sprite`. The analysis tools are the `Graph`, the `Gauge`, and the `Meter`. There are also interactive input objects: the `Toggle`, the `Slider`, the `Input`, and the `Menu` controls. ### Common Attributes The following attributes are shared by most graphical objects in Tychos. Exceptions are noted in individual class sections below. #### `pos` — matrix The position of the object in the World as an `[X, Y]` matrix. This is a world-space coordinate, not a pixel position. #### `color` — string The object will be drawn in this color. Use HTML color names (e.g. `"blue"`) or hex codes (e.g. `"#ff3300"`), or use the [`rgba`](/docs/learn.md#rgba-r-g-b-a) function. #### `opacity` — number The object will be drawn with an opacity between `1` (fully opaque) and `0` (fully transparent). #### `image` — string **Circle, Rectangle, Ellipse**, and **Arc** objects can be displayed as an image by setting this attribute to a URL pointing to a PNG, SVG, GIF, or JPEG file. ```coffeescript rocket = Circle({pos:[0, 0], radius:10}) rocket.image = "https://upload.wikimedia.org/wikipedia/commons/3/3d/Spacecraft.png" ``` #### `no_fill` — boolean If `true`, the interior area of the object is transparent — only the border is drawn. Applies to **Circle, Rectangle, Ellipse, Arc**, and **PolyLine** objects. #### `fill` — object Set to a `LinearGradient` or `RadialGradient` object to render the interior with a gradient instead of a solid color. Applies to **Circle, Rectangle, Ellipse, Arc**, and **PolyLine** objects. #### `visible` — boolean Set to `false` to hide the object from view without removing it. #### `motion_map` — boolean When `true`, Tychos attaches a series of "strobe" images behind the object as it moves, creating a motion map. ### Labels The **Circle, Rectangle, Ellipse**, and **Arc** objects can display a text label that scales with the object. Set it using an object with `text`, `color`, and optional `font` properties: ```coffeescript c.label = {text: "Hello", color: "white"} c.label = {text: "Hi", color: "white", font: "Courier"} ``` ### Borders **Circle, Rectangle, Ellipse, Arc**, and **PolyLine** objects support borders. #### `border_size` — number Border thickness in pixels. Default is `0` (no border). #### `border_color` — string Border color. Use HTML color names or hex codes. #### `border_style` — string `"none"` (default, solid fill), `"dash"` for a dashed border, or `"dot"` for a dotted border. ```coffeescript c = Circle({pos:[0,0], radius:20, color:"lightblue", border_size:3, border_color:"navy", border_style:"dash"}) ``` ### Effects Objects can be visually altered with the following attributes. #### `skew_x` — number Skews the object's coordinate map by this angle (in radians) about its X axis. #### `skew_y` — number Skews the object's coordinate map by this angle (in radians) about its Y axis. #### `flip_x` — boolean Mirrors the object about its X axis. #### `flip_y` — boolean Mirrors the object about its Y axis. #### `blur` — number Sets the standard deviation of a Gaussian blur applied to the object. #### `blend_mode` — string Sets the CSS `mix-blend-mode`, controlling how the object composites with objects beneath it. Accepts any valid CSS blend mode value: `"multiply"`, `"screen"`, `"overlay"`, `"darken"`, `"lighten"`, `"difference"`, `"exclusion"`, and others. ```coffeescript c = Circle({pos:[0,0], radius:20, color:"red", blend_mode:"multiply"}) ``` ### Mouse Interaction All graphical objects (Circle, Rectangle, Ellipse, Arc, Sprite, Arrow, Line, Label, etc.) can detect mouse events. Assign a function to any of the following event attributes to make your simulation interactive. **Event Attributes** * `on_click` — Triggered when the mouse button is pressed and released on the object. * `on_double_click` — Triggered when the mouse button is double-clicked on the object. * `on_mouse_down` — Triggered when the mouse button is pressed down while over the object. * `on_mouse_up` — Triggered when the mouse button is released while over the object. * `on_mouse_over` — Triggered while the mouse pointer is over the object. * `on_mouse_out` — Triggered when the mouse pointer moves off the object. **How to Use** Define a function that accepts a single argument (the object that triggered the event) using MathJS function definition syntax, then assign it to the event attribute without parentheses. **Examples** Click to change color: ```coffeescript # Setup Code c1 = Circle({pos:[0, 0], radius:10, color:"red"}) c2 = Circle({pos:[25, 0], radius:10, color:"blue"}) changeColor(target) = (target.color = "green") c1.on_click = changeColor c2.on_click = changeColor ``` Hover highlight: ```coffeescript # Setup Code btn = Rectangle({pos:[0, 0], size:[40, 20], color:"gray"}) hoverOn(target) = (target.color = "white") hoverOff(target) = (target.color = "gray") btn.on_mouse_over = hoverOn btn.on_mouse_out = hoverOff ``` Dragging an object (using Loop Code to track `mouse.pos`): ```coffeescript # Setup Code box = Rectangle({pos:[0, 0], size:[20, 20], color:"orange"}) ``` ```coffeescript # Loop Code if mouse.is_down() and mouse.is_over(box) box.pos = mouse.pos end ``` ### Common Methods #### `remove()` Permanently removes the object from the simulation. The object will no longer appear in the World View. ```coffeescript c = Circle({pos:[0,0], radius:10}) c.remove() ``` #### `rotate(angle=0, axis=[0, 0])` Rotates the object by a given angle in radians. You can also provide an optional `[X, Y]` axis of rotation. Note: `Line`, `Arrow`, and `Spring` objects cannot be rotated — update their `pos2` attribute to change direction instead. #### `clone()` Creates and returns a duplicate of the object that can be modified independently. ```coffeescript c1 = Circle({pos:[0, 0], radius:10, color:"blue"}) c2 = c1.clone() c2.pos = [20, 0] c2.color = "red" ``` ### Circle A `Circle` is drawn as a colored circle in the World View. A `Circle` has a position, a radius, a color, an opacity, a flag for setting its visibility state, and a flag for determining if a motion map should be attached. ![](https://tychos.org/static/writing_scenarios/particle.png) Below is the constructor for the `Circle` class that shows its default values: ```coffeescript Circle( {pos:[0,0], radius:10, color:default_color, no_fill: false, fill: null, image: "", opacity: 1, visible: true, motion_map: false, label: {text: "", color: default_color, font: "default"}, border_size: 0, border_color: default_color, border_style: "none", skew_x: 0, skew_y: 0, flip_x: false, flip_y: false, blur: 0 } ) ``` * `pos` — The initial position of your `Circle` in `[X,Y]` coordinates. * `radius` — The radius of the circle drawn in the World View. * `color` — The circle will be drawn in this color. Use HTML colors e.g. `"#ff3300"`, `"blue"`. * `no_fill` — If `true`, the interior is transparent; only the border is drawn. * `fill` — Optional `LinearGradient` or `RadialGradient` object for gradient fills. * `image` — A URL that identifies a JPEG, GIF, SVG or PNG image to display inside the circle. * `opacity` — A value between `1` (fully opaque) and `0` (fully transparent). * `visible` — Set to `false` to hide the circle from view. * `motion_map` — When `true`, attaches a series of strobe images as a motion map. * `label` — Attaches a text label. Set `text`, `color`, and optionally `font`. * `border_size` — Border thickness in pixels. * `border_color` — Border color. * `border_style` — `"none"` (solid), `"dash"`, or `"dot"`. * `skew_x`, `skew_y` — Skew transforms in radians. * `flip_x`, `flip_y` — Mirror the circle about each axis. * `blur` — Gaussian blur standard deviation. 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 Loop Code editor to show movement. e.g. ```coffeescript # Setup Code c = Circle() c_big = Circle({pos:[50, 0], radius:25}) c_big.color = "red" c_green = Circle({pos:[100, 0], color: "green", opacity: .5}) ``` ```coffeescript # Loop Code c.pos = c.pos + [1, 0.25] ``` #### Circle.rotate() `Circle` objects can be rotated. `Circle.rotate(angle=0, axis=[0, 0])` — Rotates the `Circle` object by a given angle value in radian units. You can also provide an optional matrix 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. ``` rocket = Circle({pos:[0, 0], radius:10}) rocket.image = "https://upload.wikimedia.org/wikipedia/commons/3/3d/Spacecraft.png" ``` ![A Circle that looks like a rocket.](/files/-LEMDYX74SDR4RTOlWVn) {% hint style="info" %} The above image also demonstrates the use of the `direction` function as well as the `rotate` method: `rocket.rotate(direction(rocket.v))` {% endhint %} #### Circle.label `Circle` objects can also be given a text label. This is similar to the `Label` object. `c.label = {text:"Hello", color:"green"}` — This adds a text label to the `Circle` object that scales to fit inside the circle. ### Rectangle A `Rectangle` is very similar to a `Circle` but it is represented as a colored rectangle in the World View. A `Rectangle` has position, width, height, color, opacity, visibility, a motion map flag, as well as a label. Just as with the `Circle`, Tychos only uses the width and height attributes for display. You can define how these attributes change given the rules of the simulation that you define. ![](https://tychos.org/static/help/ref/ref_block.png) Below is the constructor for the `Rectangle` class that shows its default values: ```coffeescript Rectangle( {pos:[0,0], size:[10,10], color:default_color, no_fill: false, fill: null, image: "", opacity: 1, visible: true, motion_map: false, label: {text: "", color: default_color, font: "default"}, border_size: 0, border_color: default_color, border_style: "none", skew_x: 0, skew_y: 0, flip_x: false, flip_y: false, blur: 0 } ) ``` * `pos` — The initial position of your `Rectangle` in `[X,Y]` coordinates. * `size` — The width and height of the `Rectangle` as an `[X, Y]` matrix. * `color` — The `Rectangle` will be drawn in this color. Use HTML colors e.g. `"#ff3300"`, `"blue"`. * `no_fill` — If `true`, the interior is transparent; only the border is drawn. * `fill` — Optional `LinearGradient` or `RadialGradient` object for gradient fills. * `image` — A URL that identifies a JPEG, GIF, SVG or PNG image to display inside the rectangle. * `opacity` — A value between `1` (fully opaque) and `0` (fully transparent). * `visible` — Set to `false` to hide the rectangle from view. * `motion_map` — When `true`, attaches a series of strobe images as a motion map. * `label` — Attaches a text label. Set `text`, `color`, and optionally `font`. * `border_size` — Border thickness in pixels. * `border_color` — Border color. * `border_style` — `"none"` (solid), `"dash"`, or `"dot"`. * `skew_x`, `skew_y` — Skew transforms in radians. * `flip_x`, `flip_y` — Mirror the rectangle about each axis. * `blur` — Gaussian blur standard deviation. 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 Loop Code editor to show movement. e.g. ```coffeescript # Setup Code r1 = Rectangle({pos:[0, 0], size:[10, 10], color:"green"}) r2 = Rectangle({pos:[20, 0], size:[10, 20], color:"blue"}) r3 = Rectangle({pos:[40, 0], size:[20, 10], color:"orange"}) ``` ```coffeescript # Loop Code r1.pos = r1.pos + [1, 0.25] ``` #### Rectangle.rotate You can also rotate a `Rectangle` object in order to simulate rotational behavior. `Rectangle.rotate(angle=0, axis=[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. ![Three different Rectangle objects rotated at different angles](/files/-LELi7zhujAo60I3ZA_9) Example: ```coffeescript # Loop Code r1.rotate(-PI/4) r2.rotate(radians(90)) r3.rotate(radians(45)) ``` **Rectangle.image** Just as with `Circle` objects, `Rectangle` objects can also be represented with an image by setting the image attribute of the object. ```coffeescript r.image = "https://some.image.url.jpg" ``` #### Rectangle.label `Rectangle` objects can also be given a text label. This is similar to the `Label` object. ```coffeescript r.label = {text:"Hello", color:"green"} ``` This adds a text label to the `Rectangle` object. ### Ellipse An `Ellipse` is similar to a `Circle` but is drawn as an ellipse (oval) shape. Unlike a `Circle` which uses a single `radius`, the `Ellipse` uses a `size` matrix to define its width and height independently. Below is the constructor for the `Ellipse` class that shows its default values: ```coffeescript Ellipse( {pos:[0,0], size:[10,5], color:default_color, image: "", opacity: 1, visible: true, motion_map: false, angle: 0, axis: [0,0], border_color: default_color, border_size: 0, border_style: "none", label: {text: "", color: default_color} } ) ``` * `pos` — The initial position of your `Ellipse` in `[X,Y]` coordinates. * `size` — The width and height of the ellipse as an `[X,Y]` matrix, e.g. `[20, 10]` creates an ellipse 20 units wide and 10 units tall. * `color` — The ellipse will be drawn in this color. Use HTML colors e.g. "#ff3300", "blue". * `image` — A URL that identifies a JPEG, GIF, SVG or PNG image to fill the ellipse. * `opacity` — The ellipse will be drawn with an opacity between 1 and 0. * `visible` — The ellipse can be hidden from view by setting this flag to `false`. * `motion_map` — This flag tells Tychos to attach a series of strobe images called a motion map. * `angle` — Initial rotation angle in radians. * `axis` — The axis of rotation as an `[X, Y]` matrix. * `border_color` — HTML color for the ellipse border. * `border_size` — Width of the border in pixels. * `border_style` — CSS border style, e.g. `"solid"`, `"dashed"`. * `label` — You can attach a label to the `Ellipse` by indicating the `text` and `color`. Example: ```coffeescript # Setup Code e1 = Ellipse({pos:[0, 0], size:[20, 10], color:"blue"}) e2 = Ellipse({pos:[30, 0], size:[10, 20], color:"red", opacity:0.5}) ``` ```coffeescript # Loop Code e1.pos = e1.pos + [1, 0] e1.rotate(0.05) ``` #### Ellipse.rotate `Ellipse.rotate(angle=0, axis=[0, 0])` — Rotates the `Ellipse` object by a given angle in radian units. You can also provide an optional matrix that identifies the center of rotation. ### Arc An `Arc` is a partial ellipse — a pie slice, open arc, or chord shape. It extends `Ellipse` by adding `start` and `end` angle attributes and a `mode` that controls how the arc is rendered. Below is the constructor for the `Arc` class that shows its default values: ```coffeescript Arc( {pos:[0,0], size:[10,10], color:default_color, start: 0, end: 0, mode: "chord", image: "", opacity: 1, visible: true, motion_map: false, angle: 0, axis: [0,0], border_color: default_color, border_size: 0, border_style: "none", label: {text: "", color: default_color} } ) ``` * `pos` — The initial position of your `Arc` in `[X,Y]` coordinates. * `size` — The width and height as an `[X,Y]` matrix. * `color` — The arc will be drawn in this color. * `start` — The start angle of the arc in radians. * `end` — The end angle of the arc in radians. * `mode` — Controls how the arc is rendered. Options are `"chord"` (straight line connecting end points), `"pie"` (lines from the center), or `"open"` (just the arc edge with no fill lines). * `image` — A URL that identifies a JPEG, GIF, SVG or PNG image. * `opacity` — The arc will be drawn with an opacity between 1 and 0. * `visible` — The arc can be hidden from view by setting this flag to `false`. * `motion_map` — This flag tells Tychos to attach a motion map. * `angle` — Initial rotation angle in radians. * `axis` — The axis of rotation as an `[X, Y]` matrix. * `border_color` — HTML color for the arc border. * `border_size` — Width of the border in pixels. * `border_style` — CSS border style, e.g. `"solid"`, `"dashed"`. * `label` — You can attach a label by indicating the `text` and `color`. Example: ```coffeescript # Setup Code # A pie-chart slice from 0 to PI/2 a1 = Arc({pos:[0, 0], size:[20, 20], color:"orange", start:0, end:PI/2, mode:"pie"}) # An open arc from PI to 2*PI (a half-circle outline) a2 = Arc({pos:[30, 0], size:[20, 20], color:"green", start:PI, end:2*PI, mode:"open"}) ``` #### Arc.rotate `Arc.rotate(angle=0, axis=[0, 0])` — Rotates the `Arc` object by a given angle in radian units. ### Arrow The `Arrow` class 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` class that shows its default values: ```coffeescript Arrow( { pos:[0,0], size:[1,0], color:default_color, components: false, stroke: 1, opacity: 1, visible: true, motion_map: false } ) ``` * `pos` — coordinates for the starting point of the `Arrow` as an `[X,Y]` matrix. * `size` — the vector to illustrate, e.g. `[10, 0]` will draw an `Arrow` 10 units to the right. * `color` — HTML color value for your `Arrow`, e.g. "red" or "#ff0000". * `components` — A flag that determines if X and Y components are drawn, a value of `true` displays the components. * `stroke` — Stroke value that determines the visual thickness of the `Arrow`. * `opacity` — The `Arrow` will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent. * `visible` — The `Arrow` can be hidden from view by setting this flag to `false`. * `motion_map` — This flag tells Tychos to attach a series of strobe images called a motion map. ![Arrow without components](https://tychos.org/static/help/drawArrow_2.png) ![Arrow with components](https://tychos.org/static/help/drawArrow_1.png) Example — The illustrations above were drawn using these commands: ```coffeescript # Setup Code c = Circle({pos:[0,0], color:"green"}) a = Arrow({pos: c.pos, size: [20, 20], color:"purple"}) a.components = true ``` ### 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: ```coffeescript Line( { pos:[0,0], pos2:[1,0], color:default_color, stroke: 1, opacity: 1, visible: true, motion_map: false } ) ``` * `pos` — coordinates for the starting point of the `Line` as an `[X,Y]` matrix. * `pos2` — coordinates of the termination point of the `Line` as an `[X,Y]` matrix * `color` — HTML color value for your `Line`, e.g. "red" or "#ff0000". * `stroke` — Stroke value that determines the visual thickness of the `Line`. This is measured in pixels. * `opacity` — The `Line` will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent. * `visible` — The `Line` can be hidden from view by setting this flag to `false`. * `motion_map` — This flag tells Tychos to attach a series of strobe images called a motion map. ![](/files/-LR32TDaeXVYokKRK4u5) Example: ```coffeescript myLine = Line({pos:[0, 0], pos2: [20, 20], color: "purple", stroke:2}) anotherLine = Line({pos:[0, 0], pos2: [10, 20], color: "green", stroke:10}) ``` ### PolyLine The `PolyLine` class displays a sequence of straight lines between points, and is commonly used to illustrate a more complex shape or path.
Below is the constructor for the `PolyLine` class that shows its default values: ```coffeescript PolyLine( { pos:[0,0], color:default_color, stroke: 1, style: "none", fill: null, opacity: 1, visible: true, style: "none", motion_map: false, retain: 100 } ) ``` * `pos` — coordinates for the starting point of the `Line` as an `[X,Y]` matrix. * `color` — HTML color value for your `Line`, e.g. "red" or "#ff0000". * `stroke` — Stroke value that determines the visual thickness of the `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 the `PolyLine` object as a filled in solid with a color, or an optional argument for rendering the inside area with either a `LinearGradient` or `RadialGradient` object. * `opacity` — The `PolyLine` will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent. * `visible` — The `PolyLine` can be hidden from view by setting this flag to `false` * `motion_map` — This flag tells Tychos to attach a series of strobe images called a motion map. * `retain` — The maximum number of points that can be contained. If another point is added, the last point in the `PolyLine` is removed. `PolyLine` objects have a number of methods for manipulating the points, like adding new points, changing existing points, removing points, etc: * `setPoints: (points)` -> Set the points for the `PolyLine` given an array of points. * `translate: (deltaPosition)` -> Move all the points according to a vector displacement. * `rotate: (angle, axis)` -> Transform the points a certain angle measurement about an axis. This axis is relative to the first point in the `PolyLine`. * `npoints():` -> Returns the number of points in the `PolyLine`. * `append: (...points)` -> Add a point (or many points) to the end of the `PolyLine`. * `unshift: (...points)` -> Add a point (or many points) at the beginning of the `PolyLine`. * `shift: ()` -> Remove the first point in the `PolyLine` object. * `splice: (point, position)` -> Insert a point at the specific index position. * `slice: (start, end)` -> Returns the set of points (but does not remove them) from the `PolyLine` object beginning at the `start` value and ending at the `end` index position. * `last: ()` -> Gets the last point * `first: ()` -> Gets the first point * `replace: (point, n)` -> Modify the nth point. * `drop: (n)` -> Creates slice of points with n points dropped from beginning. * `dropRight: (n)` -> Creates a slice of array with n elements dropped from the end. * `remove: (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 the `PolyLine`. Example: ```coffeescript star1 = PolyLine({stroke: 3, style:"dash", opacity: .2, color: "blue"}) star1.setPoints([[0,75-200], [379-350,161-200],[469-350,161-200],[397-350,215-200], [423-350,301-200], [350-350,250-200], [277-350,301-200], [303-350,215-200], [231-350,161-200], [321-350,161-200], [0,75-200]]) star2 = PolyLine({stroke: 2, style:"none", color: "green"}) star2.setPoints([[0,75-200], [379-350,161-200],[469-350,161-200],[397-350,215-200], [423-350,301-200], [350-350,250-200], [277-350,301-200], [303-350,215-200], [231-350,161-200], [321-350,161-200], [0,75-200]]) star2.translate([100, 100]) star3 = PolyLine({stroke: 3, style:"dot", color: "red"}) star3.setPoints([[0,75-200], [379-350,161-200],[469-350,161-200],[397-350,215-200], [423-350,301-200], [350-350,250-200], [277-350,301-200], [303-350,215-200], [231-350,161-200], [321-350,161-200], [0,75-200]]) star3.translate([-100, 100]) ``` ### 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 **Loop Code** pane. Below is the constructor for the `Spring` class that shows its default values: ```coffeescript Spring( { pos:[0,0], pos2:[1,0], color:default_color, coils: 5, width: 10, stroke: 1, opacity: 1, visible: true, motion_map: false } ) ``` * `pos` — coordinates for the starting point of the `Spring` as an `[X,Y]` matrix. * `pos2` — coordinates of the termination point of the `Spring` as an `[X,Y]` matrix * `color` — HTML color value for your `Spring`, 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 the `Spring`. This is measured in pixels. * `opacity` — The `Spring` will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent. * `visible` — The `Spring` can be hidden from view by setting this flag to `false`. * `motion_map` — This flag tells Tychos to attach a series of strobe images called a motion map. ![Three different Spring objects](/files/-LR2SQrF1kfAATmvdVEs) 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. ```coffeescript # Setup Code c1 = Circle({pos:[0, 0], radius:2, color:"green"}) spring1 = Spring({pos:[0, 20], pos2:c1.pos, color:"black", coils:20, width:2}) c2 = Circle({pos:[10, 0], radius:2, color:"green"}) spring2 = Spring({pos:[10, 20], pos2:c2.pos, color:"black", coils:10, width:4}) c3 = Circle({pos:[20, 0], radius:2, color:"green"}) spring3 = Spring({pos:[20, 20], pos2:c3.pos, color:"black", coils:20, width:2}) ``` These attributes may also be modified after the `Spring` is created. ### Label You can add text labels to any scenario using the `Label` class. ```coffeescript dog = Label({pos:[0,0], size:[20,20], text:"dog", color:"green"}) cat = Label({pos:[0,-15], size:[10,10], text:"cat", color:"red"}) mouse = Label({pos:[0,15], size:[10,10], text:"mouse", color:"blue"}) dog.font="Impact" cat.font="Times" mouse.font="monospace" dog.style = {textShadow:"3px 3px 3px black"} cat.style = {fontStyle:"oblique"} mouse.style = {textDecoration:"underline"} ```
Below is the constructor for the `Label` class that shows its default values: ```coffeescript Label( { pos:[0,0], size:[10,10], text: "", color:default_color, font: "default", style: {}, opacity: 1, visible: true, motion_map: false } ) ``` * `pos` — coordinates for the center point of the `Label` as an `[X,Y]` matrix. * `size` — The width and height of the `Label` as an `[X,Y]` matrix * `text` — The text of the `Label` as a string. * `color` — HTML color value for your `Label`, e.g. "red" or "#ff0000". * `font` — CSS font family identifier, e.g. "Times", or "Courier" * `style` — An object with key-value pairs that represent CSS font styling rules. * `opacity` — The `Label` will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent. * `visible` — The `Label` can be hidden from view by setting this flag to `false`. * `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.rotate Just as with a `Rectangle` object or a `Circle` object, you can rotate a `Label` as shown above: ``` label3.rotate(PI/4) ``` ### Compound Compound objects allow you to group any of the above graphical objects together so that they can all be animated as a single object. Compound objects can even be added to other compound objects to make some complex object compositions.

These are made up of several objects that are grouped in compounds that can then be moved together.

Below is the constructor for the `Compound` class that shows its default values: ```coffeescript Compound( { pos:[0,0], style: {}, opacity: 1, visible: true } ) ``` * `pos` — coordinates for the center point of the `Compound` as an `[X,Y]` matrix. * `opacity` — The `Compound` will be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent. * `visible` — The `Compound` can be hidden from view by setting this flag to `false`. These attributes may also be modified after the `Compound` object is created. #### Compound.add(...objects) To add an object to a compound, you simply call the add method with the object variable that you want to add. You can add as many objects as you want in one call. ```javascript # Make some graphic objects. c1 = Circle({pos:[-5, 0], radius:1, color:"orange"}) c2 = Circle({pos:[5, 0], radius:1, color:"orange"}) r1 = Rectangle({pos:[0,0], size:[11, 1], color:"orange"}) # Add them to a compound cmp1 = Compound({pos:[0,0]}) cmp1.add(c1, c2, r1) ``` #### Compound.remove() `compound` 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. #### Compound.rotate(angle=0) You can rotate a Compound as shown below: ```python cmp1.rotate(pi/4) ``` ### Sprite A `Sprite` is used to display animated sprite-sheet images. It renders a portion of a sprite sheet image and can cycle through frames to create animations. Below is the constructor for the `Sprite` class that shows its default values: ```coffeescript Sprite( {pos:[0,0], image: "", size:[10,10], width: 32, height: 32, n_rows: 1, n_cols: 1, scale: 1, border_width: 0, spacing_width: 0, current_animation_name: "idle", animations: { idle: {frame_indices:[0], time_per_frame:250, on_end:"repeat"} }, angle: 0, axis: [0,0], opacity: 1, visible: true, motion_map: false } ) ``` * `pos` — The initial position of your `Sprite` in `[X,Y]` coordinates. * `image` — A URL pointing to the sprite sheet image (PNG, GIF, etc.). * `size` — The display size of the sprite in world units as an `[X,Y]` matrix. * `width` — The pixel width of a single frame in the sprite sheet. * `height` — The pixel height of a single frame in the sprite sheet. * `n_rows` — Number of rows of frames in the sprite sheet. * `n_cols` — Number of columns of frames in the sprite sheet. * `scale` — A scale multiplier applied to the displayed sprite. * `border_width` — Pixel width of any border between frames in the sprite sheet. * `spacing_width` — Pixel spacing between frames in the sprite sheet. * `current_animation_name` — The name of the currently playing animation (must match a key in `animations`). * `animations` — An object where each key is an animation name. Each animation has: * `frame_indices` — Array of zero-based frame indices to play in sequence. * `time_per_frame` — Milliseconds to display each frame. * `on_end` — What to do when the animation ends: `"repeat"` to loop, `"ping-pong"` to reverse, or `"stop"` to halt on the last frame. * `angle` — Initial rotation angle in radians. * `axis` — The axis of rotation as an `[X, Y]` matrix. * `opacity` — Opacity between 1 and 0. * `visible` — Set to `false` to hide the sprite. * `motion_map` — Attach a motion map. Example: ```coffeescript # Setup Code player = Sprite({ pos:[0, 0], image:"https://example.com/spritesheet.png", size:[10, 10], width:48, height:48, n_rows:1, n_cols:4, animations:{ idle: {frame_indices:[0], time_per_frame:500, on_end:"repeat"}, walk: {frame_indices:[1,2,3], time_per_frame:150, on_end:"repeat"} }, current_animation_name:"walk" }) ``` ```coffeescript # Loop Code player.pos = player.pos + [0.5, 0] ``` #### Sprite.rotate `Sprite.rotate(angle=0, axis=[0, 0])` — Rotates the `Sprite` object by a given angle in radian units. ### RadialGradient A `RadialGradient` creates a radial (circular) gradient that can be used as the `fill` attribute of any graphical object. The gradient blends between colors at specified percentage offsets radiating outward from a focal point. Below is the constructor for the `RadialGradient` class that shows its default values: ```coffeescript RadialGradient( {start_x: 50, start_y: 50, end_x: 50, end_y: 50, colors: [], offsets: [] } ) ``` * `start_x` — Horizontal position (0–100) of the inner circle center. * `start_y` — Vertical position (0–100) of the inner circle center. * `end_x` — Horizontal position (0–100) of the outer circle center. * `end_y` — Vertical position (0–100) of the outer circle center. * `colors` — An array of HTML color strings, e.g. `["red", "blue"]`. * `offsets` — An array of numbers (0–100) representing where each color stop is placed along the gradient. To use a gradient, assign it to the `fill` attribute of any graphical object: ```coffeescript # Setup Code rg = RadialGradient({ start_x:50, start_y:50, end_x:50, end_y:50, colors:["yellow", "orange", "red"], offsets:[0, 50, 100] }) c = Circle({pos:[0,0], radius:20, fill:rg}) ``` ### LinearGradient A `LinearGradient` creates a linear gradient that can be used as the `fill` attribute of any graphical object. The gradient blends between colors along a direction defined by an angle. Below is the constructor for the `LinearGradient` class that shows its default values: ```coffeescript LinearGradient( {angle: PI/2, colors: [], offsets: [] } ) ``` * `angle` — The direction of the gradient in radians. `0` goes left to right; `PI/2` goes top to bottom. * `colors` — An array of HTML color strings, e.g. `["white", "black"]`. * `offsets` — An array of numbers (0–100) representing where each color stop is placed. To use a linear gradient, assign it to the `fill` attribute of any graphical object: ```coffeescript # Setup Code lg = LinearGradient({ angle: 0, colors:["blue", "cyan", "white"], offsets:[0, 50, 100] }) r = Rectangle({pos:[0,0], size:[30, 20], fill:lg}) ``` ## 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: ```javascript world.set_extents(pos=[0,0], size=[10,10]) ``` The inputs are two vector objects representing the center position of the view of the world, and secondly the size of the viewable world. ## 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 Loop Code editor. Each `Graph` that is created will appear on the right side of the World View. Your program needs to add points to the graph with the `plot`command. ```coffeescript g1 = Graph({title:"Line Graph", align:"left", width:"50%", height:200}) g1.plot(x=[0,1,2,3], y=[0, 10, 10, 0], color="purple", mode="line", fill=true) g1.plot(x=[0,1,2,3], y=[0, 2, 4, 9], color="green", mode="line", fill=false) ```

A line graph with two plots

```coffeescript # Create a graph with a scatter plot. g2 = Graph({title:"Scatter Graph", align:"right", width:"50%", height:400}) # x_vals and y_vals are lists of numerical points. g2.plot(x=x_vals, y=y_vals, color="orange", mode="scatter") ```

A graph with a scatter plot.

Here is the constructor for creating a `graph` object ```coffeescript Graph( { title:"Graph", align:"right", y_axis:"Y", x_axis:"X", width:500, height:350, plot_rate:undefined } ) ``` * `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: ```coffeescript Graph.plot( x=0, y=0, color=default_color, mode="line", fill=false ) ``` * `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: ```coffeescript Graph.clear() ``` ### BarChart A `BarChart` is a chart of data that is displayed as a set of bars representing an array of data values. Each `BarChart` that is created will appear on the right side of the World View. {% code lineNumbers="true" %} ```coffeescript # Setup Code bc_energy = BarChart({title:"Energy Bar Chart", min:0, max:500}) bc_energy.setData([150, 250, 200, 500]) bc_energy.setColors(["red", "blue", "green", "black"]) bc_energy.setLabels(["KE", "Ue", "Ug", "TE"]) ``` {% endcode %}

A BarChart with four bars

* `title` = Optional text that will appear at the top of the `bar_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%". **BarChart.setData()** `BarChart.setData` — Sets the data values for the bars in the bar chart. ```coffeescript # Set the data for the bars bc_energy.setData([x,y,z,w]) # Where x, y, z, and w are numerical data values ``` **BarChart.setLabels** `BarChart.setLabels` — 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. ```coffeescript # Set the labels for the bars bc_energy.setLabels(["KE", "Ue", "Ug", "TE"]) ``` **BarChart.setColors** `BarChart.setColors` — 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`. ```coffeescript # Set the colors for the bars bc_energy.setColors(["red", "blue", "green", "black"]) ``` ### PieChart A `PieChart` 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 `PieChart` that is created will appear on the right side of the World View by default, but can be aligned to the left. ```coffeescript # Setup Code pc = PieChart({title:"Pie Chart", width:300, height:200}) pc.setData([10,20,30]) pc.setLabels(["yes", "no", "maybe"]) pc.setColors(["lightgreen", "red", "gold"]) ```

A PieChart with four data values.

The constructor options for adding a `PieChart` to your scenario are the following: * `title` = Optional text that will appear at the top of the `PieChart.` * `align` = Optional value of "`left`" or "`right`" to align the `PieChart` 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%". **PieChart.setData** `PieChart.setData` — Sets the data values for the pie slices in the pie chart. ```coffeescript # Set the data for the bars pc.setData([x,y,z]) # Where x, y, z, are numerical data values ``` **PieChart.setLabels** `PieChart.setLabels` — 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. ```coffeescript # Set the labels for the pie chart slices pc.setLabels(["yes", "no", "maybe"]) ``` **PieChart.setColors** `PieChart.setColors` — 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. ```coffeescript # Set the colors for the data values pc.setColors(["lightgreen", "red", "gold"]) ``` ### Table A `Table` displays data organized in columns and rows. Each `Table` that is created will appear on the right side (default) 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: ```coffeescript Table( { title:"Table", align:"right", columns:[], precision:4 } ) ``` * `title` = Optional text that will appear at the top of the `Table` 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.addRow(\[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.

Table of data

Example: ```coffeescript # Setup Code table1 = Table({title:"example"}) table1.columns = ["Time", "X Pos", "Y Pos"] table1.precision = 6 ``` ```coffeescript # Loop Code table1.addRow([t, c.pos.x, c.pos.y]) ``` ### Meter A `Meter` is a numeric display of data that you specify in the Loop Code editor. 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. ![](/files/-MJxWiXWbOGE-MzAgPUd) Below is the constructor for the `Meter` widget and default values: ```coffeescript Meter( { title:"Meter", color:default_color } ) ``` * `title` = Optional text that will appear at the top of the `Gauge` widget. * `color` — HTML color value for your `Gauge`, e.g. "red" or "#ff0000". #### **Meter.display** `meter.display(value, units)` — Displays the value on the Meter. * `value` = Numeric value to be displayed. * `units` = Optional string representing the unit label to be displayed. Example: {% code lineNumbers="true" %} ```coffeescript # Setup Code mt = Meter({title:"Time", color:"red"}) ``` {% endcode %} {% code lineNumbers="true" %} ```coffeescript # Loop Code mt.display(t, "s") ``` {% endcode %} ### 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. ![Three different gauges](/files/-MJxPa5QJ3BAJEdDpWxs) Below is the constructor for the `Gauge` widget and default values: ```coffeescript Gauge( { title:"Gauge", min:0, max:100, color:default_color } ) ``` * `title` = Optional text that will appear at the top of the `Gauge` widget. * `min` = The minimum value of the `Gauge` * `max` = The maximum value of the `Gauge` * `color` — HTML color value for your `Gauge`, e.g. "red" or "#ff0000". #### **Gauge.display** `gauge.display(value)` — Displays the value in the Gauge. Example: {% code lineNumbers="true" %} ```coffeescript # Setup Code g1 = Gauge({title:"Value 1", min:0, max:200, color:"orange"}) g2 = Gauge({title:"Value 2", min:-100, max:100, color:"purple"}) g3 = Gauge({title:"Value 3", min:0, max:100, color:"blue"}) ``` {% endcode %} {% code lineNumbers="true" %} ```coffeescript # Loop Code val = 44 g1.display(val) g2.display(val) g3.display(val) ``` {% endcode %} ### Button A `Button` is a clickable widget that you can add to your scenarios that allows you to respond to the mouse in several ways.

Three different buttons.

To create a button, you can supply all the following properties defined below: ```coffeescript Button( { title: "Button", align: "left", color: "red", label_text: "", label_color: "black", label_font: "default", style: "normal", on_click: undefined, on_mouse_over: undefined, on_mouse_out: undefined, on_mouse_down: undefined, on_mouse_up: undefined } ) ``` * `title` - Optional text that will appear at the top of the button widget. * `align` = Optional value of "left" or "right" to align the button to the corresponding side of the view window. * `color` — HTML color value for your button, e.g. "red" or "#ff0000". * `label_text` - Text that you want to appear on the button itself. * `label_color` - HTML color value for your label text, e.g. "red" or "#ff0000". * `label_font` - A font family name for the label text, like "Courier" or "Times New Roman". * `style` - This can be one of three options, "arcade", "normal", or "alert", but can also be a CSS style object, i.e. {text-decoration: "underline"} * `on_click` — The name of a function that will be called whenever the button is clicked. * `on_mouse_over` — The name of a function that will be called whenever the moves over the button. * `on_mouse_out` — The name of a function that will be called whenever the mouse moves away from the button. * `on_mouse_down` — The name of a function that will be called whenever the mouse button is pressed while on the button. * `on_mouse_up` — The name of a function that will be called whenever the button is release while on the button. Example {% tabs %} {% tab title="Tychos" %} ```javascript b1 = Button({title:"Arcade", style:"arcade", color:"green", label_text:"YES"}) b1.label_font = "Impact" b1.label_color = "white" b2 = Button({title:"Normal", style:"normal", label_text:"Hello!"}) b2.style = {"text-decoration":"underline"} b2.color = "lightblue" b3 = Button({title:"Alert", style:"alert", label_text:"Danger!"}) b3.label_font = "Courier" ``` {% endtab %} {% endtabs %} ### Toggle A `Toggle` is an interactive widget that allows you associate a boolean value (true or false) with the state of the `Toggle` widget. ![A Toggle that is "false"](/files/-MJxMJXj3pP6HVQ2LwoE) ![A Toggle that is "true"](/files/-MJxN8eOZiXofjhvwpLV) Below is the constructor for the `Toggle` widget and default values: ```coffeescript Toggle( { title:"Toggle" } ) ``` * `title` = Optional text that will appear at the top of the `Toggle` widget. #### **Toggle.value** `x = toggle.value` — Returns the current value of the Toggle. This is read/write. Example: {% code lineNumbers="true" %} ```coffeescript # Setup Code t1 = Toggle({title:"Activate"}) ``` {% endcode %} {% code lineNumbers="true" %} ```coffeescript # Loop Code isActive = t1.value ``` {% endcode %} ### Slider A `Slider` is an interactive widget that allows you to link a value in your scenario to the current value of a horizontal slider. ![A Slider widget with a value of 0.](/files/-MJxKRckXSYUapXnRLtt) Below is the constructor for the `Slider` widget and default values: ```coffeescript Slider( { title:"Input", min:0, max:100, step:1 } ) ``` * `title` = Optional text that will appear at the top of the `Slider` widget. * `min` = The minimum value of the `Slider` * `max` = The maximum value of the `Slider` * `step` = The step increment of the `Slider` #### **Slider.value** `x = slider.value` — Returns the current value of the Slider. This is read/write. Example: {% code lineNumbers="true" %} ```coffeescript # Setup Code s1 = Slider({title:"I'm A Slider", min:0, max:100, step:2}) ``` {% endcode %} {% code lineNumbers="true" %} ```coffeescript # Loop Code x = s1.value ``` {% endcode %} ### Input An `Input` is an interactive widget that allows you to link a value in your scenario to the current value of a text box. The input values are limited to numerical inputs. ![An Input widget](/files/-MJwREDbAKH76quUSBfm) Below is the constructor for the `Input` widget: ```coffeescript Input( { title:"Input" } ) ``` * `title` — The text title of the `Input` * `min` = The minimum value that the user can enter in the `Input` * `max` = The maximum value that the user can enter in the `Input` * `step` = The step increment of the `Input` #### **Input.value** `x = input.value` — Returns the current value of the `Input`. Example: {% code lineNumbers="true" %} ```coffeescript # Setup Code in = Input({title:"Size", max:10, min:-10, step:.1}) ``` {% endcode %} {% code lineNumbers="true" %} ```coffeescript # Loop Code x = in.value ``` {% endcode %} ### Menu A `Menu` is an interactive widget that allows you to link a value in your scenario to the current value selected from a drop-down menu. ![A Menu widget](/files/-MJwUIXVbHC6fAt26-Jm) Below is the constructor for the `Menu` widget: ```coffeescript Menu( { title:"Menu", choices:[], values:[] } ) ``` * `title` — The text title of the `Input` * `choices` — An array of menu choices. * `values` — An optional array of corresponding menu values for each choice. If no values are given, the values are assumed to be the choices. #### **Menu.value** `x = menu.value` — Returns the current value of the `Menu`. Example: {% code lineNumbers="true" %} ```coffeescript # Setup Code menu = Menu({title:"Pick One", choices:["A","B","C"], values:[1,2,3]}) ``` {% endcode %} {% code lineNumbers="true" %} ```coffeescript # Loop Code x = menu.value ``` {% endcode %} ### ControlPanel A `ControlPanel` widget allows you to group other widgets together which better organizes your widgets. Once you create a `ControlPanel`, you simply add other UI widgets to it. You can can set the layput of the control\_panel to be either "row" or "column:

A ControlPanel with a layout that is set to "row".

Below is the constructor for the `ControlPanel` widget: ```coffeescript ControlPanel( { title:"Control Panel", align:"left", layout:"row" } ) ``` * `title` — The text title of the `ControlPanel` * `align` = Optional value of "`left`" or "`right`" to align the control panel to the corresponding side of the view window. * `layout` — Either "row" to arrange the contained widgets horizontally, or "column" to arrange them vertically. #### **ControlPanel.add(...widgets)** To add widgets to a control panel, you simply supply the widgets' variable names to the add function, like this: {% code lineNumbers="true" %} ```coffeescript # Define the Sliders s_width = Slider({title:"Width", min:1, max:100, step:1}) s_height = Slider({title:"Height", min:1, max:100, step:1}) s_shade = Slider({title:"Shade", min:0, max:255, step:1}) s_opacity = Slider({title:"Opacity", min:0, max:1, step:.01, value:1}) cp = ControlPanel({title:"Change the Rectangle", layout:"column", align:"left"}) cp.add(s_width, s_height, s_shade, s_opacity) ``` {% endcode %} The above would create a control\_panel that looks like this:

Control panel with four sliders added to it.

## Interactivity The following section describes additional interactivity that you can add through the use of `keyboard` and `mouse` objects. ### keyboard The `keyboard` object represents your computers keyboard and has commands to see if any keys are pressed during a simulation. #### **keyboard.is\_down** `keyboard.is_down(key)` -> `boolean` — Return 1/0 whether `key` is currently down #### **keyboard.last\_pressed** `keyboard.last_pressed(key)` -> `boolean` — was `key` typed? i.e. key was pushed down then released. ### mouse The `mouse` object represents your computer**'**s mouse. #### **mouse.pos** `mouse.pos` -> `vec` — Returns two dimensional vector as a \[X, Y] matrix representing the position of the mouse in the simulation space. #### **mouse.is\_down** `mouse.is_down(button_num=0)` -> `boolean` — Returns whether the mouse button is pressed. `button_num` — Which button to check? 0 = primary button, 1 = secondary, etc. #### **mouse.is\_over** `mouse.is_over(object)` -> `boolean` — Returns whether the mouse is positioned over an object that is either a `Circle` or a `Rectangle`. `object` — A simulation object. ## Audio The `audio` object can be used to add sound to your scenarios. This can be done by creating an `oscillator` that plays a continuous frequency using a specified wave type, or by creating a `sound` object that plays an audio file given a URL, or finally by just playing a specified tone for a specified amount of time. ### audio.sound To create a sound object, you need to specify a URL for the location of the .wav, .ogg, or .mp3 file ```coffeescript my_sound = audio.sound({url:"https://www.example.com/my_cool_sound.wav"}) ``` The sound object has these methods and attributes: * `sound.play()` - Plays the sound file. * `sound.stop()` - If the sound file is currently playing, it stops the sound file. * `sound.volume` - A numeric value that determines the volume that the sound file will play at. Value must be larger than 0 to hear the sound. * `sound.playback_rate` - A numeric value that determines the playback speed of the file. If a negative value is given, the file plays backwards. ### audio.oscillator An oscillator object is created using this constructor method: ```coffeescript my_oscillator = audio.oscillator({freq:400, volume:1, type:"sine"}) ``` The oscillator object has these methods and attributes: * `oscillator.start()` - Starts the oscillation. * `oscillator.stop()` - Stops generating the oscillation. * `oscillator.freq` - A numeric value that determines the frequency of the sound wave that the oscillator will generate. * `oscillator.volume` - A numeric value that determines the volume of the sound wave that the oscillator will generate. Value must be larger than 0 to hear the sound. * `oscillator.type` - A string value of "sine", "square", "sawtooth", or "triangle" that detemines the type of oscillation. Finally, you can also call a method directly on the `audio` object for generating a tone for a specified amount of time: #### audio.play\_tone `audio.play_tone(freq, volume, time)` — Produces an audio tone for the specified time at the specified frequency (`freq`) and volume. ## CSV Files Comma separated files can be loaded into the current session of Tychos, and then the data can be read into your scenarios. You need to upload the file through the interface, found in the Settings Tab of the Hack Panel: ![](/files/2kEE9wnnA8YfYA4qLF0M) Once this has been done, you can access the data in the file using the `csvFiles` array. ### csvFiles This array is a list of data objects representing the data contained in each file. {% hint style="info" %} Note, this array is actually not 0 indexed. The first file is actually identified at index of 1. {% endhint %} You access each file as you would any array in Tychos: ```coffeescript file = csvFiles[1] ``` ### CSV file For example, let's say your CSV file has the name `"my_data.csv"` and looks like this: {% code lineNumbers="true" %} ```csv Time, X, Y 0, 10, -10 1, 11, -9 2, 12, -8 ``` {% endcode %} The file object has two read-only attributes, one representing the name of the file, and the other representing the data in the file: {% code lineNumbers="true" %} ```coffeescript name = file.name # Returns string "my_data.csv" data = file.data # Returns list of dictionary objects ``` {% endcode %} The data attribute is itself a list, representing the rows of the data in the file. Each row is a dictionary whose keys correspond to the column headers in the CSV file: ```coffeescript data[1] # Returns {"Time":"0", "X":"10", "Y":"-10"} ``` Then to access the *X* value in the file located at row 1 of the data then you would type: ```coffeescript x = data[1].X # Returns "10" y = x + 1 # Returns 11.0 ``` {% hint style="info" %} It is important to note that the values stored in the data objects are all string values. As long as the values can be easily parsed to numerical values, Tychos will do the parsing automatically if the value is used in a mathematical calculation. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tychos.org/docs/learn/language-reference-api-1.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.