opentrons 8.1.0a0__py2.py3-none-any.whl → 8.2.0__py2.py3-none-any.whl

opentrons/protocol_api/core/engine/protocol.py

@@ -2,11 +2,17 @@
 from __future__ import annotations
 from typing import Dict, Optional, Type, Union, List, Tuple, TYPE_CHECKING
 
+from opentrons_shared_data.liquid_classes import LiquidClassDefinitionDoesNotExist
+
 from opentrons.protocol_engine import commands as cmd
 from opentrons.protocol_engine.commands import LoadModuleResult
 from opentrons_shared_data.deck.types import DeckDefinitionV5, SlotDefV3
 from opentrons_shared_data.labware.labware_definition import LabwareDefinition
 from opentrons_shared_data.labware.types import LabwareDefinition as LabwareDefDict
+from opentrons_shared_data import liquid_classes
+from opentrons_shared_data.liquid_classes.liquid_class_definition import (
+    LiquidClassSchemaV1,
+)
 from opentrons_shared_data.pipette.types import PipetteNameType
 from opentrons_shared_data.robot.types import RobotType
 
@@ -51,7 +57,7 @@ from opentrons.protocol_engine.errors import (
 
 from ... import validation
 from ..._types import OffDeckType
-from ..._liquid import Liquid
+from ..._liquid import Liquid, LiquidClass
 from ...disposal_locations import TrashBin, WasteChute
 from ..protocol import AbstractProtocol
 from ..labware import LabwareLoadParams
@@ -103,6 +109,7 @@ class ProtocolCore(
             str, Union[ModuleCore, NonConnectedModuleCore]
         ] = {}
         self._disposal_locations: List[Union[Labware, TrashBin, WasteChute]] = []
+        self._defined_liquid_class_defs_by_name: Dict[str, LiquidClassSchemaV1] = {}
         self._load_fixed_trash()
 
     @property
@@ -311,7 +318,6 @@ class ProtocolCore(
 
         return labware_core
 
-    # TODO (spp, 2022-12-14): https://opentrons.atlassian.net/browse/RLAB-237
     def move_labware(
         self,
         labware_core: LabwareCore,
@@ -323,6 +329,7 @@ class ProtocolCore(
             NonConnectedModuleCore,
             OffDeckType,
             WasteChute,
+            TrashBin,
         ],
         use_gripper: bool,
         pause_for_manual_move: bool,
@@ -723,6 +730,23 @@ class ProtocolCore(
             ),
         )
 
+    def define_liquid_class(self, name: str) -> LiquidClass:
+        """Define a liquid class for use in transfer functions."""
+        try:
+            # Check if we have already loaded this liquid class' definition
+            liquid_class_def = self._defined_liquid_class_defs_by_name[name]
+        except KeyError:
+            try:
+                # Fetching the liquid class data from file and parsing it
+                # is an expensive operation and should be avoided.
+                # Calling this often will degrade protocol execution performance.
+                liquid_class_def = liquid_classes.load_definition(name)
+                self._defined_liquid_class_defs_by_name[name] = liquid_class_def
+            except LiquidClassDefinitionDoesNotExist:
+                raise ValueError(f"Liquid class definition not found for '{name}'.")
+
+        return LiquidClass.create(liquid_class_def)
+
     def get_labware_location(
         self, labware_core: LabwareCore
     ) -> Union[str, LabwareCore, ModuleCore, NonConnectedModuleCore, OffDeckType]:
@@ -754,6 +778,7 @@ class ProtocolCore(
             NonConnectedModuleCore,
             OffDeckType,
             WasteChute,
+            TrashBin,
         ],
     ) -> LabwareLocation:
         if isinstance(location, LabwareCore):
@@ -770,6 +795,7 @@ class ProtocolCore(
             NonConnectedModuleCore,
             OffDeckType,
             WasteChute,
+            TrashBin,
         ]
     ) -> NonStackedLocation:
         if isinstance(location, (ModuleCore, NonConnectedModuleCore)):
@@ -783,3 +809,5 @@ class ProtocolCore(
         elif isinstance(location, WasteChute):
             # TODO(mm, 2023-12-06) This will need to determine the appropriate Waste Chute to return, but only move_labware uses this for now
             return AddressableAreaLocation(addressableAreaName="gripperWasteChute")
+        elif isinstance(location, TrashBin):
+            return AddressableAreaLocation(addressableAreaName=location.area_name)

opentrons/protocol_api/core/instrument.py

@@ -33,6 +33,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType]):
         rate: float,
         flow_rate: float,
         in_place: bool,
+        is_meniscus: Optional[bool] = None,
     ) -> None:
         """Aspirate a given volume of liquid from the specified location.
         Args:
@@ -55,6 +56,7 @@ class AbstractInstrument(ABC, Generic[WellCoreType]):
         flow_rate: float,
         in_place: bool,
         push_out: Optional[float],
+        is_meniscus: Optional[bool] = None,
     ) -> None:
         """Dispense a given volume of liquid into the specified location.
         Args:

opentrons/protocol_api/core/labware.py

@@ -97,6 +97,10 @@ class AbstractLabware(ABC, Generic[WellCoreType]):
     def is_adapter(self) -> bool:
         """Whether the labware is an adapter."""
 
+    @abstractmethod
+    def is_lid(self) -> bool:
+        """Whether the labware is a lid."""
+
     @abstractmethod
     def is_fixed_trash(self) -> bool:
         """Whether the labware is a fixed trash."""

opentrons/protocol_api/core/legacy/legacy_instrument_core.py

@@ -80,6 +80,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore]):
         rate: float,
         flow_rate: float,
         in_place: bool,
+        is_meniscus: Optional[bool] = None,
     ) -> None:
         """Aspirate a given volume of liquid from the specified location.
         Args:
@@ -122,6 +123,7 @@ class LegacyInstrumentCore(AbstractInstrument[LegacyWellCore]):
         flow_rate: float,
         in_place: bool,
         push_out: Optional[float],
+        is_meniscus: Optional[bool] = None,
     ) -> None:
         """Dispense a given volume of liquid into the specified location.
         Args:

opentrons/protocol_api/core/legacy/legacy_labware_core.py

@@ -138,6 +138,11 @@ class LegacyLabwareCore(AbstractLabware[LegacyWellCore]):
     def is_adapter(self) -> bool:
         return False  # Adapters were introduced in v2.15 and not supported in legacy protocols
 
+    def is_lid(self) -> bool:
+        return (
+            False  # Lids were introduced in v2.21 and not supported in legacy protocols
+        )
+
     def is_fixed_trash(self) -> bool:
         """Whether the labware is fixed trash."""
         return "fixedTrash" in self.get_quirks()

opentrons/protocol_api/core/legacy/legacy_protocol_core.py

@@ -17,7 +17,7 @@ from opentrons.protocols import labware as labware_definition
 
 from ...labware import Labware
 from ...disposal_locations import TrashBin, WasteChute
-from ..._liquid import Liquid
+from ..._liquid import Liquid, LiquidClass
 from ..._types import OffDeckType
 from ..protocol import AbstractProtocol
 from ..labware import LabwareLoadParams
@@ -267,7 +267,6 @@ class LegacyProtocolCore(
         """Load an adapter using its identifying parameters"""
         raise APIVersionError(api_element="Loading adapter")
 
-    # TODO (spp, 2022-12-14): https://opentrons.atlassian.net/browse/RLAB-237
     def move_labware(
         self,
         labware_core: LegacyLabwareCore,
@@ -278,6 +277,7 @@ class LegacyProtocolCore(
             legacy_module_core.LegacyModuleCore,
             OffDeckType,
             WasteChute,
+            TrashBin,
         ],
         use_gripper: bool,
         pause_for_manual_move: bool,
@@ -532,6 +532,10 @@ class LegacyProtocolCore(
         """Define a liquid to load into a well."""
         assert False, "define_liquid only supported on engine core"
 
+    def define_liquid_class(self, name: str) -> LiquidClass:
+        """Define a liquid class."""
+        assert False, "define_liquid_class is only supported on engine core"
+
     def get_labware_location(
         self, labware_core: LegacyLabwareCore
     ) -> Union[

opentrons/protocol_api/core/legacy_simulator/legacy_instrument_core.py

@@ -91,6 +91,7 @@ class LegacyInstrumentCoreSimulator(AbstractInstrument[LegacyWellCore]):
         rate: float,
         flow_rate: float,
         in_place: bool,
+        is_meniscus: Optional[bool] = None,
     ) -> None:
         if self.get_current_volume() == 0:
             # Make sure we're at the top of the labware and clear of any
@@ -132,6 +133,7 @@ class LegacyInstrumentCoreSimulator(AbstractInstrument[LegacyWellCore]):
         flow_rate: float,
         in_place: bool,
         push_out: Optional[float],
+        is_meniscus: Optional[bool] = None,
     ) -> None:
         if isinstance(location, (TrashBin, WasteChute)):
             raise APIVersionError(

opentrons/protocol_api/core/module.py

@@ -2,7 +2,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import List, Optional, TypeVar, ClassVar
+from typing import List, Dict, Optional, TypeVar, ClassVar
 
 from opentrons.drivers.types import (
     HeaterShakerLabwareLatchStatus,
@@ -16,6 +16,7 @@ from opentrons.hardware_control.modules.types import (
     MagneticStatus,
     SpeedStatus,
 )
+from opentrons.protocol_engine.types import ABSMeasureMode
 from opentrons.types import DeckSlotName
 
 
@@ -355,9 +356,26 @@ class AbstractAbsorbanceReaderCore(AbstractModuleCore):
         """Get the module's unique hardware serial number."""
 
     @abstractmethod
-    def initialize(self, wavelength: int) -> None:
+    def initialize(
+        self,
+        mode: ABSMeasureMode,
+        wavelengths: List[int],
+        reference_wavelength: Optional[int] = None,
+    ) -> None:
         """Initialize the Absorbance Reader by taking zero reading."""
 
     @abstractmethod
-    def initiate_read(self) -> None:
-        """Initiate read on the Absorbance Reader."""
+    def read(self, filename: Optional[str] = None) -> Dict[int, Dict[str, float]]:
+        """Get an absorbance reading from the Absorbance Reader."""
+
+    @abstractmethod
+    def close_lid(self) -> None:
+        """Close the Absorbance Reader's lid."""
+
+    @abstractmethod
+    def open_lid(self) -> None:
+        """Open the Absorbance Reader's lid."""
+
+    @abstractmethod
+    def is_lid_on(self) -> bool:
+        """Return True if the Absorbance Reader's lid is currently closed."""

opentrons/protocol_api/core/protocol.py

@@ -18,7 +18,7 @@ from opentrons.protocols.api_support.util import AxisMaxSpeeds
 from .instrument import InstrumentCoreType
 from .labware import LabwareCoreType, LabwareLoadParams
 from .module import ModuleCoreType
-from .._liquid import Liquid
+from .._liquid import Liquid, LiquidClass
 from .._types import OffDeckType
 from ..disposal_locations import TrashBin, WasteChute
 
@@ -93,7 +93,6 @@ class AbstractProtocol(
         """Load an adapter using its identifying parameters"""
         ...
 
-    # TODO (spp, 2022-12-14): https://opentrons.atlassian.net/browse/RLAB-237
     @abstractmethod
     def move_labware(
         self,
@@ -105,6 +104,7 @@ class AbstractProtocol(
             ModuleCoreType,
             OffDeckType,
             WasteChute,
+            TrashBin,
         ],
         use_gripper: bool,
         pause_for_manual_move: bool,
@@ -248,6 +248,10 @@ class AbstractProtocol(
     ) -> Liquid:
         """Define a liquid to load into a well."""
 
+    @abstractmethod
+    def define_liquid_class(self, name: str) -> LiquidClass:
+        """Define a liquid class for use in transfer functions."""
+
     @abstractmethod
     def get_labware_location(
         self, labware_core: LabwareCoreType

opentrons/protocol_api/instrument_context.py

@@ -39,12 +39,7 @@ from ._nozzle_layout import NozzleLayout
 from . import labware, validation
 
 
-AdvancedLiquidHandling = Union[
-    labware.Well,
-    types.Location,
-    Sequence[Union[labware.Well, types.Location]],
-    Sequence[Sequence[labware.Well]],
-]
+AdvancedLiquidHandling = transfers.AdvancedLiquidHandling
 
 _DEFAULT_ASPIRATE_CLEARANCE = 1.0
 _DEFAULT_DISPENSE_CLEARANCE = 1.0
@@ -222,8 +217,9 @@ class InstrumentContext(publisher.CommandPublisher):
             )
         )
 
-        well: Optional[labware.Well] = None
         move_to_location: types.Location
+        well: Optional[labware.Well] = None
+        is_meniscus: Optional[bool] = None
         last_location = self._get_last_location_by_api_version()
         try:
             target = validation.validate_location(
@@ -237,17 +233,13 @@ class InstrumentContext(publisher.CommandPublisher):
                 "knows where it is."
             ) from e
 
-        if isinstance(target, validation.WellTarget):
-            move_to_location = target.location or target.well.bottom(
-                z=self._well_bottom_clearances.aspirate
-            )
-            well = target.well
-        if isinstance(target, validation.PointTarget):
-            move_to_location = target.location
         if isinstance(target, (TrashBin, WasteChute)):
             raise ValueError(
                 "Trash Bin and Waste Chute are not acceptable location parameters for Aspirate commands."
             )
+        move_to_location, well, is_meniscus = self._handle_aspirate_target(
+            target=target
+        )
         if self.api_version >= APIVersion(2, 11):
             instrument.validate_takes_liquid(
                 location=move_to_location,
@@ -287,6 +279,7 @@ class InstrumentContext(publisher.CommandPublisher):
                 rate=rate,
                 flow_rate=flow_rate,
                 in_place=target.in_place,
+                is_meniscus=is_meniscus,
             )
 
         return self
@@ -389,6 +382,7 @@ class InstrumentContext(publisher.CommandPublisher):
             )
         )
         well: Optional[labware.Well] = None
+        is_meniscus: Optional[bool] = None
         last_location = self._get_last_location_by_api_version()
 
         try:
@@ -407,6 +401,7 @@ class InstrumentContext(publisher.CommandPublisher):
             well = target.well
             if target.location:
                 move_to_location = target.location
+                is_meniscus = target.location.is_meniscus
             elif well.parent._core.is_fixed_trash():
                 move_to_location = target.well.top()
             else:
@@ -472,6 +467,7 @@ class InstrumentContext(publisher.CommandPublisher):
                 flow_rate=flow_rate,
                 in_place=target.in_place,
                 push_out=push_out,
+                is_meniscus=is_meniscus,
             )
 
         return self
@@ -545,12 +541,12 @@ class InstrumentContext(publisher.CommandPublisher):
             ),
         ):
             self.aspirate(volume, location, rate)
-            while repetitions - 1 > 0:
-                self.dispense(volume, rate=rate, **dispense_kwargs)
-                self.aspirate(volume, rate=rate)
-                repetitions -= 1
-            self.dispense(volume, rate=rate)
-
+            with AutoProbeDisable(self):
+                while repetitions - 1 > 0:
+                    self.dispense(volume, rate=rate, **dispense_kwargs)
+                    self.aspirate(volume, rate=rate)
+                    repetitions -= 1
+                self.dispense(volume, rate=rate)
         return self
 
     @requires_version(2, 0)
@@ -2196,6 +2192,42 @@ class InstrumentContext(publisher.CommandPublisher):
                     )
             # SINGLE, QUADRANT and ALL are supported by all pipettes
 
+    def _handle_aspirate_target(
+        self, target: validation.ValidTarget
+    ) -> tuple[types.Location, Optional[labware.Well], Optional[bool]]:
+        move_to_location: types.Location
+        well: Optional[labware.Well] = None
+        is_meniscus: Optional[bool] = None
+        if isinstance(target, validation.WellTarget):
+            well = target.well
+            if target.location:
+                move_to_location = target.location
+                is_meniscus = target.location.is_meniscus
+
+            else:
+                move_to_location = target.well.bottom(
+                    z=self._well_bottom_clearances.aspirate
+                )
+        if isinstance(target, validation.PointTarget):
+            move_to_location = target.location
+        return (move_to_location, well, is_meniscus)
+
+
+class AutoProbeDisable:
+    """Use this class to temporarily disable automatic liquid presence detection."""
+
+    def __init__(self, instrument: InstrumentContext):
+        self.instrument = instrument
+
+    def __enter__(self) -> None:
+        if self.instrument.api_version >= APIVersion(2, 21):
+            self.auto_presence = self.instrument.liquid_presence_detection
+            self.instrument.liquid_presence_detection = False
+
+    def __exit__(self, *args: Any, **kwargs: Any) -> None:
+        if self.instrument.api_version >= APIVersion(2, 21):
+            self.instrument.liquid_presence_detection = self.auto_presence
+
 
 def _raise_if_has_end_or_front_right_or_back_left(
     style: NozzleLayout,

opentrons/protocol_api/labware.py

@@ -30,7 +30,6 @@ from opentrons.hardware_control.nozzle_manager import NozzleMap
 # remove when their usage is no longer needed
 from opentrons.protocols.labware import (  # noqa: F401
     get_labware_definition as get_labware_definition,
-    get_all_labware_definitions as get_all_labware_definitions,
     verify_definition as verify_definition,
     save_definition as save_definition,
 )
@@ -222,6 +221,19 @@ class Well:
         """
         return Location(self._core.get_center(), self)
 
+    @requires_version(2, 21)
+    def meniscus(self, z: float = 0.0) -> Location:
+        """
+        :param z: An offset on the z-axis, in mm. Positive offsets are higher and
+            negative offsets are lower.
+        :return: A :py:class:`~opentrons.types.Location` that indicates location is meniscus and that holds the ``z`` offset in its point.z field.
+
+        :meta private:
+        """
+        return Location(
+            point=Point(x=0, y=0, z=z), labware=self, _ot_internal_is_meniscus=True
+        )
+
     @requires_version(2, 8)
     def from_center_cartesian(self, x: float, y: float, z: float) -> Point:
         """

opentrons/protocol_api/module_contexts.py

@@ -1,16 +1,18 @@
 from __future__ import annotations
 
 import logging
-from typing import List, Optional, Union, cast
+from typing import List, Dict, Optional, Union, cast
 
+from opentrons_shared_data.errors.exceptions import CommandPreconditionViolated
+
+from opentrons.protocol_engine.types import ABSMeasureMode
 from opentrons_shared_data.labware.types import LabwareDefinition
 from opentrons_shared_data.module.types import ModuleModel, ModuleType
 
 from opentrons.legacy_broker import LegacyBroker
-from opentrons.hardware_control.modules import ThermocyclerStep
 from opentrons.legacy_commands import module_commands as cmds
 from opentrons.legacy_commands.publisher import CommandPublisher, publish
-from opentrons.protocols.api_support.types import APIVersion
+from opentrons.protocols.api_support.types import APIVersion, ThermocyclerStep
 from opentrons.protocols.api_support.util import (
     APIVersionError,
     requires_version,
@@ -159,7 +161,18 @@ class ModuleContext(CommandPublisher):
             load_location = loaded_adapter._core
         else:
             load_location = self._core
+
         name = validation.ensure_lowercase_name(name)
+
+        # todo(mm, 2024-11-08): This check belongs in opentrons.protocol_api.core.engine.deck_conflict.
+        # We're currently doing it here, at the ModuleContext level, for consistency with what
+        # ProtocolContext.load_labware() does. (It should also be moved to the deck_conflict module.)
+        if isinstance(self._core, AbsorbanceReaderCore):
+            if self._core.is_lid_on():
+                raise CommandPreconditionViolated(
+                    f"Cannot load {name} onto the Absorbance Reader Module when its lid is closed."
+                )
+
         labware_core = self._protocol_core.load_labware(
             load_name=name,
             label=label,
@@ -568,7 +581,7 @@ class ThermocyclerContext(ModuleContext):
                                  individual well of the loaded labware, in µL.
                                  If not specified, the default is 25 µL.
 
-        .. note:
+        .. note::
 
             If ``hold_time_minutes`` and ``hold_time_seconds`` are not
             specified, the Thermocycler will proceed to the next command
@@ -592,7 +605,7 @@ class ThermocyclerContext(ModuleContext):
         :param temperature: A value between 37 and 110, representing the target
                             temperature in °C.
 
-        .. note:
+        .. note::
 
             The Thermocycler will proceed to the next command immediately after
             ``temperature`` has been reached.
@@ -622,12 +635,19 @@ class ThermocyclerContext(ModuleContext):
                                  individual well of the loaded labware, in µL.
                                  If not specified, the default is 25 µL.
 
-        .. note:
+        .. note::
 
             Unlike with :py:meth:`set_block_temperature`, either or both of
             ``hold_time_minutes`` and ``hold_time_seconds`` must be defined
             and for each step.
 
+        .. note::
+
+            Before API Version 2.21, Thermocycler profiles run with this command
+            would be listed in the app as having a number of repetitions equal to
+            their step count. At or above API Version 2.21, the structure of the
+            Thermocycler cycles is preserved.
+
         """
         repetitions = validation.ensure_thermocycler_repetition_count(repetitions)
         validated_steps = validation.ensure_thermocycler_profile_steps(steps)
@@ -971,28 +991,106 @@ class MagneticBlockContext(ModuleContext):
 
 
 class AbsorbanceReaderContext(ModuleContext):
-    """An object representing a connected Absorbance Reader Module.
+    """An object representing a connected Absorbance Plate Reader Module.
 
     It should not be instantiated directly; instead, it should be
     created through :py:meth:`.ProtocolContext.load_module`.
 
-    .. versionadded:: 2.18
+    .. versionadded:: 2.21
     """
 
     _core: AbsorbanceReaderCore
 
     @property
-    @requires_version(2, 18)
+    @requires_version(2, 21)
     def serial_number(self) -> str:
         """Get the module's unique hardware serial number."""
         return self._core.get_serial_number()
 
-    @requires_version(2, 18)
-    def initialize(self, wavelength: int) -> None:
-        """Initialize the Absorbance Reader by taking zero reading."""
-        self._core.initialize(wavelength)
+    @requires_version(2, 21)
+    def close_lid(self) -> None:
+        """Use the Flex Gripper to close the lid of the Absorbance Plate Reader.
+
+        You must call this method before initializing the reader, even if the reader was
+        in the closed position at the start of the protocol.
+        """
+        self._core.close_lid()
+
+    @requires_version(2, 21)
+    def open_lid(self) -> None:
+        """Use the Flex Gripper to open the lid of the Absorbance Plate Reader."""
+        self._core.open_lid()
+
+    @requires_version(2, 21)
+    def is_lid_on(self) -> bool:
+        """Return ``True`` if the Absorbance Plate Reader's lid is currently closed."""
+        return self._core.is_lid_on()
 
-    @requires_version(2, 18)
-    def initiate_read(self) -> None:
-        """Initiate read on the Absorbance Reader."""
-        self._core.initiate_read()
+    @requires_version(2, 21)
+    def initialize(
+        self,
+        mode: ABSMeasureMode,
+        wavelengths: List[int],
+        reference_wavelength: Optional[int] = None,
+    ) -> None:
+        """Prepare the Absorbance Plate Reader to read a plate.
+
+        See :ref:`absorbance-initialization` for examples.
+
+        :param mode: Either ``"single"`` or ``"multi"``.
+
+            - In single measurement mode, :py:meth:`.AbsorbanceReaderContext.read` uses
+              one sample wavelength and an optional reference wavelength.
+            - In multiple measurement mode, :py:meth:`.AbsorbanceReaderContext.read` uses
+              a list of up to six sample wavelengths.
+        :param wavelengths: A list of wavelengths, in nm, to measure.
+
+            - In the default hardware configuration, each wavelength must be one of
+              ``450`` (blue), ``562`` (green), ``600`` (orange), or ``650`` (red). In
+              custom hardware configurations, the module may accept other integers
+              between 350 and 1000.
+            - The list must contain only one item when initializing a single measurement.
+            - The list can contain one to six items when initializing a multiple measurement.
+        :param reference_wavelength: An optional reference wavelength, in nm. If provided,
+            :py:meth:`.AbsorbanceReaderContext.read` will read at the reference
+            wavelength and then subtract the reference wavelength values from the
+            measurement wavelength values. Can only be used with single measurements.
+        """
+        self._core.initialize(
+            mode, wavelengths, reference_wavelength=reference_wavelength
+        )
+
+    @requires_version(2, 21)
+    def read(
+        self, export_filename: Optional[str] = None
+    ) -> Dict[int, Dict[str, float]]:
+        """Read a plate on the Absorbance Plate Reader.
+
+        This method always returns a dictionary of measurement data. It optionally will
+        save a CSV file of the results to the Flex filesystem, which you can access from
+        the Recent Protocol Runs screen in the Opentrons App. These files are `only` saved
+        if you specify ``export_filename``.
+
+        In simulation, the values for each well key in the dictionary are set to zero, and
+        no files are written.
+
+        .. note::
+
+            Avoid divide-by-zero errors when simulating and using the results of this
+            method later in the protocol. If you divide by any of the measurement
+            values, use :py:meth:`.ProtocolContext.is_simulating` to use alternate dummy
+            data or skip the division step.
+
+        :param export_filename: An optional file basename. If provided, this method
+            will write a CSV file for each measurement in the read operation. File
+            names will use the value of this parameter, the measurement wavelength
+            supplied in :py:meth:`~.AbsorbanceReaderContext.initialize`, and a
+            ``.csv`` extension. For example, when reading at wavelengths 450 and 562
+            with ``export_filename="my_data"``, there will be two output files:
+            ``my_data_450.csv`` and ``my_data_562.csv``.
+
+            See :ref:`absorbance-csv` for information on working with these CSV files.
+
+        :returns: A dictionary of wavelengths to dictionary of values ordered by well name.
+        """
+        return self._core.read(filename=export_filename)