chemistrylab.vessel module

class chemistrylab.vessel.Event(name, parameter, other_vessel)

Bases: NamedTuple

name: str

The registered name of the event function.

other_vessel: object | None

The other vessel needed for this event if requred (ex the target vessel when pouring).

parameter: tuple

The parameters of the registered event function

class chemistrylab.vessel.Vessel(label: str, temperature: float = 297.0, volume: float = 1.0, ignore_layout: bool = False)

Bases: object

The Vessel class serves as any container you might find in a lab, a beaker, a dripper, etc. It simulates actions performed within a lab, such as draining contents, performing reactions, mixing, pouring, etc.

The most important method is push_event_to_queue() . The rest of the functions are either handeled in the backend or getter methods.

These are the default Event functions:

Event Name	Event Description	Event Parameters
pour by volume	Pour from self vessel to target vessel by certain volume	volume (float)
pour by percent	Pour a fraction of all contents in one vessel into another	fraction (float)
drain by pixel	Drain from self vessel to target vessel by certain pixel	n_pixel (int)
mix	Shake the vessel or let it settle	t (float)
update_layer	Update self vessel’s layer representation
change heat	Add or remove heat from the vessel	dQ (float)
heat contact	Connect the vessel to a reservoir for heat transfer	Tf (float), ht (float)

filled_volume()

Returns:

The volume of all non-gas phase materials in the vessel (in Litres).

Return type:

float

get_layer_dataframe()

Returns:

A DataFrame containing the layer information of the vessel.

Return type:

DataFrame

get_layers()

Returns:

The color of each vessel layer.

Return type:

List[float]

get_material_dataframe()

Returns:

A DataFrame detailing all materials present in the Vessel.

Return type:

DataFrame

get_solute_dataframe()

Returns:

A [solutes, solvents] DataFrame detailing how much solute is dissolved in each solvent.

Return type:

DataFrame

heat_capacity()

Returns:

The sum of the heat capacities of all materials in the vessel (in J/K)

Return type:

float

push_event_to_queue(events: Tuple[Event] = (), dt: float = 0, update_layers: bool = True) → Tuple[int]

This function calls a set of event functions in sequence specified by events, then returns a tuple of status codes (one for each event).

Parameters:

• events (Tuple[Event]) – The sequence of events to be executed.

• dt (float) – The amount of time elapsed (defaults to 0).

• update_layers (bool) – Whether or not to update layer information at the end of the queue.

Returns:

A sequence of status codes for each event. At the moment, 0 represents normal execution, and -1 represents an illegal state reached (like a vessel overflow or boiling an empty vessel).

Return type:

Tuple[int]

classmethod register(func: Callable, name: str)

The method to register an event function which updates a vessel instance.

Parameters:

• func (Callable[[Vessel, Tuple, Optional[Vessel]], int]) – An event function which acts on one or two vessels.

• name (str) – The name of the event function for registration.

validate_solutes(checksum: bool = True)

Turns the solute dict into a 2D array, gets a 1D array of solute amounts, as well as a 1D array of solvent amounts, then performs consistency checks with _validate_solute_amounts.

validate_solvents()

Updates the solute_dict and solvent_dict / solvent array when the solvents have changed