eng-lab/hwe/core/energy.py

"""EL01 lab: energy, power, and flight time. YOU WRITE THIS FILE (EL01 lab, step 4).

Contracts as in hover.py: each docstring is checked by labs/el01_hover/tests, and
the @quantities line checks units at the boundary. Keep the units attached.

Three ideas from EL01, section 2.9:
- Energy is capacity times voltage. A battery's mAh is CHARGE, not energy: to
  compare two packs, multiply by their voltages first.
- Power is energy per unit time, and a hovering drone draws roughly constant power.
- Flight time is usable energy divided by power.
"""
from hwe.units import Q_, quantities


@quantities(capacity="[charge]", cell_voltage="[electric_potential]", returns="[energy]")
def battery_energy(capacity, cells, cell_voltage=Q_(3.7, "V")):
    """The energy stored in a battery pack: E = capacity x pack voltage.

    capacity      the pack's rated charge, for example Q_(1300, "mA*h").
    cells         cells in series (an int: "6S" means 6).
    cell_voltage  the voltage of one cell; 3.7 V is the usual nominal value for LiPo.
    The pack voltage is cells x cell_voltage. Return the energy in watt-hours.
    """
    raise NotImplementedError("Step 4: battery_energy")


@quantities(thrust_per_motor="[force]", efficiency="[force] / [power]", returns="[power]")
def propulsion_power(thrust_per_motor, efficiency, motor_count):
    """Electrical power drawn by all motors, from a thrust table's efficiency.

    thrust_per_motor  the thrust each motor makes (for a hover: weight / motor_count).
    efficiency        thrust per watt AT THAT THRUST, read from the motor's thrust
                      table, for example Q_(4.5, "gf/W").
    motor_count       how many motors (an int).
    Each motor draws thrust / efficiency. Return the total in watts.
    """
    raise NotImplementedError("Step 4: propulsion_power")


@quantities(energy="[energy]", power="[power]", returns="[time]")
def flight_time(energy, power, usable_fraction=0.8):
    """Flight time at constant power: usable energy / power.

    energy           the pack's stored energy.
    power            the total electrical power drawn (motors plus electronics).
    usable_fraction  the share of the stored energy you allow yourself to use (a
                     pure number between 0 and 1; 0.8 keeps a LiPo healthy).
    Return a time (pint converts it to whatever unit is asked for; the report
    shows minutes). Raise ValueError unless 0 < usable_fraction <= 1, and
    raise ValueError if power is not positive.
    """
    raise NotImplementedError("Step 4: flight_time")