Battery Simulator
=================

.. py:module:: Nets
    :noindex:

.. py:class:: Battery

    Class for controlling power traces with a supply

    .. py:method:: setup_battery(
        sim_mode=None,
        soc=None,
        voc=None,
        voltage_full=None,
        voltage_empty=None,
        current_limit=None,
        capacity=None,
        model=None)

        Setup battery output on trace. In Dynamic mode the battery will discharge or
        charge according to a modeled charge/discharge curve. In Static mode the battery
        will remain at its initial SOC.

        .. code-block:: python
            :emphasize-lines: 7,8,9,10,11,12,13,14

            from lager import Net, NetType, SimMode

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            v_bat.setup_battery(
                sim_mode=SimMode.Dynamic,
                soc=50,
                voc=None,
                voltage_full=4.2,
                voltage_empty=3.0,
                current_limit=1.0,
                capacity=1.5)
            v_bat.enable()

        :param SimMode sim_mode: Simulation mode for battery output
        :param float soc: State of Charge of battery in Volts
        :param float voc: Open circuit battery voltage in Volts
        :param float voltage_full: Voltage at 100% SOC in Volts
        :param float voltage_empty: Voltage at 0% SOC in Volts
        :param float current_limit: Max charge/discharge current in Amps
        :param float capacity: Battery capacity in Ah

    .. py:method:: voltage()

        Query real-time battery voltage

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            voltage = v_bat.voltage()
            print(voltage)

        :return: real time battery voltage in Volts
        :rtype: float

    .. py:method:: current()

        Query real-time battery current

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            current = v_bat.current()
            print(current)

        :return: real time battery current in Amps
        :rtype: float

    .. py:method:: esr()

        Query Equivalent Series Resistence

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            esr = v_bat.esr()
            print(esr)

        :return: Equivlanet Series Resistance
        :rtype: float

    .. py:method:: soc()

        Query State Of Charge

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            soc = v_bat.soc()
            print(soc)

        :return: State Of Charge
        :rtype: float

    .. py:method:: capacity()

        Query remaining battery capacity

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            capacity = v_bat.capacity()
            print(capacity)

        :return: battery capacity
        :rtype: float

    .. py:method:: capacity_limit()

        Query remaining max battery capacity

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            cap_limit = v_bat.capacity_limit()
            print(cap_limit)

        :return: battery capacity
        :rtype: float

    .. py:method:: mode()

        Query simulation mode.

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            mode = v_bat.mode()
            print(mode)

        :return: simulation mode
        :rtype: SimMode

    .. py:method:: model()

        Get battery model in use.

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            model = v_bat.model()
            print(model)

        :return: model
        :rtype: str

    .. py:method:: voltage_full()

        Get voltage at 100% charge.

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            volt_full = v_bat.voltage_full()
            print(volt_full)

        :return: voltage
        :rtype: float

    .. py:method:: voltage_empty()

        Get voltage at 0% charge.

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            volt_empty = v_bat.voltage_empty()
            print(volt_empty)

        :return: voltage
        :rtype: float

    .. py:method:: current_limit()

        Get maximum discharge current.

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            curr = v_bat.current_limit()
            print(curr)

        :return: current
        :rtype: float

    .. py:method:: terminal_voltage()

        Get real-time terminal voltage.

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            tvolt = v_bat.terminal_voltage()
            print(tvolt)

        :return: voltage
        :rtype: float

    .. py:method:: set_over_current(over_current)

        Set maximum over current on given net

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            v_bat.set_over_current(0.8)

        :param float over_current: Maximum over current on net in Amps

    .. py:method:: set_over_voltage(over_voltage)

        Set maximum over voltage on given net

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            v_bat.set_over_voltage(4.4)

        :param float over_voltage: Maximum over voltage on net in Volts


    .. py:method:: ovp_level()

        Get over voltage protection limit.

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            ovp = v_bat.ovp_level()
            print(ovp)

        :return: voltage
        :rtype: float

    .. py:method:: ocp_level()

        Get over voltage protection limit.

        .. code-block:: python
            :emphasize-lines: 7

            from lager import Net, NetType

            v_bat = Net.get('VBAT',
                        type=NetType.Battery,
                        setup_function=setup_net,
                        teardown_function=teardown_net)
            ocp = v_bat.ocp_level()
            print(ocp)

        :return: current
        :rtype: float


.. py:class:: SimMode(enum)

    Battery simulation modes.

    .. py:data:: Static

    .. py:data:: Dynamic