Merge remote-tracking branch 'upstream/master'

docs/source/api.rst

@@ -1,14 +1,30 @@
 API Reference
 =============
 
+.. automodule:: pyfme.simulator
+   :members:
+
 `pyfme.environment` package
 ---------------------------
 
 .. automodule:: pyfme.environment
 
-.. automodule:: pyfme.environment.isa
+.. autoclass:: pyfme.environment.environment.Environment
    :members:
 
+.. autoclass:: pyfme.environment.atmosphere.Atmosphere
+   :members:
+
+.. autoclass:: pyfme.environment.atmosphere.ISA1976
+   :members:
+
+.. automodule:: pyfme.environment.gravity
+   :members:
+
+.. automodule:: pyfme.environment.wind
+   :members:
+
+
 `pyfme.models` package
 ----------------------
 
@@ -17,7 +33,7 @@ API Reference
 .. automodule:: pyfme.models.euler_flat_earth
    :members:
 
-.. automodule:: pyfme.models.system
+.. automodule:: pyfme.models.systems
    :members:
 
 `pyfme.utils` package
@@ -27,3 +43,12 @@ API Reference
 
 .. automodule:: pyfme.utils.coordinates
    :members:
+
+.. automodule:: pyfme.utils.anemometry
+   :members:
+
+.. automodule:: pyfme.utils.input_generator
+   :members:
+
+.. automodule:: pyfme.utils.trimmer
+   :members:

setup.py

@@ -8,4 +8,5 @@
     version="0.1.dev0",
     packages=find_packages('src'),
     package_dir={'': 'src'},
+    install_requires=['scipy', 'numpy']
 )

src/pyfme/environment/environment.py

@@ -4,9 +4,23 @@
 Distributed under the terms of the MIT License.
 """
 
+
 class Environment(object):
+    """
+    Stores all the environment info: atmosphere, gravity and wind.
+    """
 
     def __init__(self, atmosphere, gravity, wind):
+        """
+        Parameters
+        ----------
+        atmosphere : Atmosphere
+            Atmospheric model.
+        gravity : Gravity
+            Gravity model.
+        wind : Wind
+            Wind or gust model.
+        """
         self.atmosphere = atmosphere
         self.gravity = gravity
         self.wind = wind

src/pyfme/environment/gravity.py

@@ -14,7 +14,9 @@
 from pyfme.models.constants import GRAVITY, STD_GRAVITATIONAL_PARAMETER
 from pyfme.utils.coordinates import hor2body
 
+
 class Gravity(object):
+    """Generic gravity model"""
 
     def __init__(self):
         self.magnitude = None
@@ -27,6 +29,8 @@ def update(self, system):
 
 
 class VerticalConstant(Gravity):
+    """Vertical constant gravity model.
+    """
 
     def __init__(self):
         Gravity.__init__(self)
@@ -42,6 +46,9 @@ def update(self, system):
 
 
 class VerticalNewton(Gravity):
+    """Vertical gravity model with magnitude varying according to Newton's
+    universal law of gravitation.
+    """
 
     def __init__(self):
         Gravity.__init__(self)

src/pyfme/models/systems.py

@@ -16,6 +16,9 @@
 
 
 class System(object):
+    """Generic system class contains the state vector and other derived
+    variables related to the system's state.
+    """
 
     def __init__(self, lat, lon, h, psi=0, x_earth=0, y_earth=0):
 
@@ -149,16 +152,29 @@ def set_initial_state_vector(self):
     def propagate(self, aircraft, environment, dt=0.01):
         pass
 
+
 class EulerFlatEarth(System):
+    """Euler flat Earth equations system"""
 
     def __init__(self, lat, lon, h, psi=0, x_earth=0, y_earth=0,
                  integrator='dopri5', use_jac=False, **integrator_params):
-        """
-        Initialize the equations of the chosen model and selects the
+        """Initialize the equations of the chosen model and selects the
         integrator. Check `scipy.integrate.ode` to see available integrators.
 
         If use_jac = True the jacobian of the equations is used for the
         integration.
+
+        Parameters
+        ----------
+        lat, lon, h: float
+            Latitude, longitude and height (rad, rad, m).
+        psi, x_earth, y_earth: float, opt
+            Yaw angle and initial Earth position (rad, m, m).
+        integrator: str, optional
+            Any allowed integrator for `ode` class: "vode", "zvode", "lsoda",
+            "dopri5", "dop853".
+        use_jac : bool, optional
+            Use analytical jacobians of system equations.
         """
         super().__init__(lat, lon, h, psi, x_earth, y_earth)
         # State vector must be initialized with set_initial_state_vector() method
@@ -191,7 +207,9 @@ def height(self):
 
     def set_initial_state_vector(self):
         """
-        Set the initial values of the required variables
+        Set the initial values of the state vector for system integration
+        once the values for the involved variables have been assigned or the
+        system has been trimmed.
         """
 
         self.vel_NED = body2hor(self.vel_body, theta=self.theta,
@@ -251,7 +269,8 @@ def propagate(self, aircraft, dt=0.01):
 
         Parameters
         ----------
-        environment
+        aircraft : Aircraft
+            Aircraft model for simulation is used to get forces.
         """
         self.dt = dt
         self._propagate_state_vector(aircraft, dt)

src/pyfme/simulator.py

@@ -12,8 +12,25 @@
 
 
 class Simulation(object):
+    """
+    Simulation class stores the simulation configuration, aircraft, system and
+    environment. It provides methods for simulation running and results
+    storing.
+    """
 
     def __init__(self, aircraft, system, environment):
+        """
+        Simulation objects.
+
+        Parameters
+        ----------
+        aircraft : Aircraft
+            Aircraft.
+        system : System
+            System.
+        environment : Environment
+            Environment.
+        """
         self.aircraft = aircraft
         self.system = system
         self.environment = environment
@@ -53,6 +70,14 @@ def __init__(self, aircraft, system, environment):
         self.par_dict = {}
 
     def time_step(self, dt):
+        """
+        Performs a simulation time step.
+
+        Parameters
+        ----------
+        dt : float
+            Time step (s).
+        """
 
         self.save_current_par_dict()
         self._time_step += 1
@@ -78,6 +103,18 @@ def save_current_par_dict(self):
 class BatchSimulation(Simulation):
 
     def __init__(self, aircraft, system, environment):
+        """
+        Simulation objects.
+
+        Parameters
+        ----------
+        aircraft : Aircraft
+            Aircraft.
+        system : System
+            System.
+        environment : Environment
+            Environment.
+        """
         super().__init__(aircraft, system, environment)
         self.time = None
         self.aircraft_controls = {}
@@ -87,12 +124,10 @@ def set_controls(self, time, controls):
 
         Parameters
         ----------
-        time
-        controls
-
-        Returns
-        -------
-
+        time : array_like
+            Time history for the simulation.
+        controls : array_like
+            Controls for the given time array.
         """
 
         # check time dimensions
@@ -123,6 +158,12 @@ def _get_current_controls(self, ii):
                 self.aircraft_controls.keys()}
 
     def run_simulation(self):
+        """
+        Run simulation for the times in self.time.
+        """
+        if self.time is None:
+            raise ValueError("Time and controls for the simulation must be "
+                             "set with `set_controls()`")
 
         for ii, t in enumerate(self.time[1:]):
             dt = t - self.time[ii]
@@ -131,7 +172,14 @@ def run_simulation(self):
         self.save_current_par_dict()
 
     def set_par_dict(self, par_list):
+        """
+        Set parameters to be saved
 
+        Parameters
+        ----------
+        par_list : list
+            List with parameter names.
+        """
         if self.time is None:
             msg = "Set controls with BatchSimulation.set_controls before " \
                   "setting the par_dict"
@@ -181,10 +229,10 @@ def save_current_par_dict(self):
             par_values[self._time_step] = self.PAR_KEYS[par_name]
 
 
-
 class RealTimeSimulation(Simulation):
 
     def __init__(self, aircraft, system, environment):
+        raise NotImplementedError()
         super(RealTimeSimulation, self).__init__(aircraft, system, environment)
         # TODO:...