Classes

Science Jubilee exposes a set of Python classes that wrap the Jubilee hardware, deck layout, and labware model. This section documents those classes in a consistent, task-oriented way: what each class represents, how to construct it safely, and which methods you are most likely to need in real experiments.

If you are building automation scripts or integrating Jubilee into your own tools, this is the main reference you will use.

INFO

Use the sidebar navigation to browse individual class pages, or start with Machine if you are new to the library.

How class pages are structured

Every class page follows the same layout so you can skim quickly:

1. Description What the class represents, the part of the system it belongs to (hardware, labware, geometry, etc.), and when you should use it.

2. Constructor The Python signature (with type hints) plus a parameter table:

   • which arguments are required vs. optional
   • defaults and common values
   • how the argument interacts with the rest of the system (e.g., address vs simulated on Machine).

3. Key Properties Attributes you are expected to read or set directly (for example, configured_axes, deck, or position on Machine). These are listed in a table with type and a short description.

4. Important Methods The main methods you will call in normal usage, with return types and concise behavioral notes (e.g., “absolute vs. relative motion”, “mutates state”, “idempotent”).

5. Short Example A minimal, runnable example that shows the class in context: construction, one or two core operations, and any teardown or cleanup.

6. Important Notes & Related Concepts Implementation details and gotchas (e.g., homing, safe Z movement, caching, simulation) plus links to other classes that typically appear together.

You can use the Machine page as a canonical example of this structure.

Core class groups

Hardware & motion control

These classes talk directly to the Jubilee controller or model its motion state.

• Machine — High-level interface to a Jubilee machine. Manages connection, homing, motion commands, tool pickup/parking, labware loading, and state caching. Supports both real hardware and simulated mode.

Deck & labware model

These classes describe what is on the deck and where it lives.

• Deck — Represents the physical deck configuration (slots, coordinate system, and installed labware). The Machine.deck property refers to the active deck.
• Labware — A loaded piece of labware (e.g., a specific 96-well plate or rack) that knows its geometry and slot.
• Tool — A physical tool the machine can pick up (pipette, gripper, etc.), including offsets and metadata.

Locations, wells, and geometry

These classes let you work with specific positions rather than raw XYZ coordinates.

• Well — Represents a single well in a plate or similar container, including its position and dimensions.
• Location — A coordinate or frame of reference attached to labware, wells, or other features on the deck.

(See the sidebar or navigation for the full list of documented classes.)

Where to start

If you are new to Science Jubilee:

1. Start with Machine. Learn how to connect, home the axes, move safely, and load labware. Most other classes are used through methods on Machine.

2. Then read the deck & labware classes. Understanding how Deck, Labware, Well, and Location fit together makes it easier to reason about coordinates and avoid collisions.

3. Use examples as templates. Each class page includes a short example. Copy one as a starting point and modify it for your own setup or protocol.

TIP

If you are unsure which class to use for a task, start from the example closest to your workflow and follow the links in the Related Concepts section of each class page.

Conventions used in class docs

Across all class pages, we follow a few conventions:

• Type hints match the public API. Signatures are shown exactly as they appear in the library (including defaults like baudrate: int = 115200).

• Keyword-friendly constructors. Constructors are designed to be called with keyword arguments in scripts, and examples use keywords wherever it improves readability.

• Safe-by-default motion. Methods that involve motion call out any requirements (e.g., “requires homing” or “moves via safe Z”) and refer to the decorators that enforce them (@machine_homed, @requires_deck, @requires_safe_z on Machine).

• Simulation support. Where applicable (for example, Machine(simulated=True)), docs note how to use a class without physical hardware for testing and dry-runs.

INFO

If you notice a class page that does not follow this structure, or you are unsure which class to use for a task, please open an issue or reach out to the Science Jubilee maintainers.