fix OpentronsThermocyclerBackend.{get_current_cycle_index,get_total_cycle_count}

[rickwierenga]

what is a cycle precisely?

maybe we should update the standard to have methods for returning the current (stage, step) tuple instead of "cycle"?

[hazlamshamin]

if you mean for OT, from what I understand and see (also attached the code from their github), it's basically repetitions when u run a profile.

here's the method i see Opentrons AI usually use when writing PCR protocol when requested. so usually, when we ask for a standard PCR protocol, they will call multiple execute_protocol that separates transition from non-cyclic to cylic steps.

api/src/opentrons/protocol_api/core/module.py:

    @abstractmethod
    def execute_profile(
        self,
        steps: List[ThermocyclerStep],
        repetitions: int,
        block_max_volume: Optional[float] = None,
    ) -> None:
        """Execute a Thermocycler Profile.

        Profile defined as a cycle of ``steps`` to repeat for a given number of ``repetitions``

        Note:
            Unlike the :py:meth:`set_block_temperature`, either or both of
            'hold_time_minutes' and 'hold_time_seconds' must be defined
            and finite for each step.
        Args:
            steps: List of unique steps that make up a single cycle.
                Each list item should be a dictionary that maps to
                the parameters of the :py:meth:`set_block_temperature`
                method with keys 'temperature', 'hold_time_seconds',
                and 'hold_time_minutes'.
            repetitions: The number of times to repeat the cycled steps.
            block_max_volume: The maximum volume of any individual well
                of the loaded labware. If not supplied, the thermocycler
                will default to 25µL/well.
        """

example:

    # Initial denaturation
    tc_module.execute_profile(steps=[{'temperature': 94, 'hold_time_seconds': 120}],
                            repetitions=1,
                            block_max_volume=25)
    
    # Cycling (30 cycles)
    tc_module.execute_profile(steps=[
        {'temperature': 94, 'hold_time_seconds': 30},
        {'temperature': 55, 'hold_time_seconds': 30},
        {'temperature': 72, 'hold_time_seconds': 60}
    ],
    repetitions=30,
    block_max_volume=25)
    
    # Final extension
    tc_module.execute_profile(steps=[{'temperature': 72, 'hold_time_seconds': 300}],
                            repetitions=1,
                            block_max_volume=25)

however, since in ot_api, we mostly use commands, the runProfile actually default to repetitions=1, so we can only pass a linearised steps. since the opentrons http api set this here:

api/src/opentrons/protocol_engine/commands/thermocycler/run_profile.py

    async def execute(self, params: RunProfileParams) -> SuccessData[RunProfileResult]:
        """Run a Thermocycler profile."""
        thermocycler_state = self._state_view.modules.get_thermocycler_module_substate(
            params.moduleId
        )
        thermocycler_hardware = self._equipment.get_module_hardware_api(
            thermocycler_state.module_id
        )

        steps = [
            ThermocyclerStep(
                temperature=thermocycler_state.validate_target_block_temperature(
                    profile_step.celsius
                ),
                hold_time_seconds=profile_step.holdSeconds,
            )
            for profile_step in params.profile
        ]

        target_volume: Optional[float]
        if params.blockMaxVolumeUl is not None:
            target_volume = thermocycler_state.validate_max_block_volume(
                params.blockMaxVolumeUl
            )
        else:
            target_volume = None

        if thermocycler_hardware is not None:
            # TODO(jbl 2022-06-27) hardcoded constant 1 for `repetitions` should be
            #  moved from HardwareControlAPI to the Python ProtocolContext
            await thermocycler_hardware.cycle_temperatures(
                steps=steps, repetitions=1, volume=target_volume
            )

        return SuccessData(
            public=RunProfileResult(),
        )

compared to another command, runExtendedProfile (i actually just noticed this exist) where we can actually combine ProfileStep and ProfileCycle (but im not really sure then why execute_profile needs to be called many times if this command can be used?)

api/src/opentrons/protocol_api/core/module.py:

class ProfileStep(BaseModel):
    """An individual step in a Thermocycler extended profile."""

    celsius: float = Field(..., description="Target temperature in °C.")
    holdSeconds: float = Field(
        ..., description="Time to hold target temperature in seconds."
    )


class ProfileCycle(BaseModel):
    """An individual cycle in a Thermocycler extended profile."""

    steps: List[ProfileStep] = Field(..., description="Steps to repeat.")
    repetitions: int = Field(..., description="Number of times to repeat the steps.")


class RunExtendedProfileParams(BaseModel):
    """Input parameters for an individual Thermocycler profile step."""

    moduleId: str = Field(..., description="Unique ID of the Thermocycler.")
    profileElements: List[Union[ProfileStep, ProfileCycle]] = Field(
        ...,
        description="Elements of the profile. Each can be either a step or a cycle.",
    )
    blockMaxVolumeUl: float | SkipJsonSchema[None] = Field(
        None,
        description="Amount of liquid in uL of the most-full well"
        " in labware loaded onto the thermocycler.",
        json_schema_extra=_remove_default,
    )

therefore, when call get_current_cycle_index, get_total_cycle_count, we are getting them within the current cycle. i will also later do PR to replace all these get_ functions to rely directly on Opentrons HTTP API (so easier to trace as well), than currently getting the info using find_module.get() (tho this already work in functionality).

[hazlamshamin]

wdym by stage in the (stage, step) tuple? specific examples? issit like predefined stages, like pre-denaturation, denaturation, annealing etc?

[rickwierenga]

thanks for looking into this. so the cycle is an index within the current profile, and since we always have 1 it will always be 1. step is the index within the 'cycle'

runExtendedProfile seems to match the new PLR api (in proflex branch), with stages (they call it cycle, which is a horribly confusing name) and steps within stages. the difference is the extended one has profileElements whereas run_profile just uses one cycle (potentially multiple repeats in OT, but only 1 repeat in our ot_api)

1. we could migrate to extended and it would make our implementation a bit simpler
2. we could also keep using the current implementation (linearizing all protocols)

i would lean towards option 1 since it's simpler and more elegant

[rickwierenga]

wdym by stage in the (stage, step) tuple? specific examples? issit like predefined stages, like pre-denaturation, denaturation, annealing etc?

stage is a list of steps that potentially repeats. a step is one temperature, duration tuple

[hazlamshamin]

i think option 1 is more biologically intuitive too for a pcr machine. therefore we also gonna retain {get_current_cycle_index,get_total_cycle_count}?

[rickwierenga]

yes (stage in PLR)

index sounds useful, count can be done without making requests to the machine if we keep a copy of the running protocol/profile