fixing code blocks and most build errors, add expected mix behavior and meniscus-relative shoutout

Author: emilyburghardt

api/docs/v2/complex_commands/parameters.rst

@@ -113,7 +113,7 @@ For example, this basic transfer command will mix 50 µL of liquid 3 times befor
 
 Mixing occurs before every aspiration, including when :ref:`tip refilling <complex-tip-refilling>` is required.
 
-Liquid class definitions determine mix behavior in liquid class complex commands like ``transfer_with_liquid_class()``. For more information, see the :ref:`Opentrons-verified liquid class definitions <liquid-class-definitions>`. 
+Liquid class definitions determine mix behavior in liquid class complex commands like ``transfer_with_liquid_class()``. If mixing is enabled before an aspiration, the pipette will mix in place at the aspirate position. You can see position and other values in the  :ref:`Opentrons-verified liquid class definitions <liquid-class-definitions>`. 
 
 .. note::
     :py:meth:`~.InstrumentContext.consolidate` ignores any value of ``mix_before``. Mixing on the second and subsequent aspirations of a consolidate command would defeat its purpose: to aspirate multiple times in a row, from different wells, *before* dispensing.
@@ -285,7 +285,7 @@ For example, this ``transfer()`` command will mix 50 µL of liquid 3 times after
         mix_after=(3, 50),
     )
 
-Liquid class definitions determine mix behavior in liquid class complex commands like ``transfer_with_liquid_class()``. For more information, see the :ref:`Opentrons-verified liquid class definitions <liquid-class-definitions>`. 
+Liquid class definitions determine mix behavior in liquid class complex commands like ``transfer_with_liquid_class()``. If mixing is enabled after a dispense, the pipette will mix in place at the dispense position. You can see position and other values in the  :ref:`Opentrons-verified liquid class definitions <liquid-class-definitions>`. 
 
 .. versionadded:: 2.0
 

api/docs/v2/liquid_class_definitions.rst

@@ -6,7 +6,7 @@
 Liquid Class Definitions
 *************************
 
-A *liquid class definition* specifies nearly all transfer behavior a Flex pipette will perform during a :py:meth:`.InstrumentContext.transfer_with_liquid_class`, :py:meth:`.InstrumentContext.distribute_with_liquid_class`, or :py:meth:`InstrumentContext.consolidate_with_liquid_class`. Properties, like aspirate flow rate, submerge speed, or dispense position, are required in every liquid class definition. 
+A *liquid class definition* specifies nearly all transfer behavior a Flex pipette will perform during a :py:meth:`.InstrumentContext.transfer_with_liquid_class`, :py:meth:`.InstrumentContext.distribute_with_liquid_class`, or :py:meth:`.InstrumentContext.consolidate_with_liquid_class`. Properties, like aspirate flow rate, submerge speed, or dispense position, are required in every liquid class definition. 
 
 This section details specific changes to transfer behavior for each Opentrons-verified liquid class. The transfer steps are listed in the order the robot performs them. Advanced settings like mix, pre-wet tip, touch tip, and blowout are automatically disabled in Opentrons-verified liquid class definitions. 
 

api/docs/v2/liquid_classes.rst

@@ -78,13 +78,15 @@ Each Opentrons-verified liquid class is defined by a set of properties:
     * - .. image:: ../img/lc_icons/flow_rate_aspirate.png
 
         **Aspirate flow rate**
-      - The pipette aspirates liquid at this speed.
-      - Varies by volume.
+      -  
+        - The pipette aspirates liquid at this speed.
+        - Varies by volume.
     * - .. image:: ../img/lc_icons/flow_rate_dispense.png
 
         **Dispense flow rate**
-      - The pipette dispenses liquid at this speed.
-      - Varies by volume. 
+      -  
+        - The pipette dispenses liquid at this speed.
+        - Varies by volume.
     * - .. image:: ../img/lc_icons/retract_position.png
 
         **Retract position**
@@ -96,17 +98,19 @@ Each Opentrons-verified liquid class is defined by a set of properties:
     * - .. image:: ../img/lc_icons/push_out.png
 
         **Push out**
-      - The pipette dispenses a small amount of air to ensure all liquid leaves the tip.
-      - Varies by volume.
+      -
+        - The pipette dispenses a small amount of air to ensure all liquid leaves the tip.
+        - Varies by volume.
     * - .. image:: ../img/lc_icons/touch_tip.png
 
         **Touch tip**
       - The pipette touches the attached tip to the sides of a well to remove droplets.
     * - .. image:: ../img/lc_icons/air_gap.png
 
         **Air gap**
-      - The pipette aspirates a small amount of air after an aspirate or dispense.
-      - Varies by volume. 
+      -  
+        - The pipette aspirates a small amount of air after an aspirate or dispense.
+        - Varies by volume.
     * - .. image:: ../img/lc_icons/blow_out.png
 
         **Blow out**
@@ -131,43 +135,53 @@ Start by definining the tips, trash, pipette, and labware used in your transfers
 
     from opentrons import protocol_api
 
-    requirements = {"robotType": "Flex", "apiLevel": "|2.23|"}
+    requirements = {"robotType": "Flex", "apiLevel": "|2.24|"}
 
     # define tips, trash, and pipette
     def run(protocol: protocol_api.ProtocolContext):
-        tiprack1 = protocol_context.load_labware("opentrons_flex_96_tiprack_50ul", "D3")
-        trash = protocol_context.load_trash_bin("A3")
-        pipette_50 = protocol_context.load_instrument("flex_1channel_50", "left, tip_racks=[tiprack1]")
+            tiprack = protocol.load_labware(
+              load_name="opentrons_flex_96_tiprack_50ul", 
+              location="D3")
+            trash = protocol.load_trash_bin(location="A3")
+            pipette = protocol.load_instrument(
+              instrument_name="flex_1channel_50", 
+              mount="left", 
+              tip_racks=[tiprack])
     
     # load source and destination labware
-        nest_plate = protocol_context.load_labware("nest_96_wellplate_200ul_flat", "C3")
-        arma_plate = protocol_context.load_labware("armadillo_96_wellplate_200ul_pcr_full_skirt","C2")
+            reservoir = protocol.load_labware(
+              load_name="nest_12_reservoir_15ml", 
+              location="C3")
+            plate = protocol.load_labware(
+              load_name="nest_96_wellplate_200ul_flat",
+              location="C2")
 
-    # select liquid classes to use in your protocol
-        liquid_1 = protocol_context.get_liquid_class("glycerol_50")
-        liquid_2 = protocol_context.get_liquid_class("ethanol_80")
-        liquid_3 = protocol_context.get_liquid_class("glycerol_50")
+    # select liquid class to use in your protocol
+            viscous_liquid = protocol.get_liquid_class(name="glycerol_50")
 
+.. versionadded:: 2.24
 
-You'll need to add a label, like ``liquid_1``, to liquid classes in your protocol. This helps you keep track of multiple liquids of the same class in a protocol. It's also required by ``transfer_with_liquid_class()``, instead of a liquid class load name like ``glycerol_50``. 
+Use :py:meth:`.ProtocolContext.get_liquid_class` to name the Opentrons-verified liquid class you'll use in the protocol. :py:meth:`~.get_liquid_class` also takes into account pipettes and tipracks in your protocol to define transfer behavior. 
 
-
-Use the :py:meth:`.InstrumentContext.transfer_with_liquid_class` method to transfer an aqueous, volatile, or viscous liquid defined in a Flex protocol. This method accepts arguments that let you specify your liquid, volume, source and destination wells, tip handling preferences, and trash location. 
+Next, use the :py:meth:`.InstrumentContext.transfer_with_liquid_class` method to transfer an aqueous, volatile, or viscous liquid defined in a Flex protocol. This method requires the stored set of properties defined earlier, ``viscous_liquid``, instead of the ``glycerol_50`` load name. It accepts additional arguments that let you specify your liquid, volume, source and destination wells, tip handling preferences, and trash location. 
 
 Opentrons-verified liquid class definitions are based on Flex pipette and tip combinations. The API will raise an error if you try to perform a liquid class transfer with an OT-2 pipette and tips. 
 
-In the example below, a Flex P50 1-channel pipette will transfer 50 µL of your viscous ``liquid_1`` from each well of the  source plate to each well of the destination plate. A new tip is used for each well transfer, and each tip is dropped in the trash bin loaded in slot A3. 
+In the example below, a Flex P50 1-channel pipette will transfer 50 µL of your ``viscous_liquid`` from well A1 of the reservoir to well A1 of the destination plate. A new tip is used for each well transfer, and each tip is dropped in the trash bin loaded in slot A3. 
 
 .. code-block:: python
 
-    pipette_50.transfer_with_liquid_class(
-        liquid_class=liquid_1,
-        volume=50,
-        source=nest_plate.rows()[0],
-        dest=arma_plate.rows()[0],
-        new_tip="always",
-        trash_location=trash
-    )
+    # transfer with the viscous liquid class
+            pipette.transfer_with_liquid_class(
+              liquid_class=viscous_liquid,
+              volume=50,
+              source=reservoir["A1"],
+              dest=plate["A1"],
+              new_tip="always",
+              trash_location=trash
+            )
+  
+.. versionadded:: 2.24
 
 
 Here, the ``glycerol_50`` viscous liquid class definition accounts for all other transfer behavior, like flow rate, whether or not to add an air gap or delay, and submerge and retract speeds. For each aspirate, the pipette: 
@@ -202,57 +216,63 @@ Customizing Liquid Classes
 
 You can create your own liquid class to customize transfer behavior for any liquid in a Flex protocol. To make changes, you can edit individual properties of an existing liquid class, or add properties to a new liquid class. 
 
-To customize an Opentrons-verified liquid class, use :py:meth:`InstrumentContext.define_liquid_class` to define your custom liquid class after adding your pipettes, tips, trash, and labware::
+To customize an Opentrons-verified liquid class, first add your pipettes, tips, trash, and labware. Then, use :py:meth:`~.ProtocolContext.get_liquid_class` to specify the liquid class you'll make changes to::
+
+  # get base liquid class and custom properties for the Flex pipette and tips 
+            custom_water = protocol.get_liquid_class(name="water")
+            custom_water_properties=custom_water.get_for(pipette, tiprack)
 
-    ## customize based on the aqueous liquid class
-    custom_water = protocol_context.define_liquid_class(
-        name="custom_water",
-        properties=custom_liquid_class_properties,
-        base_liquid_class="aqueous",
-        display_name="Custom Water",
-    )
+.. versionadded:: 2.24
 
 Next, edit indivual liquid class properties based on your Flex pipette and tip combination. 
 
 .. code-block:: python
-
-    # access aqueous liquid class properties for the Flex 1-ch. pipette and tips
-    custom_water_props = custom_water.get_for(pipette_20, tiprack)
     
-    # edit aspirate submerge speed
-    custom_water_props.aspirate.submerge.speed = 80
+  # edit aspirate submerge speed to 80 μL/sec
+            custom_water_properties.aspirate.submerge.speed = 80
+
+  # edit aspirate flow rate by volume for 10 μL and 20 μL volumes
+            custom_water_properties.aspirate.flow_rate_by_volume.set_for_volume = [(10.0, 40.0)
+            custom_water_properties.aspirate.flow_rate_by_volume.set_for_volume = [(20.0, 30.0)]
+
+  # edit to delay for 1 sec before retracting after an aspirate
+            custom_water_properties.aspirate.retract.delay.enabled = True
+            custom_water_properties.aspirate.retract.delay.duration = 1.0
 
-    # edit aspirate flow rate by volume for 10 μL and 20 μL volumes
-    custom_water_props.aspirate.flow_rate_by_volume = [(10.0, 40.0), (20.0, 30.0)]
+.. versionadded:: 2.24
 
-    # edit to delay before an aspirate
-    custom_water_props.aspirate.delay = {"enabled": True} 
+Then, complete your transfers with the modified ``custom_water`` liquid class. 
 
+All Opentrons-verified liquid classes position the pipette relative to the well. To customize your liquid class to use :ref:`meniscus-relative <well-meniscus>` locations, set the ``positionReference`` to ``"liquid-meniscus"`` for actions like an aspirate or dispense.   
 
-You can also create a new liquid class for your Flex protocols. Instead of using an Opentrons-verified ``base_liquid_class``, you'll start from scratch, providing a value for `every required property <https://github.com/Opentrons/opentrons/blob/edge/shared-data/liquid-class/schemas/1.json>`__ in your liquid class. 
+You can also create a new liquid class for your Flex protocols. Instead of using an Opentrons-verified liquid class, you'll start from scratch, providing a value for `every required property <https://github.com/Opentrons/opentrons/blob/edge/shared-data/liquid-class/schemas/1.json>`__ in your liquid class. 
 
 .. code-block:: python
 
- # add all required properties, like aspirate properties, for the pipette, tip rack, and liquid class
-    custom_liquid_class_properties = {
-       "p20_single_gen2": {
-          "opentrons/opentrons_96_tiprack_20ul/1": {
-              "aspirate": {
-                 "aspirate_position": {
-                    "offset": {"x": 1, "y": 2, "z": 3},
-                    "position_reference": "well-bottom",
-                }
+ # examples of required properties in a dictionary for your pipette and tip racks
+            custom_liquid_class_properties = {
+            "flex_1channel_50": {
+                "opentrons/opentrons_flex_96_tiprack_50ul/1": {
+                    "aspirate": {
+                        "aspirate_position": {
+                            "offset": {"x": 1, "y": 2, "z": 3},
+                            "position_reference": "well-bottom",
+                        },
+                    },
+                },
+            }
     
-    # create a new liquid class
-    custom_viscous = protocol_context.define_liquid_class(
-        name="custom_viscous",
-        properties=custom_liquid_class_properties,
-        display_name="Custom Viscous",
-    )
+ # create a new liquid class
+              custom_viscous = protocol.define_liquid_class(
+                name="custom_viscous",
+                properties=custom_liquid_class_properties,
+                display_name="Custom Viscous"
+              )
 
+.. versionadded:: 2.24
 
-The example above only includes aspirate position properties. To create your liquid class, you'll need to define values for `required properties <https://github.com/Opentrons/opentrons/blob/edge/shared-data/liquid-class/schemas/1.json>` like submerging before aspirating or after dispensing, speeds and flow rates, and position offsets. 
+The example above is shortened and only includes aspirate position properties. To create your liquid class, you'll need to define values for all `required properties <https://github.com/Opentrons/opentrons/blob/edge/shared-data/liquid-class/schemas/1.json>` in your new liquid class, like submerging before aspirating or after dispensing, speeds and flow rates, and position offsets. 
 
 .. note:: 
 
-    The :py:meth:`.InstrumentContext.get_liquid_class` method only accepts Opentrons-verified liquid classes, like ``glycerol_50``. You'll need to use :py:meth:`.InstrumentContext.define_liquid_class` in each Flex protocol that uses a custom liquid class.
+    The :py:meth:`.ProtocolContext.get_liquid_class` method only accepts Opentrons-verified liquid classes, like ``glycerol_50``. You'll need to use :py:meth:`.ProtocolContext.define_liquid_class` in each Flex protocol that uses a custom liquid class.

api/docs/v2/new_examples.rst

@@ -193,7 +193,7 @@ This protocol uses some :ref:`building block commands <v2-atomic-commands>` to t
 Advanced Method
 ---------------
 
-These protocols accomplishes the same thing as the previous example, but does it a little more efficiently. Notice how it uses the :py:meth:`.InstrumentContext.transfer` or :py:meth:`InstrumentContext.transfer_with_liquid_class` method to move liquid between well plates. Because each is a complex command, you don't need separate calls to ``aspirate`` or ``dispense`` here.
+These protocols accomplishes the same thing as the previous example, but does it a little more efficiently. Notice how it uses the :py:meth:`.InstrumentContext.transfer` or :py:meth:`.InstrumentContext.transfer_with_liquid_class` method to move liquid between well plates. Because each is a complex command, you don't need separate calls to ``aspirate`` or ``dispense`` here.
 
 Let's start with a basic complex command, using ``transfer()``. The source and destination well  arguments (e.g., ``plate["A1"], plate["B1"]``) are part of ``transfer()`` method parameters. 
 

api/src/opentrons/protocol_api/instrument_context.py

@@ -1837,7 +1837,6 @@ def transfer_with_liquid_class(
             ``False``, the last tip will be dropped or returned. If not set, behavior depends on the value of
             ``new_tip``. ``new_tip="never"`` keeps the tip, and all other values of ``new_tip`` drop or return the tip.
 
-        :meta private:
         """
         if volume == 0.0:
             _log.info(
@@ -1966,7 +1965,6 @@ def distribute_with_liquid_class(
             ``False``, the last tip will be dropped or returned. If not set, behavior depends on the value of
             ``new_tip``. ``new_tip="never"`` keeps the tip, and all other values of ``new_tip`` drop or return the tip.
 
-        :meta private:
         """
         if volume == 0.0:
             _log.info(
@@ -2104,7 +2102,6 @@ def consolidate_with_liquid_class(
             ``False``, the last tip will be dropped or returned. If not set, behavior depends on the value of
             ``new_tip``. ``new_tip="never"`` keeps the tip, and all other values of ``new_tip`` drop or return the tip.
 
-        :meta private:
         """
         if volume == 0.0:
             _log.info(