### Install Development Dependencies

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/CONTRIBUTING.rst

Installs the necessary packages for testing and documentation, and initializes the pre-commit hooks.

```sh
pip install -e '.[test, docs]'
pre-commit install
```

--------------------------------

### Install Autoprotocol from source

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/index.md

Clones the repository and installs the library from the local source code.

```bash
git clone https://github.com/autoprotocol/autoprotocol-python
cd autoprotocol-python
python setup.py install
```

--------------------------------

### Install Autoprotocol via pip

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/index.md

Installs the latest stable release of the library.

```bash
pip install autoprotocol
```

--------------------------------

### Gradient Thermocycle Protocol Setup

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Initial setup for a gradient thermocycle protocol.

```python
p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-pcr",
                     storage="warm_37")

```

--------------------------------

### Incubate a plate in Autoprotocol

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Example of sealing a plate and setting it to incubate at 37 degrees for one hour with shaking enabled.

```python
p.seal(sample_plate)
p.incubate(sample_plate, "warm_37", "1:hour", shaking=True)
```

```none
"instructions": [
    {
       "object": "sample_plate",
       "op": "seal"
    },
    {
        "duration": "1:hour",
        "where": "warm_37",
        "object": "sample_plate",
        "shaking": true,
        "op": "incubate",
        "co2_percent": 0
    }
  ]
```

--------------------------------

### Perform Absorbance Measurement

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Example of initializing a protocol, defining a plate reference, and executing an absorbance read on a set of wells.

```python
p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.absorbance(sample_plate, sample_plate.wells_from(0,12),
             "600:nanometer", "test_reading", flashes=50)
```

--------------------------------

### Thermocycle Protocol Implementation

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Example of setting up a standard thermocycle protocol using the Autoprotocol Python library.

```python
from instruction import Thermocycle

p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-pcr",
                     storage="warm_37")

# a plate must be sealed before it can be thermocycled
p.seal(sample_plate)

p.thermocycle(
    sample_plate,
    [
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("95:celsius", "5:minute")
            ]
        ),
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("95:celsius", "30:s"),
                Thermocycle.builders.step("56:celsius", "20:s"),
                Thermocycle.builders.step("72:celsius", "20:s"),
            ],
            cycles=30
        ),
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("72:celsius", "10:minute")
            ]
        ),
        Thermocycle.builders.group(
            steps=[
                Thermocycle.builders.step("4:celsius", "30:s")
            ]
        )
    ],
    lid_temperature="97:celsius"
)

```

--------------------------------

### Perform Gel Purification in Autoprotocol

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Example of setting up a protocol and executing a gel_purify instruction with defined extract parameters.

```python
p = Protocol()
sample_wells = p.ref("test_plate", None, "96-pcr",
                     discard=True).wells_from(0, 8)
extract_wells = [p.ref("extract_" + str(i.index), None,
                       "micro-1.5", storage="cold_4").well(0)
                 for i in sample_wells]


extracts = [make_gel_extract_params(
                w,
                make_band_param(
                    "TE",
                    "5:microliter",
                    80,
                    79,
                    extract_wells[i]))
                for i, w in enumerate(sample_wells)]

p.gel_purify(extracts, "10:microliter",
             "size_select(8,0.8%)", "ladder1",
             "gel_purify_example")
```

--------------------------------

### Discard Container Example

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/container.md

Example demonstrating how to discard a container within an Autoprotocol script. This results in the container being marked for discard in the generated JSON.

```python
p = Protocol()
container = p.ref("new_container", cont_type="96-pcr",
                  storage="cold_20")
p.incubate(c, "warm_37", "30:minute")
container.discard()
```

--------------------------------

### Dispense with Nozzle Position and Shape

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

This example demonstrates dispensing a reagent with specific nozzle positioning and shape configurations. The `Dispense.builders.nozzle_position` and `shape_builder` are used to define these parameters.

```python
p.dispense(
    sample_plate,
    "water",
    Dispense.builders.columns(
        [Dispense.builders.column(0, "10:uL")]
    ),
    Dispense.builders.nozzle_position(
        position_x=Unit("1:mm"),
        position_y=Unit("2:mm"),
        position_z=Unit("20:mm")
    ),
    shape_builder(
        rows=8, columns=1, format="SBS96"
    )
)
```

--------------------------------

### Perform Sanger Sequencing

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Example of defining a container and executing a sangerseq instruction within a protocol.

```python
p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.sangerseq(sample_plate,
            sample_plate.wells_from(0,5).indices(),
            "seq_data_022415")
```

```none
"instructions": [
    {
        "dataref": "seq_data_022415",
        "object": "sample_plate",
        "wells": [
            "A1",
            "A2",
            "A3",
            "A4",
            "A5"
        ],
        "op": "sanger_sequence"
    }
]
```

--------------------------------

### Dispense Using Multiple Chips from a Single Source Tube

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

This example demonstrates dispensing using multiple intake hoses from a single source tube to multiple columns of a destination plate. Note the source is defined as a list of tuples, where each tuple contains a Well and the number of intake hoses.

```python
from autoprotocol import Unit
from autoprotocol import Protocol

p = Protocol()
source = p.ref("source", cont_type="micro-2.0", discard=True).well(0)
destination = p.ref("destination", cont_type="96-flat", discard=True)

intake_hoses = 3
number_dispense_columns = 5
source: List[Tuple[Well, int]] = [(source, intake_hoses)]

destination = [destination.wells_from(0, num_dispense_columns)]
self.protocol.liquid_handle_dispense(
    source=source,
    destination=destination,
    volume='100:microliter',
)
```

--------------------------------

### Evaporate Builders - Get Mode Parameters

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/builders.md

Checks the validity of evaporation mode and its parameters, and creates a dictionary for mode parameters.

```APIDOC
## get_mode_params(mode: EvaporateBuildersValidModes | str, mode_params: Dict[str, Any])

### Description
Checks on the validity of mode and mode_params, and creates a dictionary for mode_params.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
* **mode** (Str) – Mode of the evaporate method.
* **mode_params** (Dict) – Method parameters for each mode.

### Request Example
```json
{
  "mode": "evaporate",
  "mode_params": {
    "duration": "30:minute",
    "temperature": "60:celsius",
    "speed": "100:rpm"
  }
}
```

### Response
#### Success Response (200)
* **Dict** - Dictionary of mode_params

#### Response Example
```json
{
  "mode": "evaporate",
  "mode_params": {
    "duration": {
      "value": 30,
      "unit": "minute"
    },
    "temperature": {
      "value": 60,
      "unit": "celsius"
    },
    "speed": {
      "value": 100,
      "unit": "rpm"
    }
  }
}
```

### Error Handling
* **ValueError** – If mode is not specified.
* **ValueError** – If specified mode is not a valid mode.
* **ValueError** – If mode_params contain key(s) that are not applicable for the specified mode.
* **TypeError** – If there are multiple speed parameters.
* **ValueError** – If container agitation speed is less than 0.
* **ValueError** – If vacuum_pressure is less than 0 torr.
```

--------------------------------

### Sonicate Wells using Bath Mode

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Example of sonicating wells using the 'bath' mode with specified duration and mode parameters. Ensure the 'sample_holder' is a valid enum value.

```python
p = Protocol()
sample_wells = p.ref("sample_plate",
                   None,
                   "96-pcr",
                   storage="warm_37").wells_from(0,2)

p.sonicate(sample_wells, duration="1:minute",
           mode="bath",
           mode_params={"sample_holder": "suspender"})
```

--------------------------------

### Get Wells from Container

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/container.md

Retrieve a group of wells from a container starting at a specified index. Wells are counted rowwise by default, but can be counted columnwise.

```python
container.wells_from(start='A1', num=12)
container.wells_from(start=0, num=12, columnwise=True)
```

--------------------------------

### Protocol Class Initialization

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Demonstrates how to initialize a Protocol object and add a reference to a container.

```APIDOC
## Protocol Initialization and Container Referencing

### Description
Initializes a Protocol object and demonstrates how to add a reference to a container using the `ref()` method.

### Method
`Protocol(refs=None, instructions=None, propagate_properties=False, time_constraints=None)`

### Endpoint
N/A (Class Initialization)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
p = Protocol()
my_plate = p.ref("my_plate", id="ct1xae8jabbe6",
                        cont_type="96-pcr", storage="cold_4")
```

### Response
#### Success Response (200)
N/A (Object Initialization)

#### Response Example
N/A
```

--------------------------------

### Generate Documentation

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/CONTRIBUTING.rst

Builds the HTML documentation using Sphinx from the docs directory.

```bash
cd docs  # Assuming you're in the root cloned directory
sphinx-build -W -b html -d tmp/doctrees . tmp/html
```

--------------------------------

### Autoprotocol JSON Output

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/index.md

The resulting JSON structure generated by the protocol example.

```json
{
  "instructions": [
    {
      "op": "seal",
      "object": "test pcr plate",
      "type": "foil",
      "mode": "thermal",
      "mode_params": {
        "temperature": "165:celsius",
        "duration": "1.5:second"
      }
    },
    {
      "op": "spin",
      "object": "test pcr plate",
      "acceleration": "1000:g",
      "duration": "1:minute"
    }
  ],
  "refs": {
    "test pcr plate": {
      "new": "96-pcr",
      "discard": true
    }
  }
}
```

--------------------------------

### Capture container images

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Demonstrates how to use image_plate to capture images of a container after incubation.

```python
p = Protocol()

agar_plate = p.ref("agar_plate", None, "1-flat", discard=True)
bact = p.ref("bacteria", None, "micro-1.5", discard=True)

p.spread(bact.well(0), agar_plate.well(0), "55:microliter")
p.incubate(agar_plate, "warm_37", "18:hour")
p.image_plate(agar_plate, mode="top", dataref="my_plate_image_1")
```

```json
{
  "refs": {
    "bacteria": {
      "new": "micro-1.5",
      "discard": true
    },
    "agar_plate": {
      "new": "1-flat",
      "discard": true
    }
  },
  "instructions": [
    {
      "volume": "55.0:microliter",
      "to": "agar_plate/0",
      "from": "bacteria/0",
      "op": "spread"
    },
    {
      "where": "warm_37",
      "object": "agar_plate",
      "co2_percent": 0,
      "duration": "18:hour",
      "shaking": false,
      "op": "incubate"
    },
    {
      "dataref": "my_plate_image_1",
      "object": "agar_plate",
      "mode": "top",
      "op": "image_plate"
    }
  ]
}
```

--------------------------------

### Autoprotocol Fluorescence Output

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

This is an example of the JSON output generated by the Autoprotocol library after executing the fluorescence instruction.

```json
{
    "instructions": [
        {
            "dataref": "test_reading",
            "excitation": "587:nanometer",
            "object": "sample_plate",
            "emission": "610:nanometer",
            "wells": [
                "A1",
                "A2",
                "A3",
                "A4",
                "A5",
                "A6",
                "A7",
                "A8",
                "A9",
                "A10",
                "A11",
                "A12"
            ],
            "num_flashes": 25,
            "op": "fluorescence"
        }
    ]
}
```

--------------------------------

### Incubate Instruction

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/instruction.md

Use Incubate to store a sample in a specific environment for a set duration. Supports ambient, warm, and cold temperatures, with options for shaking and CO2 levels.

```python
from autoprotocol.instruction import Incubate

Incubate(object='tube1', where='warm_37', duration='2:hour')
Incubate(object='tube1', where='cold_4', duration='1:day', shaking=True)
Incubate(object='tube1', where='ambient', duration='30:min', co2=5.0, target_temperature='37:degC', shaking_params={'path': 'shaker1', 'frequency': '300:rpm'})
```

--------------------------------

### Run Linting and Formatting

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/CONTRIBUTING.rst

Manually triggers the pre-commit linting and auto-formatting checks.

```sh
pre-commit run
```

--------------------------------

### Autoprotocol dispense_full_plate Output

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

This is an example of the JSON output generated by the dispense_full_plate function, detailing the dispense operation.

```none
"instructions": [
    {
        "reagent": "water",
        "object": "sample_plate",
        "columns": [
            {
                "column": 0,
                "volume": "100:microliter"
            },
            {
                "column": 1,
                "volume": "100:microliter"
            },
            {
                "column": 2,
                "volume": "100:microliter"
            },
            {
                "column": 3,
                "volume": "100:microliter"
            },
            {
                "column": 4,
                "volume": "100:microliter"
            },
            {
                "column": 5,
                "volume": "100:microliter"
            },
            {
                "column": 6,
                "volume": "100:microliter"
            },
            {
                "column": 7,
                "volume": "100:microliter"
            },
            {
                "column": 8,
                "volume": "100:microliter"
            },
            {
                "column": 9,
                "volume": "100:microliter"
            },
            {
                "column": 10,
                "volume": "100:microliter"
            },
            {
                "column": 11,
                "volume": "100:microliter"
            }
        ],
        "op": "dispense"
    }
]
```

--------------------------------

### Uncover Instruction

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/instruction.md

API documentation for uncovering a container.

```APIDOC
## Uncover Instruction

### Description
Remove lid from specified container.

### Method
POST

### Endpoint
/autoprotocol/autoprotocol-python/instruction/Uncover

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **object** (str) - Required - Container to remove lid from
- **store_lid** (bool) - Optional - Flag to store the uncovered lid

### Request Example
```json
{
  "object": "container_id",
  "store_lid": true
}
```

### Response
#### Success Response (200)
- **status** (str) - Indicates success of the operation

#### Response Example
```json
{
  "status": "success"
}
```
```

--------------------------------

### Autoprotocol Gel Separate Instruction Output

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

This is an example of the JSON output generated by the Autoprotocol library for a gel_separate operation.

```none
"instructions": [
    {
        "dataref": "genotyping_030214",
        "matrix": "agarose(8,0.8%)",
        "volume": "10:microliter",
        "ladder": "ladder1",
        "objects": [
            "sample_plate/0",
            "sample_plate/1",
            "sample_plate/2",
            "sample_plate/3",
            "sample_plate/4",
            "sample_plate/5",
            "sample_plate/6",
            "sample_plate/7",
            "sample_plate/8",
            "sample_plate/9",
            "sample_plate/10",
            "sample_plate/11"
        ],
        "duration": "11:minute",
        "op": "gel_separate"
    }
]
```

--------------------------------

### Create and Manage Protocols with Protocol Class

Source: https://context7.com/autoprotocol/autoprotocol-python/llms.txt

Use the Protocol class to create a new protocol instance, reference containers, add instructions like sealing and incubation, and serialize the protocol to Autoprotocol JSON.

```python
import json
from autoprotocol.protocol import Protocol

# Create a new protocol instance
p = Protocol()

# Reference containers - either new or existing
new_plate = p.ref("my_plate", cont_type="96-pcr", discard=True)
existing_plate = p.ref("sample_plate", id="ct1xae8jabbe6", cont_type="96-flat", storage="cold_4")

# Add instructions to the protocol
p.seal(new_plate)
p.incubate(new_plate, "warm_37", "1:hour")

# Serialize to Autoprotocol JSON
protocol_json = p.as_dict()
print(json.dumps(protocol_json, indent=2))
```

--------------------------------

### Perform luminescence measurement

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Example usage of the luminescence method within a protocol and the resulting Autoprotocol JSON output.

```python
p = Protocol()
sample_plate = p.ref("sample_plate",
                     None,
                     "96-flat",
                     storage="warm_37")

p.luminescence(sample_plate, sample_plate.wells_from(0,12),
               "test_reading")
```

```none
"instructions": [
    {
        "dataref": "test_reading",
        "object": "sample_plate",
        "wells": [
            "A1",
            "A2",
            "A3",
            "A4",
            "A5",
            "A6",
            "A7",
            "A8",
            "A9",
            "A10",
            "A11",
            "A12"
        ],
        "op": "luminescence"
    }
]
```

--------------------------------

### Initialize and Reference a Container in Protocol

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Initialize a Protocol object and add a reference to a container with specified properties like ID, type, and storage. This is useful for setting up the initial state of your experiment.

```python
p = Protocol()
my_plate = p.ref("my_plate", id="ct1xae8jabbe6",
                        cont_type="96-pcr", storage="cold_4")
```

--------------------------------

### Define Thermocycle Gradient Temperature

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/builders.md

Example of specifying a temperature gradient using top and bottom block temperatures.

```python
temperature = {“top”: “50:celsius”, “bottom”: “45:celsius”}
```

--------------------------------

### Generate an Autoprotocol Protocol

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/index.md

Demonstrates creating a protocol object, defining a reference, adding instructions, and serializing to JSON.

```python
import json
from autoprotocol.protocol import Protocol

# instantiate a protocol object
p = Protocol()

# generate a ref
# specify where it comes from and how it should be handled when the Protocol is done
plate = p.ref("test pcr plate", id=None, cont_type="96-pcr", discard=True)

# generate seal and spin instructions that act on the ref
# some parameters are explicitly specified and others are left to vendor defaults
p.seal(
    ref=plate,
    type="foil",
    mode="thermal",
    temperature="165:celsius",
    duration="1.5:seconds"
)
p.spin(
    ref=plate,
    acceleration="1000:g",
    duration="1:minute"
)

# serialize the protocol as Autoprotocol JSON
print(json.dumps(p.as_dict(), indent=2))
```

--------------------------------

### Incubation with CO2

Source: https://context7.com/autoprotocol/autoprotocol-python/llms.txt

Incubates a container with controlled CO2 levels, suitable for cell culture applications. Shaking is disabled in this example.

```python
p.incubate(plate, "warm_37", "24:hour", shaking=False, co2=5)
```

--------------------------------

### Liquid Handle Dispense API

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Demonstrates various ways to dispense liquids using the `liquid_handle_dispense` method, including single volume, volume gradients, and multi-chip usage.

```APIDOC
## POST /autoprotocol/liquid_handle/dispense

### Description
Dispenses a specified volume of liquid from a source to a destination.

### Method
POST

### Endpoint
/autoprotocol/liquid_handle/dispense

### Parameters
#### Request Body
- **source** (Well or List[Tuple[Well, int]]) - Required - The source well or a list of source wells with intake hose information.
- **destination** (Well or List[Well]) - Required - The destination well or a list of destination wells.
- **volume** (str or List[Unit]) - Required - The volume to dispense, specified as a string with units (e.g., "5:ul") or a list of Unit objects for gradients.
- **model** (str) - Optional - The model to use for dispensing (e.g., "high_volume").
- **nozzle** (str) - Optional - The nozzle to use for dispensing (e.g., "standard").
- **chip_material** (str) - Optional - The material of the dispensing chip (e.g., "silicone", "pfe").

### Request Example
```json
{
  "source": {"container": "source_plate_id", "index": 0},
  "destination": {"container": "dest_plate_id", "index": 0},
  "volume": "5:ul"
}
```

### Response
#### Success Response (200)
- **id** (str) - The unique identifier for the dispense operation.
- **command** (str) - The command executed.
- **parameters** (dict) - The parameters used for the dispense operation.

#### Response Example
```json
{
  "id": "dispense_op_123",
  "command": "liquid_handle_dispense",
  "parameters": {
    "source": {"container": "source_plate_id", "index": 0},
    "destination": {"container": "dest_plate_id", "index": 0},
    "volume": "5:ul"
  }
}
```

### Errors
- **ValueError** – if source is not a Well or list((Well, int))
- **ValueError** – if destination and volumes are not of the same length
- **ValueError** – if model is not high_volume
- **ValueError** – if nozzle is not standard
- **ValueError** – if chip_material is not in silicone or pfe
- **TypeError** – if volume is not one of the defined allowable types
```

--------------------------------

### Incubate Instruction

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/instruction.md

The Incubate instruction stores a sample in a specific environment for a given duration, with options for shaking and CO2 levels.

```APIDOC
## Incubate Instruction

### Description
Stores a sample in a specific environment for a given duration. Once the duration has elapsed, the sample will be returned to the ambient environment until it is next used in an instruction.

### Method
POST

### Endpoint
/autoprotocol/autoprotocol-python/instructions/incubate

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **object** (Ref or str) - Required - The container to be incubated.
- **where** (Enum) - Required - Temperature at which to incubate specified container. Valid options: "ambient", "warm_37", "cold_4", "cold_20", "cold_80".
- **duration** (Unit or str) - Required - Length of time to incubate container.
- **shaking** (bool) - Optional - Specify whether or not to shake container if available at the specified temperature.
- **target_temperature** (Unit or str) - Optional - Specify a target temperature for a device (eg. an incubating block) to reach during the specified duration.
- **shaking_params** (dict) - Optional - Specify “path” and “frequency” of shaking parameters to be used with compatible devices (eg. thermoshakes).
- **co2** (Number) - Optional - Carbon dioxide percentage.

### Request Example
```json
{
  "object": "container-id",
  "where": "warm_37",
  "duration": "2:hours",
  "shaking": true,
  "target_temperature": "37:celsius",
  "shaking_params": {"path": "orbital", "frequency": "100:rpm"},
  "co2": 5
}
```

### Response
#### Success Response (200)
- **id** (str) - The unique identifier for the incubate instruction.
- **type** (str) - The type of instruction, which is 'incubate'.
- **object** (Ref) - Reference to the container being incubated.
- **where** (str) - The environment where the container is incubated.
- **duration** (Unit) - The duration of the incubation.
- **shaking** (bool) - Whether shaking was enabled.
- **target_temperature** (Unit) - The target temperature for the incubation device.
- **shaking_params** (dict) - The parameters for shaking.
- **co2** (Number) - The CO2 percentage used during incubation.

#### Response Example
```json
{
  "id": "incubate-instruction-id",
  "type": "incubate",
  "object": {"id": "container-id"},
  "where": "warm_37",
  "duration": {"value": 2, "unit": "hour"},
  "shaking": true,
  "target_temperature": {"value": 37, "unit": "celsius"},
  "shaking_params": {"path": "orbital", "frequency": {"value": 100, "unit": "rpm"}},
  "co2": 5
}
```
```

--------------------------------

### Autoprotocol SPE Instruction Output

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

This is the expected JSON output generated by the Autoprotocol library when the `spe` function is called with the example parameters.

```json
{
  "instructions": [
        {
          "op": "spe",
          "elute": [
            {
              "loading_flowrate": "100:microliter/second",
              "resource_id": "solvent_a",
              "settle_time": "2:minute",
              "volume": "2:microliter",
              "flow_pressure": "2:bar",
              "destination_well": "Elute 0/0",
              "processing_time": "3:minute"
            },
            {
              "loading_flowrate": "100:microliter/second",
              "resource_id": "solvent_a",
              "settle_time": "2:minute",
              "volume": "2:microliter",
              "flow_pressure": "2:bar",
              "destination_well": "Elute 1/0",
              "processing_time": "3:minute"
            },
            {
              "loading_flowrate": "100:microliter/second",
              "resource_id": "solvent_a",
              "settle_time": "2:minute",
              "volume": "2:microliter",
              "flow_pressure": "2:bar",
              "destination_well": "Elute 2/0",
              "processing_time": "3:minute"
            }
          ],
          "cartridge": "spe_cartridge",
          "well": "Sample/0",
          "load_sample": {
            "flow_pressure": "2:bar",
            "loading_flowrate": "1:microliter/second",
            "settle_time": "2:minute",
            "processing_time": "3:minute",
            "volume": "10:microliter"
          },
          "pressure_mode": "positive"
        }
      ]
}
```

--------------------------------

### Instantiate LiquidClass with Global Settings

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/liquid_handle.md

Use this to set a single, global liquid handling behavior across all volumes. The pump_override_volume and aspirate flowrate will be fixed regardless of the transfer volume.

```python
from autoprotocol import Unit
from autoprotocol.instruction import LiquidHandle
from autoprotocol.liquid_handle import LiquidClass

lc = LiquidClass(
    aspirate_flowrate=LiquidHandle.builders.flowrate(
        target=Unit(10, "ul/s")
    ),
    calibrated_volume=Unit(10, "uL")
)
```

--------------------------------

### Time Constraints for Scheduling

Source: https://context7.com/autoprotocol/autoprotocol-python/llms.txt

Define timing requirements between instructions for time-sensitive protocols. Constraints can specify relationships between the start or end of instructions.

```python
from autoprotocol.protocol import Protocol

p = Protocol()
plate1 = p.ref("plate1", cont_type="96-flat", discard=True)
plate2 = p.ref("plate2", cont_type="96-flat", discard=True)

# Add some instructions
p.cover(plate1)
time_point_1 = p.get_instruction_index()

p.cover(plate2)
time_point_2 = p.get_instruction_index()

# Constraint: plate1 cover must start within 1 minute of plate2 cover
p.add_time_constraint(
    from_dict={"mark": plate1, "state": "start"},
    to_dict={"mark": time_point_1, "state": "end"},
    less_than="1:minute"
)
```

--------------------------------

### Get Wells by Quadrant

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/container.md

Retrieve a group of wells corresponding to a specified quadrant of the container. Ensure the quadrant number is valid for the container type.

```python
container.quadrant(2)
```

--------------------------------

### Select dispense mode using desired_mode

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/builders.md

Demonstrates how to use desired_mode to determine the dispense mode based on the liquid class defined in transport parameters.

```python
example_transports = [
    LiquidHandle.builders.transport(
        volume=Unit(1, "uL"),
        density=None,
        pump_override_volume=Unit(2, "uL"),
        flowrate=LiquidHandle.builders.flowrate(
            target=Unit(10, "uL/s")
        ),
        delay_time=Unit(0.5, "s"),
        mode_params=LiquidHandle.builders.mode_params(
            liquid_class="air",
            position_z=LiquidHandle.builders.position_z(
                reference="preceding_position"
            )
        )
    ),
    LiquidHandle.builders.transport(
        volume=Unit(1, "uL"),
        density=None,
        pump_override_volume=Unit(2, "uL"),
        flowrate=LiquidHandle.builders.flowrate(
            target=Unit(10, "uL/s")
        ),
        delay_time=Unit(0.5, "s"),
        mode_params=LiquidHandle.builders.mode_params(
            liquid_class="viscous",
            position_z=LiquidHandle.builders.position_z(
                reference="preceding_position"
            )
        )
    )
]

LiquidHandle.builders.desired_mode(example_transports, None)
```

--------------------------------

### Instantiate LiquidHandleMethod with Blowout

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/liquid_handle.md

Instantiate `LiquidHandleMethod` with a predefined blowout behavior. This is useful for setting a global liquid handling behavior across all volumes.

```python
from autoprotocol import Unit
from autoprotocol.instruction import LiquidHandle
from autoprotocol.liquid_handle import LiquidHandleMethod

lhm = LiquidHandleMethod(
    blowout=LiquidHandle.builders.blowout(volume=Unit(10, "uL"))
)
```

--------------------------------

### Autoprotocol Sonicate Operation Output

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Example JSON output representing a sonicate operation. Note the default values for temperature and frequency if not explicitly provided.

```json
{
    "op": "sonicate",
    "wells": ["sample_plate/0", "sample_plate/1"],
    "mode": "bath",
    "duration": "1:minute",
    "temperature": "ambient",
    "frequency": "40:kilohertz"
    "mode_params": {
        "sample_holder": "suspender"
    }
}
```

--------------------------------

### Adding Instructions to a Protocol

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Shows how to add transfer and thermocycle instructions to a Protocol object.

```APIDOC
## Adding Instructions to Protocol

### Description
Demonstrates adding common instructions like `transfer` and `thermocycle` to an existing Protocol object.

### Method
`p.transfer(source, dest, volume)`
`p.thermocycle(container, groups)`

### Endpoint
N/A (Method calls on Protocol object)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
p.transfer(source=my_plate.well("A1"),
            dest=my_plate.well("B4"),
            volume="50:microliter")
p.thermocycle(my_plate, groups=[
              { "cycles": 1,
                "steps": [
                  { "temperature": "95:celsius",
                    "duration": "1:hour"
                  }]
              }])
```

### Response
#### Success Response (200)
N/A (Method execution)

#### Response Example
N/A
```

--------------------------------

### Dispense with Custom Parameters

Source: https://context7.com/autoprotocol/autoprotocol-python/llms.txt

Performs dispensing with advanced parameters such as step size, flow rate, and pre-dispense volume. These parameters allow fine-tuning of the dispensing process.

```python
p.dispense(
    plate,
    "water",
    [{"column": 0, "volume": "100:microliter"}],
    step_size="5:microliter",
    flowrate="10:microliter/second",
    pre_dispense="10:microliter"
)
```

--------------------------------

### Autoprotocol JSON Output for Acoustic Transfer

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

This is an example of the JSON output generated by Autoprotocol for an acoustic transfer operation. It details the transfers, droplet size, and operation type.

```json
{
    "instructions": [
        {
            "groups": [
                {
                    "transfer": [
                        {
                            "volume": "0.004:microliter",
                            "to": "plate/0",
                            "from": "echo_plate/0"
                        },
                        {
                            "volume": "0.004:microliter",
                            "to": "plate/1",
                            "from": "echo_plate/0"
                        },
                        {
                            "volume": "0.004:microliter",
                            "to": "plate/2",
                            "from": "echo_plate/0"
                        },
                        {
                            "volume": "0.004:microliter",
                            "to": "plate/3",
                            "from": "echo_plate/1"
                        },
                        {
                            "volume": "0.004:microliter",
                            "to": "plate/4",
                            "from": "echo_plate/1"
                        }
                    ]
                }
            ],
            "droplet_size": "25:microliter",
            "op": "acoustic_transfer"
        }
    ]
}

```

--------------------------------

### Autoprotocol JSON Output Example

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

This JSON represents the output generated by the Autoprotocol library, detailing container references and a sequence of instructions including pipetting and thermocycling operations.

```json
{
  "refs": {
    "my_plate": {
      "id": "ct1xae8jabbe6",
      "store": {
        "where": "cold_4"
      }
    }
  },
  "instructions": [
    {
      "groups": [
        {
          "transfer": [
            {
              "volume": "50.0:microliter",
              "to": "my_plate/15",
              "from": "my_plate/0"
            }
          ]
        }
      ],
      "op": "pipette"
    },
    {
      "volume": "10:microliter",
      "dataref": null,
      "object": "my_plate",
      "groups": [
        {
          "cycles": 1,
          "steps": [
            {
              "duration": "1:hour",
              "temperature": "95:celsius"
            }
          ]
        }
      ],
      "op": "thermocycle"
    }
  ]
}
```

--------------------------------

### Submit Samples for Sequencing

Source: https://context7.com/autoprotocol/autoprotocol-python/llms.txt

Execute Sanger or Illumina sequencing protocols on prepared samples.

```python
from autoprotocol.protocol import Protocol

p = Protocol()
seq_plate = p.ref("seq_samples", cont_type="96-flat", discard=True)

# Sanger sequencing
p.sangerseq(
    seq_plate,
    wells=seq_plate.wells_from(0, 8).indices(),
    dataref="sanger_results",
    type="standard"
)

# Illumina sequencing
sample_wells = p.ref("illumina_samples", cont_type="96-pcr", discard=True).wells_from(0, 8)
for well in sample_wells:
    well.set_volume("20:microliter")

p.illuminaseq(
    flowcell="PE",
    lanes=[
        {"object": sample_wells[0], "library_concentration": 1.0},
        {"object": sample_wells[1], "library_concentration": 2.5},
        {"object": sample_wells[2], "library_concentration": 3.0},
        {"object": sample_wells[3], "library_concentration": 4.0}
    ],
    sequencer="hiseq",
    mode="rapid",
    index="dual",
    library_size=300,
    dataref="illumina_results"
)
```

--------------------------------

### Static Default Position Methods

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/liquid_handle.md

Provides static methods to get default Z-axis positions for liquid level detection, tracking, well bottom, and well top.

```APIDOC
## *static* default_lld_position_z(liquid: [LiquidClass](#autoprotocol.liquid_handle.liquid_class.LiquidClass))

Default lld position_z

* **Returns:**
  position_z for sensing the liquid surface
* **Return type:**
  dict

## *static* default_tracked_position_z()

Default tracked position_z

* **Returns:**
  position_z for tracking the liquid surface
* **Return type:**
  dict

## *static* default_well_bottom_position_z()

Default well bottom position_z

* **Returns:**
  position_z for the well bottom
* **Return type:**
  dict

## *static* default_well_top_position_z()

Default well top position_z

* **Returns:**
  position_z for the well top
* **Return type:**
  dict
```

--------------------------------

### Default Behavior Methods

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/liquid_handle.md

Provides default parameters for various liquid handling steps like blowout, mixing, priming, and transit.

```APIDOC
## default_blowout(volume)

Default blowout behavior

* **Parameters:**
  **volume** ([*Unit*](autoprotocol.md#autoprotocol.unit.Unit))
* **Returns:**
  blowout_params
* **Return type:**
  dict

## default_mix_before(volume: [Unit](autoprotocol.md#autoprotocol.unit.Unit))

Default mix_before parameters

* **Parameters:**
  **volume** ([*Unit*](autoprotocol.md#autoprotocol.unit.Unit))
* **Returns:**
  mix_before params
* **Return type:**
  dict

## default_aspirate_z(volume: [Unit](autoprotocol.md#autoprotocol.unit.Unit))

Default aspirate_z parameters

* **Parameters:**
  **volume** ([*Unit*](autoprotocol.md#autoprotocol.unit.Unit))
* **Returns:**
  aspirate position_z
* **Return type:**
  dict

## default_prime(volume: [Unit](autoprotocol.md#autoprotocol.unit.Unit))

Default prime volume

* **Parameters:**
  **volume** ([*Unit*](autoprotocol.md#autoprotocol.unit.Unit))
* **Returns:**
  priming volume
* **Return type:**
  [Unit](autoprotocol.md#autoprotocol.unit.Unit)

## default_transit(volume: [Unit](autoprotocol.md#autoprotocol.unit.Unit))

Default transit volume

* **Parameters:**
  **volume** ([*Unit*](autoprotocol.md#autoprotocol.unit.Unit))
* **Returns:**
  transit volume
* **Return type:**
  [Unit](autoprotocol.md#autoprotocol.unit.Unit)

## default_dispense_z(volume: [Unit](autoprotocol.md#autoprotocol.unit.Unit))

Default aspirate_z parameters

* **Parameters:**
  **volume** ([*Unit*](autoprotocol.md#autoprotocol.unit.Unit))
* **Returns:**
  dispense position_z
* **Return type:**
  dict

## default_mix_after(volume: [Unit](autoprotocol.md#autoprotocol.unit.Unit))

Default mix_after parameters

* **Parameters:**
  **volume** ([*Unit*](autoprotocol.md#autoprotocol.unit.Unit))
* **Returns:**
  mix_after params
* **Return type:**
  dict
```

--------------------------------

### Standard PCR Thermocycle Protocol

Source: https://context7.com/autoprotocol/autoprotocol-python/llms.txt

Configures a standard PCR thermocycling protocol including initial denaturation, cycling, final extension, and hold steps. Ensure the plate is sealed before starting.

```python
p.thermocycle(
    pcr_plate,
    groups=[
        # Initial denaturation
        {"cycles": 1, "steps": [
            {"temperature": "95:celsius", "duration": "5:minute"}
        ]},
        # Main cycling
        {"cycles": 30, "steps": [
            {"temperature": "95:celsius", "duration": "30:second"},
            {"temperature": "56:celsius", "duration": "20:second"},
            {"temperature": "72:celsius", "duration": "30:second"}
        ]},
        # Final extension
        {"cycles": 1, "steps": [
            {"temperature": "72:celsius", "duration": "10:minute"}
        ]},
        # Hold
        {"cycles": 1, "steps": [
            {"temperature": "4:celsius", "duration": "30:second"}
        ]}
    ],
    lid_temperature="97:celsius"
)
```

--------------------------------

### Perform magnetic bead mixing

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

Demonstrates how to use mag_mix to cycle tips in a container for bead mixing.

```python
p = Protocol()
plate = p.ref("plate_0", None, "96-pcr", storage="cold_20")

p.mag_mix("96-pcr", plate, "30:second", "60:hertz", center=0.75,
          amplitude=0.25, magnetize=True, temperature=None,
          new_tip=False, new_instruction=False)
```

```none
"instructions": [
    {
        "groups": [
            [
                {
                    "mix": {
                        "center": 0.75,
                        "object": "plate_0",
                        "frequency": "2:hertz",
                        "amplitude": 0.25,
                        "duration": "30:second",
                        "magnetize": true,
                        "temperature": null
                    }
                }
            ]
        ],
        "magnetic_head": "96-pcr",
        "op": "magnetic_transfer"
    }
]
```

--------------------------------

### SpectrophotometryBuilders Methods

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/builders.md

Methods for constructing parameters for Spectrophotometry instructions.

```APIDOC
## SpectrophotometryBuilders

### wavelength_selection
- **shortpass** (Unit/str) - Optional - Shortpass filter
- **longpass** (Unit/str) - Optional - Longpass filter
- **ideal** (Unit/str) - Optional - Ideal wavelength

### groups
- **groups** (list) - Required - List of spectrophotometry group dictionaries

### group
- **mode** (str) - Required - Spectrophotometry mode
- **mode_params** (dict) - Required - Parameters for the specified mode
```

--------------------------------

### Autoprotocol Dispense JSON Output

Source: https://github.com/autoprotocol/autoprotocol-python/blob/master/docs/protocol.md

This is the expected JSON output for the dispense operations defined in the Python examples. It shows the structure of the dispense instructions, including reagent, object, columns, nozzle position, and shape.

```json
"instructions": [
    {
        "reagent": "water",
        "object": "sample_plate",
        "columns": [
            {
                "column": 0,
                "volume": "10:microliter"
            },
            {
                "column": 1,
                "volume": "20:microliter"
            },
            {
                "column": 2,
                "volume": "30:microliter"
            },
            {
                "column": 3,
                "volume": "40:microliter"
            },
            {
                "column": 4,
                "volume": "50:microliter"
            }
        ],
        "op": "dispense"
    },
    {
        "reagent": "water",
        "object": "sample_plate",
        "columns": [
            {
                "column": 0,
                "volume": "10:microliter"
            }
        ],
        "nozzle_position" : {
            "position_x" : "1:millimeter",
            "position_y" : "2:millimeter",
            "position_z" : "20:millimeter"
        },
        "shape" : {
            "rows" : 8,
            "columns" : 1,
            "format" : "SBS96"
        }
        "op": "dispense"
    },
]
```