> For the complete documentation index, see [llms.txt](https://www.opal-rt.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.opal-rt.com/docs/hypersim/library-blocks-reference/network-machines/synchronous-machine-cross-compound.md).

# Synchronous Machine (Cross-Compound)

## Description

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-445f9ad21b8d6db6cd48fbd756c2ba8182259181%2Fimage%20(343).png?alt=media" alt=""><figcaption></figcaption></figure>

The **Synchronous Machine (Cross-Compound)** block, located in the **Network Machines** library, models cross-compound thermal turbine generator with two generating units (primary and secondary)\
and only one boiler.

In this model, **only the speed regulator can be modelled externally** with the control system interface\
(CSI).

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-33d990ba5113900b30306e5dafc4ee0e9bd92573%2Fimage%20(338).png?alt=media" alt=""><figcaption><p>Schematic diagram of a cross-compound turbine generator</p></figcaption></figure>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-cf8b508c4774234e53de7612d15694b0a63c463c%2Fimage%20(331).png?alt=media" alt=""><figcaption><p><strong>Direct axis diagram</strong></p></figcaption></figure>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-c47f1ddc241a06b174cef553e83e178a9a06e162%2Fimage%20(332).png?alt=media" alt=""><figcaption><p><strong>Quadrature axis diagram</strong></p></figcaption></figure>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-7f2d2d16aceb9260d380390f39409778de95aeb6%2Fimage%20(333).png?alt=media" alt=""><figcaption><p><strong>Saturation diagram</strong></p></figcaption></figure>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-8f8b7243f201ec4d4913a6b2a3034b4e02a0f678%2Fimage%20(334).png?alt=media" alt=""><figcaption><p><strong>Exciter diagram</strong></p></figcaption></figure>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-fc0028c46ca72e9c5ef0b5cd58b92660c8021e17%2Fimage%20(335).png?alt=media" alt=""><figcaption><p><strong>Stabilizer diagram</strong></p></figcaption></figure>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-f34db040d09e8fdb88305740f106c3ebff2d9314%2Fjfx15578987201059946025.png?alt=media" alt="" width="492"><figcaption><p>Steam turbine diagram</p></figcaption></figure>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-9fdab564319f8f0d813f9899ddc085393d65841f%2Fjfx9175028118719199437.png?alt=media" alt=""><figcaption><p>Speed regulator diagram</p></figcaption></figure>

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-c6aebe2c0457f89594f616d36297819d17ffe46c%2Fjfx11717949838233212943.png?alt=media" alt=""><figcaption><p>Boiler diagram</p></figcaption></figure>

The model of the thermal turbine generator has two shafts, each with either one or five masses.\
In addition, the cross-compound turbine generator model allows the application of a mechanical\
torque to each turbine mass. Since the masses are hard-coded, shaft models with a mass number\
other than 1 or 5 will be simulated by setting the inertia of non-existent masses to very small values and the rigidity factors adjacent to the shafts to a very high value.

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-abda48d088f5bfe67f00cfb8dd9e68e67cfd9a69%2Fjfx14276406248500315234.png?alt=media" alt=""><figcaption><p>Shaft diagram</p></figcaption></figure>

The block participates in load flow by using the network steady-state solution to initialize machine parameters.

## Mask parameters

<figure><img src="https://3623212549-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLxgTpoh7kyPmQ5vuyqD7%2Fuploads%2Fgit-blob-817276f8ea5390e7e93c186017848f66766c7eb4%2Fcross-copound.jpg?alt=media" alt=""><figcaption></figcaption></figure>

{% tabs %}
{% tab title="General" %}

<table><thead><tr><th width="217">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Free-form description of the component.</td></tr><tr><td><strong>Nominal electrical power of generator</strong></td><td>Base nominal electrical power of the three-phase generator (MVA) for the Primary and secondary</td></tr><tr><td><strong>Nominal mechanical power of turbine</strong></td><td>Base nominal mechanical power of the turbine(MW) for the Primary and secondary</td></tr><tr><td><strong>Voltage (rms LL)</strong></td><td>Base line-to-line RMS voltage (kV) for the Primary and secondary</td></tr><tr><td><strong>Angular frequency</strong></td><td>Base angular frequency (rad/s) for the Primary and secondary</td></tr><tr><td><strong>Voltage</strong></td><td>Voltage reference (pu) for the Primary and secondary</td></tr><tr><td><strong>Power filter</strong></td><td>Power reference filter time constant (s) for the Primary and secondary</td></tr><tr><td><strong>Speed</strong></td><td>Speed reference (pu) for the Primary and secondary</td></tr><tr><td><strong>Voltage reference selection</strong></td><td>Select voltage reference: Vref or Vref = Vt for the Primary and secondary</td></tr><tr><td><strong>Active power</strong></td><td>Active power reference (MW) for the primary</td></tr><tr><td><strong>Reactive power</strong></td><td>Reactive power reference (only if Vref = Vt) (Mvar) for the Primary and secondary</td></tr></tbody></table>
{% endtab %}

{% tab title="Axes" %}

<table><thead><tr><th width="200">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Xd</strong></td><td>Direct-axis synchronous reactance (pu) for the primary and secondary</td></tr><tr><td><strong>X’d</strong></td><td>Direct-axis transient reactance (pu) for the Primary and secondary</td></tr><tr><td><strong>X’’d</strong></td><td>Direct-axis sub-transient reactance (pu) for the Primary and secondary</td></tr><tr><td><strong>T’do</strong></td><td>Direct-axis transient time constant (s) for the Primary and secondary</td></tr><tr><td><strong>T’’do</strong></td><td>Direct-axis sub-transient time constant (s) for the Primary and secondary</td></tr><tr><td><strong>Xq</strong></td><td>Quadrature-axis synchronous reactance (pu) for the Primary and secondary</td></tr><tr><td><strong>X’q</strong></td><td>Quadrature-axis transient reactance (pu) for the Primary and secondary</td></tr><tr><td><strong>X’’q</strong></td><td>Quadrature-axis sub-transient reactance (pu) for the Primary and secondary</td></tr><tr><td><strong>T’q</strong></td><td>Quadrature-axis transient time constant(s) for the Primary and secondary</td></tr><tr><td><strong>T’’q</strong></td><td>Quadrature-axis sub-transient time constant(s) for the Primary and secondary</td></tr></tbody></table>
{% endtab %}

{% tab title="Exciter" %}

<table><thead><tr><th width="200">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Modelling of excitation circuit</strong></td><td>Select internal or external (input pins) excitation model.</td></tr><tr><td><strong>Kp</strong></td><td>Excitation proportional gain on voltage limit for the primary and secondary</td></tr><tr><td><strong>Tr</strong></td><td>Voltage measurement time constant (s) for the primary and secondary</td></tr><tr><td><strong>Ka</strong></td><td>Voltage regulator gain for the primary and secondary</td></tr><tr><td><strong>Ta</strong></td><td>Voltage regulator time constant (s) for the primary and secondary</td></tr><tr><td><strong>Kf</strong></td><td>Damping filter feedback gain for the primary and secondary</td></tr><tr><td><strong>Tf</strong></td><td>Exciter damping filter feedback time constant (s) for the primary and secondary</td></tr><tr><td><strong>ex_Efdfix</strong></td><td>Constant excitation voltage (pu) for the primary and secondary</td></tr><tr><td><strong>ex_Vtmin</strong></td><td>Minimum static limit of voltage measurement (pu) for the primary and secondary</td></tr><tr><td><strong>ex_Vtmax</strong></td><td>Maximum static limit of voltage measurement (pu) for the primary and secondary</td></tr><tr><td><strong>ex_Vrmin</strong></td><td>Minimum static limit of excitation voltage (pu) for the primary and secondary</td></tr><tr><td><strong>ex_Vrmax</strong></td><td>Maximum static limit of excitation voltage (pu) for the primary and secondary</td></tr></tbody></table>
{% endtab %}

{% tab title="Stabilizer" %}

<table><thead><tr><th width="200">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Modelling of stabilizer circuit</strong></td><td>Select internal or external (input pins) stabilizer model.</td></tr><tr><td><strong>Kap</strong></td><td>Gain on electric power for the primary and secondary</td></tr><tr><td><strong>Kag</strong></td><td>Gain on gate opening for the primary and secondary</td></tr><tr><td><strong>Tap</strong></td><td>Time constant on electric power (s) for the primary and secondary</td></tr><tr><td><strong>Tag</strong></td><td>Time constant on gate opening (s) for the primary and secondary</td></tr><tr><td><strong>Ks</strong></td><td>Stabilizer gain for the primary and secondary</td></tr><tr><td><strong>Vsmin</strong></td><td>Minimum stabilizer voltage limit (pu) for the primary and secondary</td></tr><tr><td><strong>Vsmax</strong></td><td>Maximum stabilizer voltage limit (pu) for the primary and secondary</td></tr><tr><td><strong>Tw1</strong></td><td>Gate opening time constant 1 (s) for the primary and secondary</td></tr><tr><td><strong>Tw2</strong></td><td>Gate opening time constant 2 (s) for the primary and secondary</td></tr><tr><td><strong>T1</strong></td><td>Stabilizer time constant 1 (s) for the primary and secondary</td></tr><tr><td><strong>T2</strong></td><td>Stabilizer time constant 2 (s) for the primary and secondary</td></tr><tr><td><strong>T3</strong></td><td>Stabilizer time constant 3 (s) for the primary and secondary</td></tr><tr><td><strong>T4</strong></td><td>Stabilizer time constant 4 (s) for the primary and secondary</td></tr><tr><td><strong>T5</strong></td><td>Stabilizer time constant 5 (s) for the primary and secondary</td></tr><tr><td><strong>T6</strong></td><td>Stabilizer time constant 6 (s) for the primary and secondary</td></tr></tbody></table>
{% endtab %}

{% tab title="Turbine/Speed/Boiler" %}

<table><thead><tr><th width="242">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Steam turbine</strong></td><td>Select internal or external (input pins) model.</td></tr><tr><td><strong>Speed regulator</strong></td><td>Select internal or external (input pins) model.</td></tr><tr><td><strong>Boiler</strong></td><td>Select internal or external (input pins) model.</td></tr><tr><td><strong>K1</strong></td><td>(pu)</td></tr><tr><td><strong>K2</strong></td><td>(pu)</td></tr><tr><td><strong>K3</strong></td><td>(pu)</td></tr><tr><td><strong>K4</strong></td><td>(pu)</td></tr><tr><td><strong>K5</strong></td><td>(pu)</td></tr><tr><td><strong>K6</strong></td><td>(pu)</td></tr><tr><td><strong>t1</strong></td><td>(s)</td></tr><tr><td><strong>t2</strong></td><td>(s)</td></tr><tr><td><strong>t3</strong></td><td>(s)</td></tr><tr><td><strong>t4</strong></td><td>(s)</td></tr><tr><td><strong>r</strong></td><td>(pu)</td></tr><tr><td><strong>ahlim</strong></td><td>(pu)</td></tr><tr><td><strong>wsensor</strong></td><td></td></tr><tr><td><strong>kff</strong></td><td>(pu)</td></tr><tr><td><strong>pah1</strong></td><td>(pu)</td></tr><tr><td><strong>pah2</strong></td><td>(pu)</td></tr><tr><td><strong>db</strong></td><td>(pu)</td></tr><tr><td><strong>tsr</strong></td><td>(s)</td></tr><tr><td><strong>tcv</strong></td><td>(s)</td></tr><tr><td><strong>wfil</strong></td><td>(s)</td></tr><tr><td><strong>k2</strong></td><td>(pu)</td></tr><tr><td><strong>k3</strong></td><td>(pu)</td></tr><tr><td><strong>k4</strong></td><td>(pu)</td></tr><tr><td><strong>ki</strong></td><td>(pu)</td></tr><tr><td><strong>kpc</strong></td><td>(pu)</td></tr><tr><td><strong>bmax</strong></td><td>(pu)</td></tr><tr><td><strong>press</strong></td><td>(pu)</td></tr><tr><td><strong>td</strong></td><td>(s)</td></tr><tr><td><strong>t8</strong></td><td>(s)</td></tr><tr><td><strong>t9</strong></td><td>(s)</td></tr></tbody></table>
{% endtab %}

{% tab title="Mechanical torque/ Shaft" %}

<table><thead><tr><th width="242">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Modelling of shaft</strong></td><td>Select internal or external (input pins) model.</td></tr><tr><td><strong>Primary number of masses on the shaft</strong></td><td>Number of masses</td></tr><tr><td><strong>Secondary number of masses on the shaft</strong></td><td>Number of masses</td></tr><tr><td><strong>Tmec1</strong></td><td>Torque applied on primary shaft</td></tr><tr><td><strong>Tmec2</strong></td><td>Torque applied on secondary shaft</td></tr><tr><td><strong>Tmec3</strong></td><td>Torque applied on primary shaft</td></tr><tr><td><strong>Tmec4</strong></td><td>Torque applied on secondary shaft</td></tr><tr><td><strong>Tmec5</strong></td><td>Torque applied on primary shaft</td></tr><tr><td><strong>Tmec6</strong></td><td>Torque applied on secondary shaft</td></tr><tr><td><strong>Tmec7</strong></td><td>Torque applied on primary shaft</td></tr><tr><td><strong>Tmec8</strong></td><td>Torque applied on secondary shaft</td></tr><tr><td><strong>tgo</strong></td><td>Torque of mechanical losses of the shaft (pu) for the primary and secondary</td></tr><tr><td><strong>d1Start</strong></td><td>(pu) for the primary and secondary</td></tr><tr><td><strong>tStart</strong></td><td>(s) for the primary and secondary</td></tr><tr><td><strong>h1</strong></td><td>(s) for the primary and secondary</td></tr><tr><td><strong>h2</strong></td><td>(s) for the primary and secondary</td></tr><tr><td><strong>h3</strong></td><td>(s) for the primary and secondary</td></tr><tr><td><strong>h4</strong></td><td>(s) for the primary and secondary</td></tr><tr><td><strong>h5</strong></td><td>(s) for the primary and secondary</td></tr><tr><td><strong>k12</strong></td><td>(pu/rad) for the primary and secondary</td></tr><tr><td><strong>k23</strong></td><td>(pu/rad) for the primary and secondary</td></tr><tr><td><strong>k34</strong></td><td>(pu/rad) for the primary and secondary</td></tr><tr><td><strong>k45</strong></td><td>(pu/rad) for the primary and secondary</td></tr><tr><td><strong>d1</strong></td><td>(pu) for the primary and secondary</td></tr><tr><td><strong>d2</strong></td><td>(pu) for the primary and secondary</td></tr><tr><td><strong>d3</strong></td><td>(pu) for the primary and secondary</td></tr><tr><td><strong>d4</strong></td><td>(pu) for the primary and secondary</td></tr><tr><td><strong>d5</strong></td><td>(pu) for the primary and secondary</td></tr></tbody></table>
{% endtab %}

{% tab title="Load Flow" %}

<table><thead><tr><th width="242">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Type of bus</strong></td><td>Bus type: Swing, PV, or PQ for the primary and secondary</td></tr><tr><td><strong>Voltage</strong></td><td>Bus voltage magnitude (pu) for the primary and secondary</td></tr><tr><td><strong>Angle</strong></td><td>Bus voltage angle (degree) for the primary and secondary</td></tr><tr><td><strong>Reactive power minimum</strong></td><td>Minimum reactive power (Mvar) for the primary and secondary</td></tr><tr><td><strong>Reactive power maximum</strong></td><td>Maximum reactive power (Mvar) for the primary and secondary</td></tr><tr><td><strong>Active power</strong></td><td>Active power (MW) for the primary and secondary</td></tr><tr><td><strong>Reactive power</strong></td><td>Reactive power (Mvar) for the primary and secondary</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

## Conserving ports

| Input | Description |
| ----- | ----------- |
|       |             |

## Inputs

| Input | Description |
| ----- | ----------- |
|       |             |

## Outputs

This block has no outputs.

## Signals available for monitoring and external I/O connections (via sensors form)

All block inputs and outputs are available as signals for monitoring and for external I/O connections.

Additional signals are also available and are listed below with their descriptions.

<table><thead><tr><th width="206">Signal</th><th>Description</th></tr></thead><tbody><tr><td><strong>Ed</strong></td><td>D-axis voltage in front of an external reactance (Xext) (pu)</td></tr><tr><td><strong>Ed_Sec</strong></td><td>(pu)</td></tr><tr><td><strong>Edreg</strong></td><td>D-axis field voltage (pu)</td></tr><tr><td><strong>Efd</strong></td><td>(pu)</td></tr><tr><td><strong>Efd_Sec</strong></td><td>(pu)</td></tr><tr><td><strong>Eq</strong></td><td>Q-axis voltage in front of an external reactance (Xext) (pu)</td></tr><tr><td><strong>Eq_Sec</strong></td><td>(pu)</td></tr><tr><td><strong>Eqreg</strong></td><td>Q-axis field voltage (pu)</td></tr><tr><td><strong>Ia</strong></td><td>Generator phase A current (A)</td></tr><tr><td><strong>Ia_Seq</strong></td><td>(A)</td></tr><tr><td><strong>Ib</strong></td><td>Generator phase B current (A)</td></tr><tr><td><strong>Ib_Seq</strong></td><td>(A)</td></tr><tr><td><strong>Ic</strong></td><td>Generator phase C current (A)</td></tr><tr><td><strong>Ic_Seq</strong></td><td>(A)</td></tr><tr><td><strong>Id</strong></td><td>D-axis current (pu)</td></tr><tr><td><strong>ld_Sec</strong></td><td>(pu)</td></tr><tr><td><strong>Ifd</strong></td><td>Field current (pu)</td></tr><tr><td><strong>Ifd_Sec</strong></td><td>(pu)</td></tr><tr><td><strong>Iq</strong></td><td>Q-axis current (pu)</td></tr><tr><td><strong>Iq_Sec</strong></td><td>(pu)</td></tr><tr><td><strong>Pe</strong></td><td>Active power (pu/MVA)</td></tr><tr><td><strong>Pe_Sec</strong></td><td>(pu/MVA)</td></tr><tr><td><strong>Pef</strong></td><td>Filtered measured electrical power (pu/MVA)</td></tr><tr><td><strong>Pef_Sec</strong></td><td>(pu/MVA)</td></tr><tr><td><strong>Pm</strong></td><td>Turbine mechanical power (pu/MW)</td></tr><tr><td><strong>Pm_Sec</strong></td><td>(pu/MVA)</td></tr><tr><td><strong>Qe</strong></td><td>Reactive power (pu/MVA)</td></tr><tr><td><strong>Qe_Sec</strong></td><td>(pu/MVA)</td></tr><tr><td><strong>T12, T23, ..,T910</strong></td><td>(pu/MW*s)</td></tr><tr><td><strong>T12_Seq, T23_Seq, ..,T910_Seq</strong></td><td>(pu/MW*s)</td></tr><tr><td><strong>Te</strong></td><td>Electrical torque (pu/MW*s)</td></tr><tr><td><strong>Te_Seq</strong></td><td>(pu/MW*s)</td></tr><tr><td><strong>Tmec, ..Tmec8</strong></td><td>(pu/MW*s)</td></tr><tr><td><strong>Va</strong></td><td>Power system phase A voltage (V)</td></tr><tr><td><strong>Va_Sec</strong></td><td>(V)</td></tr><tr><td><strong>Vb</strong></td><td>Power system phase B voltage (V)</td></tr><tr><td><strong>Vb_Seq</strong></td><td>(V)</td></tr><tr><td><strong>Vc</strong></td><td>Power system phase C voltage (V)</td></tr><tr><td><strong>Vc_Seq</strong></td><td>(V)</td></tr><tr><td><strong>Vstab</strong></td><td>Stabilizer output voltage (pu)</td></tr><tr><td><strong>Vstab_Seq</strong></td><td>(pu)</td></tr><tr><td><strong>Vt</strong></td><td>Terminal voltage (pu)</td></tr><tr><td><strong>Vt_Seq</strong></td><td>(pu)</td></tr><tr><td><strong>Vtd</strong></td><td>D-axis terminal voltage (pu)</td></tr><tr><td><strong>Vtd_Seq</strong></td><td>(pu)</td></tr><tr><td><strong>Vtq</strong></td><td>Q-axis terminal voltage (pu)</td></tr><tr><td><strong>Vtq_Seq</strong></td><td>(pu)</td></tr><tr><td><strong>mhuh</strong></td><td>(pu)</td></tr><tr><td><strong>psih</strong></td><td>(pu)</td></tr><tr><td><strong>w</strong></td><td>Angular speed (pu)</td></tr><tr><td><strong>w2, w3, w10</strong></td><td>(pu)</td></tr><tr><td><strong>w2_Seq, w3_Seq, w10_Seq</strong></td><td>(pu)</td></tr><tr><td><strong>w_Seq</strong></td><td>(pu)</td></tr><tr><td><strong>x</strong></td><td>Gate opening (pu)</td></tr><tr><td><strong>x_i</strong></td><td>(pu)</td></tr></tbody></table>


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://www.opal-rt.com/docs/hypersim/library-blocks-reference/network-machines/synchronous-machine-cross-compound.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
