> For the complete documentation index, see [llms.txt](https://swarm-in-blocks.gitbook.io/swarm-in-blocks/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://swarm-in-blocks.gitbook.io/swarm-in-blocks/usability/python-api/basic-swarm-operations.md).

# Basic swarm operations

<table><thead><tr><th width="150" align="center">Function</th><th align="center">Description</th></tr></thead><tbody><tr><td align="center"><a href="#swarm.takeoffall-z-1">takeOffAll</a></td><td align="center">All drones take off simultaneously</td></tr><tr><td align="center"><a href="#swarm.landall">landAll</a></td><td align="center">All drones land in the current position</td></tr><tr><td align="center"><a href="#swarm.returntohome">returnToHome</a></td><td align="center">All drones return to their initial formation coordinates</td></tr><tr><td align="center"><a href="#swarm.returnandland">returnAndLand</a></td><td align="center">All drones return to their initial formation coordinates and land there</td></tr><tr><td align="center"><a href="#swarm.applyformation-speed-1-tolerance-0.2-wait-true">applyFormation</a></td><td align="center">Applies the selected formation or operation</td></tr><tr><td align="center"><a href="#swarm.plotpreview-plot_type-2d">plotPreview</a></td><td align="center">Open a window with a preview of the selected formation or operation</td></tr></tbody></table>

#### `Swarm.takeOffAll(`*`z=1`*`)`

* <mark style="color:green;">Parameters:</mark>
  * `z: int or float`\
    Set the height of the swarm
* <mark style="color:red;">Result:</mark>\
  All drones takeoff at the same time and go up to the selected height.

#### `Swarm.landAll()`

* <mark style="color:green;">Parameters:</mark>
  * None
* <mark style="color:red;">Result:</mark>\
  All the armed clovers go down to the floor in their current position and disarm themselves.

#### `Swarm.returnToHome()`

* <mark style="color:green;">Parameters:</mark>
  * None
* <mark style="color:red;">Result:</mark>\
  All the drones return to the initial formation they started operating.

#### `Swarm.returnAndLand()`

* <mark style="color:green;">Parameters:</mark>
  * None
* <mark style="color:red;">Result:</mark>\
  Very similar to the `returnToHome` function, but the drones also land and disarm.

#### `Swarm.applyFormation(`*`speed=1, tolerance=0.2, wait=True`*`)`

* <mark style="color:green;">Parameters:</mark>
  * `speed: int or float, optional`\
    Set the speed of the drones' movement
  * `tolerance: int or float, optional`\
    Set the tolerance of the `navigateWait` function
  * `wait: bool, optional`\
    While *'True'* uses the `navigateWait` module and the drones will wait for the conclusion of previous operations before applying the current desired formation
* <mark style="color:red;">Result:</mark>\
  Applies the previously selected formation or operation and the clovers start to move in order to form it.

{% hint style="warning" %}
All the operations involved in this section already apply the formation for the user, but all the more complex functions must be followed by the applyFormation command or the desired coordinates will not be executed.
{% endhint %}

#### `Swarm.plotPreview(`*`plot_type='2D'`*`)`

* <mark style="color:green;">Parameters:</mark>
  * `plot_type: string`\
    Defines if the plot will be *'2D'* or *'3D'*
* <mark style="color:red;">Result:</mark>
  * A [Swarm Preview](/swarm-in-blocks/background-theory/systems/swarm-preview.md) window will appear on the screen showing how the drones are or where they will go after applying the formation. It will also allow accessing the movement history of the drones.

{% hint style="info" %}
It's highly recommended to use the `plotPreview` feature before applying the formations in simulation or real life, to make sure that the expected behavior will confirm.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://swarm-in-blocks.gitbook.io/swarm-in-blocks/usability/python-api/basic-swarm-operations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.