DOC: improve docstrings

Author: MateusStano

docs/development/testing.rst

@@ -255,8 +255,6 @@ Consider the following integration test:
         example_plain_env : rocketpy.Environment
             Example environment object to be tested.
         """
-        # TODO:: this should be added to the set_atmospheric_model() method as a
-        #        "file" option, instead of receiving the URL as a string.
         URL = "http://weather.uwyo.edu/cgi-bin/sounding?region=samer&TYPE=TEXT%3ALIST&YEAR=2019&MONTH=02&FROM=0500&TO=0512&STNM=83779"
         # give it at least 5 times to try to download the file
         example_plain_env.set_atmospheric_model(type="wyoming_sounding", file=URL)

docs/examples/camoes_flight_sim.ipynb

@@ -299,12 +299,13 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 85,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "def drogue_trigger(p, h, y):\n",
-    "    return True if y[5] < 5 and y[2] > 300 else False\n",
+    "def drogue_trigger(**kwargs):\n",
+    "    state = kwargs[\"state\"]\n",
+    "    return True if state[5] < 5 and state[2] > 300 else False\n",
     "\n",
     "\n",
     "Drogue = CAMOES.add_parachute(\n",
@@ -353,35 +354,7 @@
    "execution_count": null,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "import numpy as np\n",
-    "\n",
-    "\n",
-    "def controller_function(\n",
-    "    time, sampling_rate, state, state_history, observed_variables, air_brakes\n",
-    "):\n",
-    "    new_deployment_level = 0\n",
-    "\n",
-    "    if time <= 11.4:\n",
-    "        new_deployment_level = 1\n",
-    "    else:\n",
-    "        new_deployment_level = (\n",
-    "            -0.002906 * np.power(time, 3)\n",
-    "            + 0.1497 * np.power(time, 2)\n",
-    "            + -2.563 * time\n",
-    "            + 14.96\n",
-    "        )\n",
-    "\n",
-    "    if time > 19.6:\n",
-    "        new_deployment_level = 0\n",
-    "\n",
-    "    if time < 3.8:\n",
-    "        new_deployment_level = 0\n",
-    "\n",
-    "    air_brakes.deployment_level = new_deployment_level\n",
-    "\n",
-    "    return time, air_brakes.deployment_level"
-   ]
+   "source": "import numpy as np\n\n\ndef controller_function(**kwargs):\n    time = kwargs[\"time\"]\n    air_brakes = kwargs[\"air_brakes\"]\n\n    new_deployment_level = 0\n\n    if time <= 11.4:\n        new_deployment_level = 1\n    else:\n        new_deployment_level = (\n            -0.002906 * np.power(time, 3)\n            + 0.1497 * np.power(time, 2)\n            + -2.563 * time\n            + 14.96\n        )\n\n    if time > 19.6:\n        new_deployment_level = 0\n\n    if time < 3.8:\n        new_deployment_level = 0\n\n    air_brakes.deployment_level = new_deployment_level\n\n    return time, air_brakes.deployment_level\n"
   },
   {
    "cell_type": "code",
@@ -835,4 +808,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}

docs/notebooks/getting_started.ipynb

@@ -369,7 +369,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": null,
    "metadata": {
     "colab": {
      "base_uri": "https://localhost:8080/",
@@ -416,14 +416,6 @@
     ")\n",
     "\n",
     "\n",
-    "# Set up parachutes. This rocket, named Valetudo, only has a drogue chute.\n",
-    "def drogue_trigger(p, h, y):\n",
-    "    # Check if rocket is going down, i.e. if it has passed the apogee\n",
-    "    vertical_velocity = y[5]\n",
-    "    # Return true to activate parachute once the vertical velocity is negative\n",
-    "    return True if vertical_velocity < 0 else False\n",
-    "\n",
-    "\n",
     "# Iterate over flight settings\n",
     "out = display(\"Starting\", display_id=True)\n",
     "for setting in flight_settings(analysis_parameters, number_of_simulations):\n",
@@ -498,7 +490,7 @@
     "    Drogue = Valetudo.add_parachute(\n",
     "        \"Drogue\",\n",
     "        cd_s=setting[\"cd_s_drogue\"],\n",
-    "        trigger=drogue_trigger,\n",
+    "        trigger=\"apogee\",\n",
     "        sampling_rate=105,\n",
     "        lag=setting[\"lag_rec\"] + setting[\"lag_se\"],\n",
     "        noise=(0, 8.3, 0.5),\n",

docs/notebooks/monte_carlo_analysis/monte_carlo_analysis.ipynb

@@ -423,14 +423,6 @@
     ")\n",
     "\n",
     "\n",
-    "# Set up parachutes. This rocket, named Valetudo, only has a drogue chute.\n",
-    "def drogueTrigger(p, h, y):\n",
-    "    # Check if rocket is going down, i.e. if it has passed the apogee\n",
-    "    vertical_velocity = y[5]\n",
-    "    # Return true to activate parachute once the vertical velocity is negative\n",
-    "    return True if vertical_velocity < 0 else False\n",
-    "\n",
-    "\n",
     "# Iterate over flight settings\n",
     "out = display(\"Starting\", display_id=True)\n",
     "for setting in flight_settings(analysis_parameters, number_of_simulations):\n",
@@ -496,7 +488,7 @@
     "    Drogue = Valetudo.addParachute(\n",
     "        \"Drogue\",\n",
     "        CdS=setting[\"CdSDrogue\"],\n",
-    "        trigger=drogueTrigger,\n",
+    "        trigger=\"apogee\",\n",
     "        samplingRate=105,\n",
     "        lag=setting[\"lag_rec\"] + setting[\"lag_se\"],\n",
     "        noise=(0, 8.3, 0.5),\n",

docs/notebooks/monte_carlo_analysis/parachute_drop_from_helicopter.ipynb

@@ -459,65 +459,7 @@
    "execution_count": 19,
    "metadata": {},
    "outputs": [],
-   "source": [
-    "def controller_function(\n",
-    "    time, sampling_rate, state, state_history, observed_variables, air_brakes, sensors\n",
-    "):\n",
-    "    # state = [x, y, z, vx, vy, vz, e0, e1, e2, e3, wx, wy, wz]\n",
-    "    altitude_ASL = state[2]\n",
-    "    altitude_AGL = altitude_ASL - env.elevation\n",
-    "    vx, vy, vz = state[3], state[4], state[5]\n",
-    "\n",
-    "    # Get winds in x and y directions\n",
-    "    wind_x, wind_y = (\n",
-    "        env.wind_velocity_x(altitude_ASL),\n",
-    "        env.wind_velocity_y(altitude_ASL),\n",
-    "    )\n",
-    "\n",
-    "    # Calculate Mach number\n",
-    "    free_stream_speed = ((wind_x - vx) ** 2 + (wind_y - vy) ** 2 + (vz) ** 2) ** 0.5\n",
-    "    mach_number = free_stream_speed / env.speed_of_sound(altitude_ASL)\n",
-    "\n",
-    "    # Get previous state from state_history\n",
-    "    previous_state = state_history[-1]\n",
-    "    previous_vz = previous_state[5]\n",
-    "\n",
-    "    # If we wanted to we could get the returned values from observed_variables:\n",
-    "    # returned_time, deployment_level, drag_coefficient = observed_variables[-1]\n",
-    "\n",
-    "    # Check if the rocket has reached burnout\n",
-    "    accelerometer = sensors[0]\n",
-    "    if accelerometer.measurement[2] > 0:\n",
-    "        return None\n",
-    "\n",
-    "    # If below 1500 meters above ground level, air_brakes are not deployed\n",
-    "    if altitude_AGL < 1500:\n",
-    "        air_brakes.deployment_level = 0\n",
-    "\n",
-    "    # Else calculate the deployment level\n",
-    "    else:\n",
-    "        # Controller logic\n",
-    "        new_deployment_level = (\n",
-    "            air_brakes.deployment_level + 0.1 * vz + 0.01 * previous_vz**2\n",
-    "        )\n",
-    "\n",
-    "        # Limiting the speed of the air_brakes to 0.2 per second\n",
-    "        # Since this function is called every 1/sampling_rate seconds\n",
-    "        # the max change in deployment level per call is 0.2/sampling_rate\n",
-    "        max_change = 0.2 / sampling_rate\n",
-    "        lower_bound = air_brakes.deployment_level - max_change\n",
-    "        upper_bound = air_brakes.deployment_level + max_change\n",
-    "        new_deployment_level = min(max(new_deployment_level, lower_bound), upper_bound)\n",
-    "\n",
-    "        air_brakes.deployment_level = new_deployment_level\n",
-    "\n",
-    "    # Return variables of interest to be saved in the observed_variables list\n",
-    "    return (\n",
-    "        time,\n",
-    "        air_brakes.deployment_level,\n",
-    "        air_brakes.drag_coefficient(air_brakes.deployment_level, mach_number),\n",
-    "    )"
-   ]
+   "source": "def controller_function(**kwargs):\n    # state = [x, y, z, vx, vy, vz, e0, e1, e2, e3, wx, wy, wz]\n    time = kwargs[\"time\"]\n    sampling_rate = kwargs[\"sampling_rate\"]\n    state = kwargs[\"state\"]\n    state_history = kwargs[\"state_history\"]\n    air_brakes = kwargs[\"air_brakes\"]\n    sensors = kwargs[\"sensors\"]\n    environment = kwargs[\"environment\"]\n\n    altitude_ASL = state[2]\n    altitude_AGL = kwargs[\"height_above_ground_level\"]\n    vx, vy, vz = state[3], state[4], state[5]\n\n    # Get winds in x and y directions\n    wind_x, wind_y = (\n        environment.wind_velocity_x(altitude_ASL),\n        environment.wind_velocity_y(altitude_ASL),\n    )\n\n    # Calculate Mach number\n    free_stream_speed = ((wind_x - vx) ** 2 + (wind_y - vy) ** 2 + (vz) ** 2) ** 0.5\n    mach_number = free_stream_speed / environment.speed_of_sound(altitude_ASL)\n\n    # Get previous state from state_history\n    previous_state = state_history[-1]\n    previous_vz = previous_state[5]\n\n    # Check if the rocket has reached burnout\n    accelerometer = sensors[0]\n    if accelerometer.measurement[2] > 0:\n        return None\n\n    # If below 1500 meters above ground level, air_brakes are not deployed\n    if altitude_AGL < 1500:\n        air_brakes.deployment_level = 0\n\n    # Else calculate the deployment level\n    else:\n        # Controller logic\n        new_deployment_level = (\n            air_brakes.deployment_level + 0.1 * vz + 0.01 * previous_vz**2\n        )\n\n        # Limiting the speed of the air_brakes to 0.2 per second\n        # Since this function is called every 1/sampling_rate seconds\n        # the max change in deployment level per call is 0.2/sampling_rate\n        max_change = 0.2 / sampling_rate\n        lower_bound = air_brakes.deployment_level - max_change\n        upper_bound = air_brakes.deployment_level + max_change\n        new_deployment_level = min(max(new_deployment_level, lower_bound), upper_bound)\n\n        air_brakes.deployment_level = new_deployment_level\n\n    # Return variables of interest to be saved in the observed_variables list\n    return (\n        time,\n        air_brakes.deployment_level,\n        air_brakes.drag_coefficient(air_brakes.deployment_level, mach_number),\n    )\n"
   },
   {
    "cell_type": "code",
@@ -901,4 +843,4 @@
  },
  "nbformat": 4,
  "nbformat_minor": 2
-}
+}

docs/notebooks/sensors.ipynb

@@ -166,12 +166,16 @@ Lets define the controller function:
 
 .. jupyter-execute::
 
-    def controller_function(
-        time, sampling_rate, state, state_history, observed_variables, air_brakes, sensors, environment
-    ):
+    def controller_function(**kwargs):
         # state = [x, y, z, vx, vy, vz, e0, e1, e2, e3, wx, wy, wz]
+        time = kwargs["time"]
+        state = kwargs["state"]
+        sampling_rate = kwargs["sampling_rate"]
+        motor = kwargs["rocket"].motor
+        environment = kwargs["environment"]
+        air_brakes = kwargs["air_brakes"]
         altitude_ASL = state[2]
-        altitude_AGL = altitude_ASL - environment.elevation
+        altitude_AGL = kwargs["height_above_ground_level"]
         vx, vy, vz = state[3], state[4], state[5]
 
         # Get winds in x and y directions
@@ -184,15 +188,15 @@ Lets define the controller function:
         mach_number = free_stream_speed / environment.speed_of_sound(altitude_ASL)
 
         # Get previous state from state_history
-        previous_state = state_history[-1]
+        previous_state = kwargs["state_history"][-1]
         previous_vz = previous_state[5]
 
         # If we wanted to we could get the returned values from observed_variables:
         # returned_time, deployment_level, drag_coefficient = observed_variables[-1]
 
         # Check if the rocket has reached burnout
-        if time < Pro75M1670.burn_out_time:
-            return None
+        if time < motor.burn_out_time:
+            air_brakes.deployment_level = 0
 
         # If below 1500 meters above ground level, air_brakes are not deployed
         if altitude_AGL < 1500:
@@ -417,7 +421,7 @@ Then we can plot the data we want.
 
     time_list, deployment_level_list, drag_coefficient_list = [], [], []
 
-    obs_vars = test_flight.get_controller_observed_variables()
+    obs_vars = test_flight._controllers[0].log
 
     for time, deployment_level, drag_coefficient in obs_vars:
         time_list.append(time)