# How to use DC outputs

Every Presto comes with 16 direct-current (DC) outputs. There are three ways to control the output
voltage. The first two methods are part of the {mod}`.hardware` class and should be used outside a
{mod}`.pulsed` experimental sequence. The third method is part of the {class}`.Pulsed` class and is
meant to be used during the pulses sequence.

## {meth}`.Hardware.set_dc_bias`

The first function used to set the parameters of DC outputs is {meth}`.Hardware.set_dc_bias`. The
signal is output "immediately", or as soon as the command is received by Presto. The range is
either chosen explicitly or assigned automatically.

When changing range, a short voltage transient (≈20% of DC value for ≈6 μs) can appear on the
DC-bias output. This transient is observable on a high-impedance input, while it is usually
negligible on a low-impedance input.

```python
bias = 5  # V
port = 1  # (int or list of int) - valid values are in [1,16]

pls.hardware.set_dc_bias(bias, port=[2, 3])
pls.hardware.set_dc_bias(bias=-2.0, port=port, range_i=4)  # manually select range ±10.0 V
pls.hardware.sleep(10e-3, False)
```
The voltage on ports 2 and 3 changes simultaneously, as it was set in the same command. The bias on
port 1 changes when the next command is executed.
```{image} images/DC_set1_light.svg
:align: center
:class: only-light
```

```{image} images/DC_set1_dark.svg
:align: center
:class: only-dark
```
The output stays on indefinitely, so it is sometimes a good idea to turn it off at the end of the
sequence. If you want to make sure the range does not change when going back to 0 V, you can pass
the current value of `range_i` to the {meth}`.set_dc_bias` method.

```python
# let the API choose a new range
pls.hardware.set_dc_bias(bias=0.0, port=[2,3])
# or keep the current range
curret_bias, current_range = pls.hardware.get_dc_bias(port, get_range=True)
pls.hardware.set_dc_bias(bias=0.0, port=port, range_i=current_range)
```

```{image} images/DC_set2_light.svg
:align: center
:class: only-light
```

```{image} images/DC_set2_dark.svg
:align: center
:class: only-dark
```

## {meth}`.Hardware.ramp_dc_bias`

It is possible to change the DC bias with a defined slew rate (V/s). This is useful, for example,
when the DC output is connected to a coil. Changing the range of the output voltage during the ramp
is not allowed. If needed, the range should be changed before initiating the ramp using
{meth}`.Hardware.set_dc_bias`.

```python
# set initial condition
pls.hardware.set_dc_bias(
   bias=-3.0,  # -3 V
   port=1,
   range_i=4,  # ±10.0 V
)
pls.hardware.sleep(10e-3, False)

# slowly ramp bias voltage from -3 V to +3 V in 8 seconds
pls.hardware.ramp_dc_bias(
   bias=+3.0,  # +3 V
   port=1,
   rate=0.75,  # 0.75 V/s
)
```
See the ramping of the DC bias captured by the oscilloscope connected to DC bias output port 1:
```{image} images/DC_ramp_light.svg
:align: center
:class: only-light
```

```{image} images/DC_ramp_dark.svg
:align: center
:class: only-dark
```

## {meth}`.Pulsed.output_dc_bias`

Use {meth}`.Pulsed.output_dc_bias` to change the value of the DC output at a specific point in time
during a {mod}`.pulsed` sequence. It is not possible to change the DC range during the pulse
sequence, instead use {meth}`.Hardware.set_dc_bias` to configure the range and the initial DC bias
before programming the experimental sequence. It is also recommended to reset the value to zero (or
some other value of your choice) after the experiment terminated, i.e. after a call to run().

Updating the DC bias on one port takes 1 μs, during which no other DC bias event should be
scheduled. Updating the bias on `n` ports takes `n` μs, and all ports will switch to the new value
simultaneously.

In the following example, we set the initial voltage of port 1 to 0 V. Then, we program a sequence
where every 10 μs we step through a list of voltages defined in `bias_list`, increasing the voltage
by 0.25 V. And finally we set the output voltage to zero when the sequence terminates.

```python
bias_list = np.linspace(-0.5,0.5,5)  # V

with pulsed.Pulsed(**CONFIG) as pls:
   pls.hardware.set_dc_bias(
      bias=0,  # V
      port=1,
      range_i=4,  # ±10.0 V
   )
   pls.hardware.sleep(10e-3, False)

   T = 0.0
   for bias in bias_list:
      pls.output_dc_bias(T, bias, port=1)
      T += 10e-6
   pls.run(T, 1, 1)

   pls.hardware.set_dc_bias(
      bias=0.0,  # 0 V
      port=1,
      range_i=4,  # ±10.0 V
   )
```
The programmed sequence is measured by an oscilloscope (below).
```{image} images/DC_pulse_light.svg
:align: center
:class: only-light
```

```{image} images/DC_pulse_dark.svg
:align: center
:class: only-dark
```