A 3D surface chart rendered with matplotlib inside a Tychos plot widget.
A 3D surface chart rendered with matplotlib inside a Tychos plot widget.
The goal editor with a hint configured. The "Show when" condition controls when the hint is visible to students.
Autocomplete with signature help and parameter highlighting.
Hover tooltip showing a function signature and description.
Inline error squiggle with tooltip.
The in-app documentation panel open alongside a simulation.
The "jump" animation.
This scenario has three uploaded assets.
New attributes allow for image manipulation.
These two graphic elements are made up of compounds that contain graphic objects.
Control panel with a "row" layout.
Control panel with a "column" layout.
Click the + to create a new collection.
A pie chart widget.
Three different labels
Scatter mode
Adding a comment.
Viewing a comment.
The new Update Clones button on the Goals tab.
Different arcs
Add new collection
Three assets have been uploaded.
color = rgb(100, 100, 0) # returns '#646400'
{% code lineNumbers="true" %}
```python
# Setup Code
p1 = circle(pos=vec(15, 0), radius=10, color=rgb(0, 200, 200), opacity=.6)
b1 = rectangle(pos=vec(0, 0), size=vec(15, 15), color=rgb(200, 0, 200), opacity=.6)
b1.rotate(radians(45))
p3 = circle(pos=vec(-15, 0), radius=10, color=rgb(0, 0, 200), opacity=.6)
```
{% endcode %}
{% code lineNumbers="true" %}
```python
# Loop Code
has_collided(p1, b1) # returns True
has_collided(b1, p3) # returns True
has_collided(p1, p3) # returns False
```
{% endcode %}
#### 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` or `rectangle` or `line` object
* `target` - `circle` or `rectangle` or `line` object
Example:
{% code lineNumbers="true" %}
```python
# Setup Code
p1 = circle(pos=vec(0, 0), radius=10, color=rgb(200, 200, 200), opacity=.6)
p2 = circle(pos=vec(12, 10), radius=10, color=rgb(0, 200, 0), opacity=.6)
b1 = rectangle(pos=vec(-12, 0), size=vec(15, 15), color=rgb(200, 0, 0), opacity=.6)
mtv1 = arrow(pos=p1.pos, color="green")
mtv2 = arrow(pos=p1.pos, color="red")
```
{% endcode %}
{% code lineNumbers="true" %}
```python
# Loop Code
mtv1.size = get_mtv(p1, p2)
mtv2.size = get_mtv(p1, b1)
```
{% endcode %}
#### 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` or `rectangle` or `line` object
* `target` - `circle` or `rectangle` or `line` 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:
{% code lineNumbers="true" %}
```python
# Setup Code
r = rectangle(pos=vec(-4, 0), size=vec(10,15), color="orange", opacity=.5)
r.rotate(.1)
l = line(pos=vec(0,10), pos2=vec(-10, -20))
```
{% endcode %}
{% code lineNumbers="true" %}
```python
# Loop Code
points = get_intersections(r, l)
```
{% endcode %}
#### get\_collisions(source, objects\_list)
This function returns a list of all objects from `objects_list` that are currently overlapping with `source`, along with the minimum translation vector (MTV) needed to separate each pair. Results are sorted by MTV magnitude (smallest overlap first).
* `source` - `circle`, `rectangle`, or `line` object
* `objects_list` - a list of `circle`, `rectangle`, or `line` objects to check against
Each item in the returned list is a tuple `(object, mtv)` where `object` is the colliding object and `mtv` is the vector needed to push `source` out of the overlap.
{% code lineNumbers="true" %}
```python
# Setup Code
all_balls = []
ball_A = circle(pos=vec(0, 0), radius=10, color="orange")
for i in range(5):
all_balls.append(circle(pos=vec(i * 15, 20), radius=10, color="blue"))
```
{% endcode %}
{% code lineNumbers="true" %}
```python
# Loop Code
collisions = get_collisions(ball_A, all_balls)
if collisions:
obj, mtv = collisions[0] # closest collision
ball_A.pos = ball_A.pos + mtv
```
{% endcode %}
### Helper Functions
The following functions are useful for testing conditions in your simulation. They are especially handy in goal expressions but can be used anywhere in your code.
#### exists(name)
Returns `True` if a variable with the given name has been defined in the simulation.
* `name` - a string with the variable name to check
```python
exists('velocity') # True if 'velocity' has been defined
exists('ball') # True if 'ball' object has been created
```
#### close(a, b, tolerance)
Returns `True` if `a` and `b` are within `tolerance` of each other. Works with both numbers and vectors (uses Euclidean distance for vectors).
* `a` - a number or vector
* `b` - a number or vector
* `tolerance` - the maximum allowed difference (default: `1e-9`)
```python
close(speed, 9.8, 0.01) # True if speed is within 0.01 of 9.8
close(ball.pos, target, 5) # True if ball position is within distance 5 of target
```
#### between(value, min, max)
Returns `True` if `min < value < max` (exclusive on both ends).
* `value` - the number to test
* `min` - the lower bound (exclusive)
* `max` - the upper bound (exclusive)
```python
between(angle, -3.14, 3.14) # True if -π < angle < π
between(score, 0, 100) # True if score is between 0 and 100 (not including 0 or 100)
```
#### has\_attr(obj, name)
Returns `True` if `obj` has an attribute with the given name. Useful for checking whether a student added a custom property to an object.
* `obj` - any object
* `name` - a string with the attribute name to check
```python
has_attr(ball, 'velocity') # True if ball has a 'velocity' attribute
has_attr(ball, 'color') # True if ball has a 'color' attribute
```
### 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.
{% code lineNumbers="true" %}
```python
A = True
B = True
A and B # returns true
B = False
A and B # returns false
```
{% endcode %}
You can use the `and` operator to test if two comparisons are both true:
{% code lineNumbers="true" %}
```python
x = 2
(x < 3) and (x == 2) # returns True
(x < 3) and (x != 2) # returns False
```
{% endcode %}
#### **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.
```
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:
```
x = 2
(x < 3) or (x == 3) # one is true, so returns True
(x < 1) or (x == 3) # both are false, so returns False
```
## 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:
* [`circle`](#circle)
* [`rectangle`](#rectangle)
* [`ellipse`](#ellipse)
* [`arc`](#arc)
* [`arrow`](#arrow)
* [`line`](#line)
* [`label`](#label)
* [`spring`](#spring)
* [`poly_line`](#poly_line)
* [`sprite`](#sprite)
There are also two gradient fill objects that can be added to some of the above graphical objects (circle, rectangle, ellipse, arc, poly\_line)
* [`radial_gradient`](#radial_gradient)
* [`linear_gradient`](#linear_gradient)
### Common Attributes
The following attributes are shared by most of the graphical objects listed above. Exceptions are noted below.
#### `pos` - vector
The position of of the graphic object scaled to the world. This is not a pixel position, but rather a position in the World as a vector with `x,y,z` coordinates. Currently the z coordinate value does not affect the position of the object in the World. The `linear_gradient` and `radial_gradient` do not have these attributes
#### `color` - string
Objects will be drawn in this color. Use HTML colors e.g. "#ff3300", "blue", or the [`rgb`](#rgb-r-g-b) function.
#### `opacity` - float
Objects can be drawn with an opacity between 1 and 0, representing 100% opaque to 100% transparent.
#### `image` - string
Certain objects (**circle, rectangle, ellipse, arc**) can also be represented with an image by setting the image attribute of the object. The text can either be a URI link or an [asset reference](/docs/learn/interface-overview#assets) to a graphic file that can be a PNG, SVG, GIF, or JPEG image.
Here is an example of using a URI for displaying a circle as an image:
```python
rocket = circle(pos=vec(0, 0), radius=10)
rocket.image = "https://upload.wikimedia.org/wikipedia/commons/3/3d/Spacecraft.png"
```
{% 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 %}
#### `no_fill` - boolean
If set to `True`, the area inside the object will be transparent.
#### `fill` - object
Optional argument for rendering the filled area with either a `linear_gradient` or `radial_gradient`
#### `visible` - boolean
All objects can be hidden from view by setting this flag to `False`.
#### `motion_map` - boolean
This flag tells Tychos to attach a series of strobe images called a motion map.
### Mouse Interaction
All graphical objects in Tychos (`circle`, `rectangle`, `sprite`, `line`, `label`, etc.) are capable of detecting mouse events. You can make your simulation interactive by defining a Python function and assigning it to one of the object's event handlers.
**Event Attributes**
* `on_click` : *Function*
Triggered when the mouse button is pressed and released on the object.
* `on_dbl_click` : *Function*
Triggered when the mouse button is double-clicked on the object.
* `on_mouse_down` : *Function*
Triggered when the mouse button is pressed down while over the object.
* `on_mouse_up` : *Function*
Triggered when the mouse button is released while over the object.
* `on_mouse_move` : *Function*
Triggered repeatedly when the mouse pointer is moving while over the object.
* `on_mouse_enter` : *Function*
Triggered once when the mouse pointer enters the object's boundary.
* `on_mouse_leave` : *Function*
Triggered once when the mouse pointer leaves the object's boundary.
* `on_mouse_over` : *Function*
Triggered repeatedly while the mouse pointer is over the object (similar to `on_mouse_move`, but can fire even if the mouse is stationary).
* `on_mouse_out` : *Function*
Triggered when the mouse pointer moves off the object (alias for `on_mouse_leave`).
* `on_context_menu` : *Function*
Triggered when the right mouse button is clicked on the object (often used for custom menus).
**How to Use**
1. Define a function that accepts a single argument (commonly named `target` or `obj`). When the event fires, Tychos will call your function and pass the object that was clicked (the source of the event) as this argument.
2. Assign that function (without parentheses) to the object's event attribute.
**Examples**
1\. Click to Change Color
This example shows how the `target` argument allows you to write a generic handler that can be reused for multiple objects.
Python
```python
# 1. Define a generic handler
def change_color(target):
# 'target' is the object that was clicked
target.color = "green"
# 2. Create objects
c1 = circle(pos=vec(0, 0), radius=5, color="red")
c2 = circle(pos=vec(20, 0), radius=5, color="blue")
# 3. Attach the SAME handler to both
c1.on_click = change_color
c2.on_click = change_color
```
2\. Mouse Hover Effects
Use `on_mouse_enter` and `on_mouse_leave` to create highlight effects.
Python
```python
button = rectangle(size=vec(40, 20), color="gray")
def highlight(target):
target.color = "white"
def unhighlight(target):
target.color = "gray"
button.on_mouse_enter = highlight
button.on_mouse_leave = unhighlight
```
3\. Dragging an Object
Python
```python
box = rectangle(pos=vec(0, 0), size=vec(10,10))
box.is_dragging = False
def start_drag(target):
target.is_dragging = True
def stop_drag(target):
target.is_dragging = False
def drag_move(target):
if target.is_dragging:
# Move the target to the mouse position
target.pos = mouse.pos
# Wire up the events
box.on_mouse_down = start_drag
box.on_mouse_up = stop_drag
box.on_mouse_move = drag_move
```
***
### Labels
The circle, rectangle, ellipse and arc objects can display a text label within their bounded areas. The text will scale with the object.
#### `label_text` - string
The text of an attached label.
#### `label_color` - string
The color of the attached label text.
#### `label_font` - string
The font family of the attached label text.
#### `label_style` - dictionary
A dictionary whose key-value pairs match CSS font styling attributes of the attached label text.
### Borders
You can add a border to the circle, rectangle, ellipse, arc, and poly\_line objects:
Borders with different sizes, colors, and styles.
Below is the constructor for the `ellipse` class that shows its default values:
```python
ellipse(
pos=vec(0,0),
size=vec(10,5),
color=default_color,
no_fill=False,
fill=None,
border_size=0,
border_color=default_color,
border_style="none",
image="",
opacity=1,
visible=True,
motion_map=False,
label_text="",
label_color="black",
label_font="",
label_style={},
skew_x = 0,
skew_y = 0,
flip_x = False,
flip_y = False,
blur = 0
)
```
* `size` — The size of the `ellipse` given as a vector with `x,y,z` coordinates.
These attributes may also be modified on the `ellipse` after it is created, just like the `circle`.
### rectangle
A `rectangle` is very similar to a `circle` but it is represented as a colored rectangle in the World View.
```python
# Setup Code
r = rectangle(size=vec(20,10))
r_big_red = rectangle(pos=vec(25, 0), size=vec(25, 25), color="red")
r_green = rectangle(pos=vec(50, 0), color="green", opacity=.5)
r_green.border_size=5
r_green.border_color="blue"
r.label_text="hi"
r.label_color="white"
r.label_font="Courier"
```
Different arc objects.
Below is the constructor for the `poly_line` class that shows its default values:
```python
poly_line(
pos=vec(0,0),
color=default_color,
stroke=1,
style="none",
fill=None,
no_fill=True,
opacity=1,
visible=True,
motion_map=False,
skew_x = 0,
skew_y = 0,
flip_x = False,
flip_y = False,
blur = 0
)
```
* `stroke` — Stroke value that determines the visual thickness of the `poly_line`. This is measured in pixels.
* `style` — Can be `"none"` for solid segments, `"dash"` for dashed line segments or `"dot"` for dotted line segments.
`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 the `poly_line` given a `List` 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 the `poly_line`.
* `npoints():` -> Returns the number of points in the `poly_line`.
* `append: (*points)` -> Add a point (or many points) to the end of the `poly_line`.
* `unshift: (*points)` -> Add a point (or many points) at the beginning of the `poly_line`.
* `shift: ()` -> Remove the first point in the `poly_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 the `poly_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 the `poly_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 the `poly_line` object beginning at the `start` value and ending at the `end` index position.
### 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.
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.
```python
# Setup Code editor
c1 = circle(pos=vec(0, 0), radius=2, color="green")
spring1 = spring(pos=vec(0, 20), pos2=c1.pos, color="black", coils=20, width=2)
c2 = circle(pos=vec(10, 0), radius=2, color="green")
spring2 = spring(pos=vec(10, 20), pos2=c2.pos, color="black", coils=10, width=4)
c3 = circle(pos=vec(20, 0), radius=2, color="green")
spring3 = spring(pos=vec(20, 20), pos2=c3.pos, color="black", coils=20, width=2)
```
Below is the constructor for the `spring` class that shows its default values:
```python
spring(
pos=vec(0,0),
pos2=vec(1,0),
color=default_color,
coils=5,
width=10,
stroke=1,
opacity=1,
visible=True,
motion_map=False,
skew_x = 0,
skew_y = 0,
flip_x = False,
flip_y = False,
blur = 0
)
```
* `pos` — coordinates for the starting point of the `spring` as a 2D vector.
* `pos2` — coordinates of the termination point of the `spring` as 2D vector
* `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.
These attributes may also be modified after the `spring` is created.
### label
You can add text labels to any scenario using the `label` object.
```python
lbl_dog = label(pos=vec(0,0), size=vec(20,20), text="dog", color="green")
lbl_cat = label(pos=vec(0,-15), size=vec(10,10), text="cat", color="red")
lbl_mouse = label(pos=vec(0,15), size=vec(10,10), text="mouse", color="blue")
lbl_dog.font="Impact"
lbl_cat.font="Times"
lbl_mouse.font="monospace"
lbl_dog.style = {"text-shadow":"3px 3px 3px black"}
lbl_cat.style = {"font-style":"oblique"}
lbl_mouse.style = {"text-decoration":"underline"}
```
my_sprite.reset_animation()
The "jump" animation.
These are made up of several objects that are grouped in compounds that can then be moved together.
| Setter/Getter | Description |
|---|---|
set_background_color() | Sets the simulation background color |
get_background_color() | Gets the background color; returns None if using default |
set_grid_visible() | Shows/hides the grid overlay |
get_grid_visible() | Gets grid visibility; returns None if using default |
set_grid_color() | Sets the grid line color |
get_grid_color() | Gets the grid color; returns None if using default |
set_strobe_count() | Sets max number of motion trail images (20-50 typical) |
get_strobe_count() | Gets the strobe count; returns None if using default |
set_tick_rate() | Sets simulation step size (e.g., 0.02 for 50 ticks/sec) |
get_tick_rate() | Gets tick rate in seconds; returns None if using default |
set_graph_strobe_rate() | Sets how often graph data is recorded (in seconds) |
get_graph_strobe_rate() | Gets graph sample rate; returns None if using default |
set_table_strobe_rate() | Sets how often table data is recorded (in seconds) |
get_table_strobe_rate() | Gets table sample rate; returns None if using default |
set_motion_map_rate() | Sets how often motion trails update (in seconds) |
get_motion_map_rate() | Gets motion map rate; returns None if using default |
load(url_key, params=None) | Deprecated — prefer the global load_scenario() function |
reset() | Deprecated — prefer the global reset() function |
params | Read-only dict of values passed from the previous scenario (or URL query params) |
get_device() | Gets connected hardware device by index |
Different gradients on different objects
A line graph with two different colored plots.
A scatter graph
A bar_chart with four bars.
A pie_chart.
A plot widget showing a 3D surface chart created with matplotlib.
Table of data
Three different buttons.
A toggle that is False
A toggle that is True
A slider widget with a value of 0.
An input widget
A menu widget
A text_input widget
A checkbox widget
A checkbox_group widget
A radio_button widget
A text_display widget
A control_panel with a "row" layout.
Conrol panel with four sliders added to it.
A popup widget
# Create a sound from a URL or an asset name
my_sound = audio.sound("https://www.example.com/my_cool_sound.wav")
my_sound2 = audio.sound("cool_sound2.mp3")
# Change the volume
my_sound.volume = 1.5 # 150% volume
my_sound2.volume = .5 # 50% volume
# Change the playback rate
my_sound1.playback_rate = 5.0 # 5 time faster
my_sound2.playback_rate = 0.5 # Half playback rate.
# Play it, or if playing already, don't play it
if not my_sound.is_playing:
my_sound.play()
if my_sound2.is_playing:
my_sound2.stop()
These are made up of several objects that are grouped in compounds that can then be moved together.
A line graph with two plots
A graph with a scatter plot.
A BarChart with four bars
A PieChart with four data values.
Table of data
Three different buttons.
A ControlPanel with a layout that is set to "row".
Control panel with four sliders added to it.
Adding a new class
Viewing a class
Goals showing PASS (✓), NOT YET (?), and FAIL (✗) states. Active hints appear below a failing goal.
An ERROR state (⚠️) appears when the goal code itself throws an error, with the error message shown to instructors.
The goal editor with all fields visible, including a hint with an optional Show When condition.
# Use a variable instead
x = 2
print(x+2)
print(x-2)
print(x*3)
print(x/3)
# This function converts a degree value to a radian value
x = radians(180)
print(x)
# This function computes the sine of an angle in radians
y = sin(.57)
print(y)
Motion map of circle and arrow
Graph of position versus time.
if t > 2:
F1 = vec(0, 0)
print(F1)
| Operator | Example | Evaluates | Description |
|---|---|---|---|
| Operator | Example | Evaluates | Description |
| < | 1 < 2 | True | Less than |
| > | 1 > 2 | False | Greater than |
| <= | 1 <= 2 | True | Less than or equal |
| >= | 1 >= 2 | False | Greater than or equal |
| != | 1 != 2 | True | Not equal |
| == | 1 == 2 | False | Equal |
| equals | equals(vec(0, 0), vec(0, 1)) | False | Equality of vectors |