docs(protocol-designer): proposal for adding Python to step generation

protocol-designer/docs/PYTHON_STEP_GENERATION.md

@@ -0,0 +1,110 @@
+# Python Step Generation
+
+We want to add Python generation to `step-generation` without severely changing the architecture and rewriting all the code.
+
+## Where does the Python go?
+
+The command creators produce a `CommandCreatorResult`. We'll augment that to include Python commands:
+
+```typescript
+export type CommandCreatorResult =
+  | CommandsAndWarnings
+  | CommandCreatorErrorResponse
+
+export interface CommandsAndWarnings {
+  commands: CreateCommand[]
+  warnings?: CommandCreatorWarning[]
+  python?: string // <<<ADD
+}
+```
+
+Here and elsewhere, we make `python` an optional field so that we don't have to rewrite all the existing code to specify it when creating objects.
+
+The new `python` field contains one or more lines of Python commands. It behaves analogously to the JSON `commands`. When reducing `CurriedCommandCreator`s together, we concatenate their JSON `commands`, so now we will also concatenate their `python` commands too:
+
+```typescript
+export const reduceCommandCreators = (...): CommandCreatorResult => {
+  const result = commandCreators.reduce(
+    (prev: CCReducerAcc, reducerFn: CurriedCommandCreator): CCReducerAcc => {
+      const allCommands = [...prev.commands, ...next.commands]
+      const allPython = [prev.python, next.python].join('\n')  // <<<NEW
+      return {
+        commands: allCommands,
+        python: allPython,  // <<<NEW
+      }
+    },
+    ...
+  )
+}
+```
+
+## Data flow
+
+The JSON commands from the `CommandCreatorResult`s get propagated to the `Timeline`, which is where we ultimately get the commands from to write out to the exported JSON file. By analogy, we'll add the Python commands to the `Timeline` as well:
+
+```typescript
+export interface Timeline {
+  timeline: CommandsAndRobotState[]
+  errors?: CommandCreatorError[] | null
+}
+
+export interface CommandsAndRobotState {
+  commands: CreateCommand[]
+  robotState: RobotState
+  warnings?: CommandCreatorWarning[]
+  python?: string // <<<ADD
+}
+```
+
+## Generating JSON and Python in parallel
+
+In the easy case, one JSON command corresponds to one Python command, and we can just emit them side-by-side, like:
+
+```typescript
+export const aspirate: CommandCreator<...> = (args, invariantContext, prevRobotState) => {
+  return {
+    commands: [ { commandType: 'aspirate', params: {...} } ],
+    python: `some_pipette.aspirate(...)`,
+  }
+}
+```
+
+Sometimes, we want to emit a Python command that doesn't correspond to any single JSON command. For example, the command sequence for a Mix step has something like:
+
+```typescript
+[
+    curryCommandCreator(aspirate, {...}),
+    curryCommandCreator(dispense, {...}),
+]
+```
+
+The Python API has a `mix()` that implements both aspirate and dispense. We can generate it by adding a `CommandCreator` that emits the Python `mix()` command with no JSON command:
+
+```typescript
+[
+    curryCommandCreator(pythonOnlyMix, {...}),
+    curryCommandCreator(aspirate, {...}),
+    curryCommandCreator(dispense, {...}),
+]
+
+const pythonOnlyMix: CommandCreator<...> = (...) => {
+    return {
+        commands: [],  // emits no JSON
+        python: `some_pipette.mix(...)`,
+    }
+}
+```
+
+When the reducer runs, it joins together all the non-empty JSON `commands` to get the final JSON output, and it'll join together all the non-empty `python` commands to get the final Python output.
+
+We need one more tool to make this work: because the Python `mix()` command replaces both the aspirate and dispense, we need to _suppress_ Python generation from aspirate and dispense. We'll do that by adding a new flag to `curryCommandCreator`, so the final sequence becomes:
+
+```typescript
+[
+    curryCommandCreator(pythonOnlyMix, {...}),
+    curryCommandCreator(aspirate, {...}, suppressPython=true),
+    curryCommandCreator(dispense, {...}, suppressPython=true),
+]
+```
+
+Now this sequence works for generating both JSON and Python.

protocol-designer/src/file-data/selectors/fileCreator.ts

@@ -356,6 +356,16 @@ export const createFile: Selector<ProtocolFile> = createSelector(
 
     const commands = [...loadCommands, ...nonLoadCommands]
 
+    // Print the combined Python commands for every timeline step:
+    console.log(
+      robotStateTimeline.timeline
+        .map(
+          (timelineFrame, idx) =>
+            `# Step ${idx + 1}\n${timelineFrame.python || ''}`
+        )
+        .join('\n\n')
+    )
+
     const flexDeckSpec: OT3RobotMixin = {
       robot: {
         model: FLEX_ROBOT_TYPE,

step-generation/src/commandCreators/atomic/aspirate.ts

@@ -261,5 +261,6 @@ export const aspirate: CommandCreator<ExtendedAspirateParams> = (
   ]
   return {
     commands,
+    python: `blah.aspirate(volume=${volume}, ...etc...)`,
   }
 }

step-generation/src/commandCreators/compound/mix.ts

@@ -28,6 +28,7 @@ import type {
   CommandCreator,
   CurriedCommandCreator,
 } from '../../types'
+import { curryCommandCreatorNoPython } from '../../utils/curryCommandCreator'
 /** Helper fn to make mix command creators w/ minimal arguments */
 export function mixUtil(args: {
   pipette: string
@@ -68,6 +69,14 @@ export function mixUtil(args: {
     nozzles,
   } = args
 
+  // This CommandCreator produces a Python command with no JSON command.
+  const pythonMixCommand: CommandCreator<{}> = () => {
+    return {
+      commands: [],
+      python: `blah.mix(repititions=${times}, location=blah.['${well}'], volume=${volume}, ...etc...)`,
+    }
+  }
+
   const getDelayCommand = (seconds?: number | null): CurriedCommandCreator[] =>
     seconds
       ? [
@@ -81,9 +90,16 @@ export function mixUtil(args: {
         ]
       : []
 
-  return repeatArray(
+  // If there is no delay, then we can issue a single Python mix() command, so we want to suppresss
+  // the Python from the individual aspirate dispense commands.
+  const noDelay = !aspirateDelaySeconds && !dispenseDelaySeconds
+  const innerCurryCommandCreator = noDelay
+    ? curryCommandCreatorNoPython
+    : curryCommandCreator
+
+  const commands = repeatArray(
     [
-      curryCommandCreator(aspirate, {
+      innerCurryCommandCreator(aspirate, {
         pipette,
         volume,
         labware,
@@ -96,7 +112,7 @@ export function mixUtil(args: {
         nozzles: null,
       }),
       ...getDelayCommand(aspirateDelaySeconds),
-      curryCommandCreator(dispense, {
+      innerCurryCommandCreator(dispense, {
         pipette,
         volume,
         labware,
@@ -112,6 +128,11 @@ export function mixUtil(args: {
     ],
     times
   )
+
+  return [
+    ...(noDelay ? [curryCommandCreator(pythonMixCommand, {})] : []),
+    ...commands,
+  ]
 }
 export const mix: CommandCreator<MixArgs> = (
   data,

step-generation/src/types.ts

@@ -624,6 +624,7 @@ export interface CommandsAndRobotState {
   commands: CreateCommand[]
   robotState: RobotState
   warnings?: CommandCreatorWarning[]
+  python?: string
 }
 
 export interface CommandCreatorErrorResponse {
@@ -634,6 +635,7 @@ export interface CommandCreatorErrorResponse {
 export interface CommandsAndWarnings {
   commands: CreateCommand[]
   warnings?: CommandCreatorWarning[]
+  python?: string
 }
 export type CommandCreatorResult =
   | CommandsAndWarnings

step-generation/src/utils/commandCreatorsTimeline.ts

@@ -53,6 +53,7 @@ export const commandCreatorsTimeline = (
         commands: commandCreatorResult.commands,
         robotState: nextRobotStateAndWarnings.robotState,
         warnings: commandCreatorResult.warnings,
+        python: commandCreatorResult.python,
       }
       return {
         timeline: [...acc.timeline, nextResult],

step-generation/src/utils/curryCommandCreator.ts

@@ -9,3 +9,21 @@ export function curryCommandCreator<Args>(
   return (_invariantContext, _prevRobotState) =>
     commandCreator(args, _invariantContext, _prevRobotState)
 }
+
+export function curryCommandCreatorNoPython<Args>(
+  commandCreator: CommandCreator<Args>,
+  args: Args
+): CurriedCommandCreator {
+  return (_invariantContext, _prevRobotState) => {
+    const commandCreatorResult = commandCreator(
+      args,
+      _invariantContext,
+      _prevRobotState
+    )
+    if ('python' in commandCreatorResult) {
+      const { python, ...withoutPython } = commandCreatorResult
+      return withoutPython
+    }
+    return commandCreatorResult
+  }
+}

step-generation/src/utils/reduceCommandCreators.ts

@@ -13,6 +13,7 @@ interface CCReducerAcc {
   commands: CreateCommand[]
   errors: CommandCreatorError[]
   warnings: CommandCreatorWarning[]
+  python?: string
 }
 export const reduceCommandCreators = (
   commandCreators: CurriedCommandCreator[],
@@ -41,6 +42,10 @@ export const reduceCommandCreators = (
         invariantContext,
         prev.robotState
       )
+      const allPython = [
+        ...(prev.python ? [prev.python] : []),
+        ...(next.python ? [next.python] : []),
+      ].join('\n')
       return {
         ...prev,
         robotState: updates.robotState,
@@ -50,6 +55,7 @@ export const reduceCommandCreators = (
           ...(next.warnings || []),
           ...updates.warnings,
         ],
+        ...(allPython && { python: allPython }),
       }
     },
     {
@@ -69,5 +75,6 @@ export const reduceCommandCreators = (
   return {
     commands: result.commands,
     warnings: result.warnings,
+    python: result.python,
   }
 }