# cosine_pulse_pwc

Source: https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Graph/signals/cosine_pulse_pwc

```python
signals.cosine_pulse_pwc(duration, segment_count, amplitude, drag=None, start_time=0.0, end_time=None, flat_duration=None, segmentation=SegmentationType.UNIFORM, *, name=None)
```

Create a Pwc representing a cosine pulse.

### Parameters
* **duration** (*float*) – The duration of the signal, $T$.
* **segment_count** (*int*) – The number of segments in the PWC.
  Must be at least six.
* **amplitude** (*float* *or* *complex* *or* [*Tensor*](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Tensor.md#boulderopal.graph.Tensor)) – The amplitude of the pulse, $A$.
  It must either be a scalar or contain a single element.
* **drag** (*float* *or* [*Tensor*](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Tensor.md#boulderopal.graph.Tensor) *or* *None* *,* *optional*) – The DRAG parameter, $\beta$.
  If passed, it must either be a scalar or contain a single element.
  Defaults to no DRAG correction.
* **start_time** (*float* *,* *optional*) – The time at which the cosine pulse starts, $t_\mathrm{start}$.
  Defaults to 0.
* **end_time** (*float* *or* *None* *,* *optional*) – The time at which the cosine pulse ends, $t_\mathrm{end}$.
  Defaults to the given duration $T$.
* **flat_duration** (*float* *or* *None* *,* *optional*) – The amount of time to remain constant after the peak of the cosine,
  $t_\mathrm{flat}$.
  If passed, it must be positive and less than the difference between end_time and
  start_time.
  Defaults to None, in which case no constant part is added to the cosine pulse.
* **segmentation** ([`SegmentationType`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Graph/signals/SegmentationType.md#boulderopal.graph.signals.SegmentationType)) – The type of segmentation for the signal.
  With a “MINIMAL” segmentation, most of the segments are placed in the
  non-constant parts of the signal.
  Defaults to “UNIFORM”, in which case the segments are uniformly
  distributed along the signal’s duration.
* **name** (*str* *or* *None* *,* *optional*) – The name of the node.
### Returns
The sampled cosine pulse.
If no flat duration is passed then the pulse is evenly sampled between $0$ and
$T$. If one is passed, the flat part of the pulse is described by one or two
segments (depending on the value of segment_count), and the rest of the pulse is
sampled with the remaining segments.
### Return type
[Pwc](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Pwc.md#boulderopal.graph.Pwc)

### SEE ALSO
[`boulderopal.signals.cosine_pulse`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/signals/cosine_pulse.md#boulderopal.signals.cosine_pulse)
: Create a Signal object representing a cosine pulse.

[`Graph.signals.gaussian_pulse_pwc`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Graph/signals/gaussian_pulse_pwc.md#boulderopal.graph.signals.gaussian_pulse_pwc)
: Create a Pwc representing a Gaussian pulse.

[`Graph.signals.hann_series_pwc`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Graph/signals/hann_series_pwc.md#boulderopal.graph.signals.hann_series_pwc)
: Create a Pwc representing a sum of Hann window functions.

[`Graph.signals.sech_pulse_pwc`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Graph/signals/sech_pulse_pwc.md#boulderopal.graph.signals.sech_pulse_pwc)
: Create a Pwc representing a hyperbolic secant pulse.

[`Graph.signals.sinusoid_pwc`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Graph/signals/sinusoid_pwc.md#boulderopal.graph.signals.sinusoid_pwc)
: Create a Pwc representing a sinusoidal oscillation.

[`Graph.signals.square_pulse_pwc`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Graph/signals/square_pulse_pwc.md#boulderopal.graph.signals.square_pulse_pwc)
: Create a Pwc representing a square pulse.

[`Graph.cos`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Graph/cos.md#boulderopal.graph.Graph.cos)
: Calculate the element-wise cosine of an object.

## Notes

The cosine pulse is defined as

$$
\mathop{\mathrm{Cos}}(t) =
\begin{cases}
0
&\mathrm{if} \quad t < t_\mathrm{start} \\
\frac{A}{2} \left[1+\cos \left(\omega \{t-\tau_-\} \right)
+ i\omega\beta \sin \left(\omega \{t-\tau_-\}\right)\right]
&\mathrm{if} \quad t_\mathrm{start} \le t < \tau_- \\
A
&\mathrm{if} \quad \tau_- \le t \le \tau_+ \\
\frac{A}{2} \left[1+\cos \left(\omega\{t-\tau_+\}\right)
+ i\omega \beta\sin \left(\omega \{t-\tau_+\}\right)\right]
&\mathrm{if} \quad \tau_+ < t \le t_\mathrm{end} \\
0
&\mathrm{if} \quad t > t_\mathrm{end} \\
\end{cases},
$$

where $\omega=2\pi /(t_\mathrm{end}-t_\mathrm{start} - t_\mathrm{flat})$,
$\tau_\mp$ are the start/end times of the flat segment,
with $\tau_\mp=(t_\mathrm{start}+t_\mathrm{end} \mp t_\mathrm{flat})/2$.

If the flat duration is zero (the default setting), this reduces to

$$
\mathop{\mathrm{Cos}}(t) =
\frac{A}{2} \left[1+\cos \left(\omega \{t-\tau\} \right)
+ i\omega\beta \sin \left(\omega \{t-\tau\}\right)\right]
\theta(t-t_\mathrm{start}) \theta(t_\mathrm{end}-t),
$$

where now $\omega=2\pi /(t_\mathrm{end}-t_\mathrm{start})$,
$\tau=(t_\mathrm{start}+t_\mathrm{end})/2$
and $\theta(t)$ is the
[Heaviside step function](https://en.wikipedia.org/wiki/Heaviside_step_function).

## Examples

Define a cosine PWC pulse.

```pycon
>>> graph.signals.cosine_pulse_pwc(
...     duration=3.0, segment_count=100, amplitude=1.0, name="cos_pulse"
... )
<Pwc: name="cos_pulse", operation_name="pwc_signal", value_shape=(), batch_shape=()>
>>> result = bo.execute_graph(graph=graph, output_node_names="cos_pulse")
>>> result["output"]["cos_pulse"]
{
    'durations': array([0.03, 0.03, ..., 0.03, 0.03]),
    'values': array([2.46719817e-04, 2.21901770e-03, ..., 2.21901770e-03, 2.46719817e-04]),
    'time_dimension': 0
}
```

Define a flat-top cosine PWC pulse with a DRAG correction.

```pycon
>>> graph.signals.cosine_pulse_pwc(
...     duration=3.0,
...     segment_count=100,
...     amplitude=1.0,
...     drag=0.1,
...     start_time=1.0,
...     end_time=2.0,
...     flat_duration=0.3,
...     segmentation="MINIMAL",
...     name="cos_flat",
... )
<Pwc: name="cos_flat", operation_name="pwc_signal", value_shape=(), batch_shape=()>
>>> result = bo.execute_graph(graph=graph, output_node_names="cos_flat")
>>> result["output"]["cos_flat"]
{
    'durations': array([1.        , 0.00729167, ..., 0.00729167, 1.        ]),
    'values': array([0.00000000e+00+0.j        , 2.67706262e-04-0.01468429j, ...,
                     2.67706262e-04+0.01468429j, 0.00000000e+00+0.j        ]),
    'time_dimension': 0
}
```

Define a cosine pulse with optimizable parameters.

```pycon
>>> amplitude = graph.optimizable_scalar(
...     lower_bound=0, upper_bound=2.*np.pi, name="amplitude"
... )
>>> drag = graph.optimizable_scalar(
...     lower_bound=0, upper_bound=1., name="drag"
... )
>>> graph.signals.cosine_pulse_pwc(
...     duration=3.0,
...     segment_count=100,
...     amplitude=amplitude,
...     drag=drag,
...     name="cos_pulse",
... )
<Pwc: name="cos_pulse", operation_name="pwc_signal", value_shape=(), batch_shape=()>
```
