# tanh_ramp_pwc

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

```python
signals.tanh_ramp_pwc(duration, segment_count, end_value, start_value=None, ramp_duration=None, center_time=None, *, name=None)
```

Create a Pwc representing a hyperbolic tangent ramp.

### Parameters
* **duration** (*float*) – The duration of the signal, $T$.
* **segment_count** (*int*) – The number of segments in the PWC.
* **end_value** (*float* *or* *complex* *or* [*Tensor*](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Tensor.md#boulderopal.graph.Tensor)) – The asymptotic value of the ramp towards $t \to +\infty$, $a_+$.
  It must either be a scalar or contain a single element.
* **start_value** (*float* *or* *complex* *or* [*Tensor*](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Tensor.md#boulderopal.graph.Tensor) *or* *None* *,* *optional*) – The asymptotic value of the ramp towards $t \to -\infty$, $a_-$.
  If passed, it must either be a scalar or contain a single element.
  Defaults to minus end_value.
* **ramp_duration** (*float* *or* [*Tensor*](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Tensor.md#boulderopal.graph.Tensor) *or* *None* *,* *optional*) – The characteristic time for the hyperbolic tangent ramp, $t_\mathrm{ramp}$.
  If passed, it must either be a scalar or contain a single element.
  Defaults to $T/6$.
* **center_time** (*float* *or* [*Tensor*](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Tensor.md#boulderopal.graph.Tensor) *or* *None* *,* *optional*) – The time at which the ramp has its greatest slope, $t_0$.
  If passed, it must either be a scalar or contain a single element.
  Defaults to $T/2$.
* **name** (*str* *or* *None* *,* *optional*) – The name of the node.
### Returns
The sampled hyperbolic tangent ramp.
### Return type
[Pwc](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Pwc.md#boulderopal.graph.Pwc)

### SEE ALSO
[`Graph.signals.linear_ramp_pwc`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Graph/signals/linear_ramp_pwc.md#boulderopal.graph.signals.linear_ramp_pwc)
: Create a Pwc representing a linear ramp.

[`boulderopal.signals.tanh_ramp`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/signals/tanh_ramp.md#boulderopal.signals.tanh_ramp)
: Create a Signal object representing a hyperbolic tangent ramp.

[`Graph.signals.tanh_ramp_stf`](https://docs.q-ctrl.com/references/boulder-opal/boulderopal/graph/Graph/signals/tanh_ramp_stf.md#boulderopal.graph.signals.tanh_ramp_stf)
: Corresponding operation with Stf output.

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

## Notes

The hyperbolic tangent ramp is defined as

$$
\mathop{\mathrm{Tanh}}(t)
= \frac{a_+ + a_-}{2}
    + \frac{a_+ - a_-}{2} \tanh\left( \frac{t - t_0}{t_\mathrm{ramp}} \right) ,
$$

where the function’s asymptotic values $a_\pm$ are defined by:

$$
a_\pm := \lim_{t\to\pm\infty} \mathop{\mathrm{Tanh}}(t) ,
$$

and $t_0$ is related to $t_\mathrm{ramp}$ by:

$$
\left.\frac{{\mathrm d}\mathop{\mathrm{Tanh}}(t)}{{\mathrm d}t}\right|_{t=t_0}
    = \frac{ (a_+ - a_-)}{2 t_\mathrm{ramp}} .
$$

Note that if $t_0$ is close to the edges of the PWC,
for example $t_0 \lesssim 2 t_\mathrm{ramp}$,
then the first and last values of the PWC will differ from the expected asymptotic values.

With the default values of start_value ($a_-$),
ramp_duration ($t_\mathrm{ramp}$), and center_time ($t_0$),
the ramp expression simplifies to

$$
\mathop{\mathrm{Tanh}}(t) = A \tanh\left( \frac{t - T/2}{T/6} \right),
$$

where $A = a_+$ is the end value (the start value is then $-A$).
This defines a symmetric ramp (around $(T/2, 0)$)
between $-0.995 A$ (at $t=0$) and $0.995 A$ (at $t=T$).

## Examples

Define a simple tanh PWC ramp.

```pycon
>>> graph.signals.tanh_ramp_pwc(
...     duration=5.0, segment_count=50, end_value=1, name="tanh_ramp"
... )
<Pwc: name="tanh_ramp", operation_name="discretize_stf", value_shape=(), batch_shape=()>
>>> result = bo.execute_graph(graph=graph, output_node_names="tanh_ramp")
>>> result["output"]["tanh_ramp"]
{
    'durations': array([0.1, 0.1, ..., 0.1, 0.1]),
    'values': array([-0.99442601, -0.99291942, ..., 0.99291942,  0.99442601]),
    'time_dimension': 0
}
```

Define a flat-top pulse from two hyperbolic tangent ramps.

```pycon
>>> ramp = graph.signals.tanh_ramp_pwc(
...     duration=3,
...     segment_count=60,
...     end_value=1,
...     ramp_duration=0.25,
...     center_time=0.5,
... )
>>> flat_top_pulse = 0.5 * (ramp + graph.time_reverse_pwc(ramp))
>>> flat_top_pulse.name="flat_top_pulse"
>>> result = bo.execute_graph(graph=graph, output_node_names="flat_top_pulse")
>>> result["output"]["flat_top_pulse"]
{
    'durations': array([0.05, 0.05, ..., 0.05, 0.05]),
    'values': array([0.02188127, 0.03229546, ..., 0.03229546, 0.02188127]),
    'time_dimension': 0
}
```

Define a hyperbolic tangent ramp with optimizable parameters.

```pycon
>>> end_value = graph.optimizable_scalar(
...     lower_bound=0, upper_bound=3e6, name="end_value"
... )
>>> ramp_duration = graph.optimizable_scalar(
...     lower_bound=0.1e-6, upper_bound=0.3e-6, name="ramp_duration"
... )
>>> center_time = graph.optimizable_scalar(
...     lower_bound=0.25e-6, upper_bound=0.75e-6, name="center_time"
... )
>>> graph.signals.tanh_ramp_pwc(
...     duration=1e-6,
...     segment_count=32,
...     end_value=end_value,
...     start_value=0.0,
...     ramp_duration=ramp_duration,
...     center_time=center_time,
...     name="tanh_ramp",
... )
<Pwc: name="tanh_ramp", operation_name="discretize_stf", value_shape=(), batch_shape=()>
```
