bug: Clarity needed in docs re: simulation in jupyter

[eirinnm]

Currently the document Using Python for Protocols has this to say about simulating code in Jupyter:

In your Jupyter notebook, you can use the Python Protocol API simulator by doing

from opentrons import simulate
protocol = simulate.get_protocol_api('|apiLevel|')
p300 = protocol.load_instrument('p300_single', 'right')
# ...

The protocol object, which is an instance of .ProtocolContext, is the same thing that gets passed to your protocol's run function, but set to simulate rather than control an OT-2. You can call all your protocol's functions on that object.

It then says:

If you have a full protocol, wrapped inside a run function, defined in a Jupyter cell you can also use opentrons.simulate.simulate as described above to simulate the protocol.

However this last part seems not to be true. The opentrons.simulate.simulate function requires a python protocol as a text file, not a run() function. I cannot find a way to pass my protocol's run() function to the simulation and get the runlog. Is this possible, or are the docs mistaken?

[SyntaxColoring]

Thanks for the report!

However this last part seems not to be true. The opentrons.simulate.simulate function requires a python protocol as a text file, not a run() function. I cannot find a way to pass my protocol's run() function to the simulation and get the runlog. Is this possible, or are the docs mistaken?

I think the docs are mistaken. As far as I know, there's no way to pass your run() function to opentrons.simulate.simulate(). If you have a run() function and want to keep it, I think you're expected to do something like:

def run(protocol):
    ...

protocol = simulate.get_protocol_api(...)
run(protocol)

[eirinnm]

Thanks for your reply. My goal is to get the runlog (ie the steps taken by the robot) as well as detecting errors such as OutOfTips.

Since submitting this issue I've discovered that I can get what I want. The protocol object has a list of the steps, which can be retrieved by protocol.commands(). It doesn't have the indenting like that of the actual simulation runlog, but that's okay.

def run(protocol):
    ...

protocol = simulate.get_protocol_api('2.12')

try:
    run(protocol)
    print(f'Simulation successful. Number of steps: {len(protocol.commands())}')
except protocol_api.labware.OutOfTipsError:
    print('Simulation error (Out of tips)')
finally:
    # Print the steps used by the robot as a numbered list
    print(''.join([f'({i+1})\t{command}\n' for i, command in enumerate(protocol.commands())]))

I think it would be helpful if the docs informed users about this protocol.commands() function.