Merge pull request #215 from RocketPy-Team/doc/rocketpy-hackathon-tutorial

DOC: add more development pages

Author: giovaniceotto

docs/development/github_hackathon.rst

@@ -0,0 +1 @@
+.. mdinclude:: ./github_tutorial.md

docs/development/github_tutorial.md

@@ -0,0 +1,98 @@
+# RocketPy Hackathon
+## _Git and GitHub Introduction_
+
+This tutorial is meant to guide the hackathon participants to the basic functionalities of Git and GitHub that they are going to need while solving the Challenges.
+
+## Git Installation
+
+In order to work with RocketPy Hackathon repository, one must have Git installed in the machine. The install instructions are available at [the official Git page](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) for Linux, Windows and Mac.
+
+Furthermore, specially if the participant is more comfortable with a GUI interface for operating with Git (instead of terminal), it is optional to download [GitHub Desktop](https://desktop.github.com/).
+
+## GitHub Account Configuration
+
+A GitHub account is required for submitting changes to the Hackathon Repository. If the participant does not have an account, it is possible to sign up [here](https://github.com/signup?source=login).
+
+After successfully creating an account, it must be set up with the participant _username_ and _email address_, this can be done with the following terminal commands:
+
+```sh
+git config --global user.name "your_username"
+git config --global user.email "[email protected]"
+```
+
+## Repository Workflow
+
+### Cloning
+
+First and foremost, the participant must open a terminal session and change the current directory to the one in which the Hackathon Repository will be downloaded. Then it is necessary to clone the Hackathon GitHub repository with the following commands:
+
+```sh
+cd <your_desired_path>
+git clone https://github.com/Projeto-Jupiter/RocketPy-Hackathon-2022.git
+```
+
+### Basic Workflow
+
+The basic workflow of interacting with a GitHub repository is through getting the most recent version of code (pull), making necessary changes (commits) and uploading these changes to the remote repository (pushes). For instance, the basic workflow for updating a README.md file from a repository would be similar to this:
+
+```sh
+# getting most recent version
+git pull
+# selecting all changed files to commit
+git add .
+# update the local repository with changes and 
+# a descriptive commit message
+git commit -m "Updade README.md file"
+# upload changes to the remote repository
+git push
+```
+
+### Pull Requests
+
+Pull Requests are a way to notify others of the changes made to the code, so that these changes may be revised by others before being merged into the final code. Pull Requests are located at the _Pull Request_ tab on the main page of the GitHub repository.
+
+A new Pull Request can be made by specifying which changes should be merged into the repository, as illustrates the figure below:
+
+![pull_request_button](https://docs.github.com/assets/cb-34915/images/help/pull_requests/choose-base-and-compare-branches.png)
+
+## Forks and Branches
+
+### Forks
+
+A Fork is a copy of a GitHub repository that allows the user to make changes to a repository while keeping the original unchanged, the changes are updated to the original repository through pull requests. The participant will solve the Challenges and make contributions to a local Fork of the Hackathon GitHub repository, so that it is possible to keep the solutions organized and avoid conflicts that arise from multiple groups editing the same code. It is recommended to use GitHub environment to create a Fork, the participant has to click on the top right corner of the Hackathon GitHub page:
+
+![fork_button](https://docs.github.com/assets/cb-23088/images/help/repository/fork_button.png)
+
+### Branches
+   
+A Branch is a separate development path for the repository. They are specially useful for developing new features, testing changes or bug fixing while keeping the original code unchanged. The changes made in a branch can be merged into another branch through a Pull Request. It is recommended that the participant organize its own workflow with branches, since there are multiple Challenges that must be solved (sometimes working on more than one Challenge concurrently). Branches can be created from the terminal with the following command:
+
+```sh
+git checkout -b <new_branch_name>
+```
+
+After this command, a new branch will be created and the user is automatically directed to it. Furthermore, changing branches is done with the command ```git checkout <branch_name>``` (existing branches can be seen either on GitHub repository page or in terminal with the command ```git branch```).
+
+![branches_button](https://docs.github.com/assets/cb-107867/images/help/branches/branches-overview-link.png)
+
+## Issues and Challenges
+
+The Hackathon Challenges are going to be released in the form of issues at the RocketPy Hackathon repository. They will be available after the Hackathon starts and can be accessed by clicking on the tab _issues_ as seen below:
+
+![issues_button](https://docs.github.com/assets/cb-25896/images/help/repository/repo-tabs-issues.png)
+
+After solving a Challenge, the participant will have to make a pull request to the main Hackathon repository.
+
+## Further Information
+
+Should the participant have any issues, RocketPy team is willing to help at a wide range of time-zones. Further information on Git/GitHub and GitHub Desktop are available from the official [GitHub Docs](https://docs.github.com/en). The documentation for the main topics covered in this tutorial are available in the table below:
+
+| Topic | Documentation |
+| ------ | ------ |
+| Git Install and Set Up| [get-started/quickstart/set-up-git](https://docs.github.com/en/get-started/quickstart/set-up-git) |
+| GitHub Desktop | [get-started/using-github/github-desktop](https://docs.github.com/en/get-started/using-github/github-desktop) |
+| Commits | [creating-and-editing-commits/about-commits](https://docs.github.com/pt/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits) |
+| Forks | [get-started/quickstart/fork-a-repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo) |
+| Branches | [creating-and-deleting-branches-within-your-repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-and-deleting-branches-within-your-repository) |
+| Pull Request | [get-started/quickstart/github-flow](https://docs.github.com/en/get-started/quickstart/github-flow) |
+

docs/development/index.rst

@@ -5,6 +5,8 @@ Welcome to RocketPy's development documentation!
    :maxdepth: 2
    :caption: Contents:
 
+   Running RocketPy as a Developer <rocketpy_as_developer.rst>
+   GitHub Workflow for RocketPy Hackathon 2022 <github_hackathon.rst>
    Style Guide <style_guide>
 
 This section is still a work in progress. Here you will find information on how to contribute to our code base.

docs/development/rocketpy_as_developer.rst

@@ -0,0 +1,256 @@
+========================
+Introduction to RocketPy
+========================
+
+This tutorial part shows how to open rocketpy files and run a simple simulation.
+
+Opening rocketpy folder
+=======================
+
+Go into the cloned repository folder by typing on a terminal
+
+.. code-block:: console
+
+    cd <rocketpy directory>
+
+Open your preference editor by typing on a terminal
+
+.. code-block:: console
+    
+    <editor name> .
+
+For example, to open VS Code type on terminal
+
+.. code-block:: console
+    
+    code .
+
+Alternatively, you can open the folder directly through your editor's interface.
+
+Preparing directory for code editing
+====================================
+
+You may create a testing file in any directory, but you must remember that they should not be included in the commits and pull requests unless they are part of the proposed solution.
+With that in mind, it is suggested the creation of a folder with all the testing files, so they can be added in the .gitignore file, which contains the name of all the files and folders that will not be added to the commits. To create the folder, type on the terminal:
+
+.. code-block:: console
+
+    mkdir <folder name>
+
+And, to add it on .gitignore, type:
+
+.. code-block:: console
+    
+    echo <folder name>/ >> .gitignore
+
+It is important to remember that all the files inside this folder will not be included in any commit so, if it is important to the solution, do not add them inside it.
+
+Running a simulation with RocketPy
+==================================
+
+Importing the RocketPy files
+----------------------------
+
+First, create a python (or .ipynb) file to make the simulation.
+To ensure you are using the local files and not the files as a python package (if you installed the library via pip for example), add 
+
+.. code-block:: python
+
+    pip install -e .
+
+Alternatively you can use the following command to pip install the local library:
+
+.. code-block:: console
+    
+    import sys
+    sys.path.append('../') # if you are using a notebook
+    sys.path.append('../rocketpy') # if you are using a script
+
+Import the classes that will be used, in case:
+
+.. code-block:: python
+    
+    from rocketpy import Environment, SolidMotor, Rocket, Flight, Function
+
+If it is the first time you are using rocketpy and you do not have all required libraries installed, you could use the command:
+
+.. code-block:: python
+
+    pip install -r </path/to/requirements.txt>
+
+Alternatively, if you are in rocketpy folder, just type
+
+.. code-block:: python
+
+    pip install -r requirements.txt
+
+Creating an Environment
+-----------------------
+
+Here we create the environment object that will be used in the simulation.
+It contains information about the local pressure profile, temperature, speed of sound, wind direction and intensity, etc.
+
+.. code-block:: python
+
+    Env = Environment(railLength=5.2, latitude=32.990254, longitude=-106.974998, elevation=1400)
+
+RocketPy can use local files via the Ensemble method or meteorological forecasts through OpenDAP protocol. 
+To work with environment files, it will be very important ensuring tha that you have the netCDF4 library installed.
+Assuming we are using forecast, first we set the simulated data with:
+
+.. code-block:: python
+
+    import datetime
+    tomorrow = datetime.date.today() + datetime.timedelta(days=1)
+    Env.setDate((tomorrow.year, tomorrow.month, tomorrow.day, 12))  # Hour given in UTC time
+
+Then we set the atmospheric model, in this case, GFS forecast:
+
+.. code-block:: python
+
+    Env.setAtmosphericModel(type="Forecast", file="GFS")
+
+Weather forecast data can be visualized through two info methods.
+
+``Env.info()`` or ``Env.allInfo()``
+
+Creating the motor that boosts the rocket
+-----------------------------------------
+
+Now we need to create the motor. 
+For example, we will use a solid motor called Pro75M1670, but other configurations are also possible.
+The motor class contains information about the thrust curve and uses some geometric parameters to calculate the mass variation over time, as well as the total thrust and other important outputs.
+
+.. code-block:: python
+
+    Pro75M1670 = SolidMotor(
+        thrustSource="../data/motors/Cesaroni_M1670.eng",
+        burnOut=3.9,
+        grainNumber=5,
+        grainSeparation=5 / 1000,
+        grainDensity=1815,
+        grainOuterRadius=33 / 1000,
+        grainInitialInnerRadius=15 / 1000,
+        grainInitialHeight=120 / 1000,
+        nozzleRadius=33 / 1000,
+        throatRadius=11 / 1000,
+        interpolationMethod="linear",
+    )
+
+Motor data can be visualized through the following methods:
+
+``Pro75M1670.info()`` or ``Pro75M1670.allInfo()``
+
+
+Creating the rocket
+-------------------
+
+The Rocket class contains all information about the rocket that are necessary to the simulation, including the motor, rocket mass and inertia, aerodynamic surfaces, parachutes, etc.
+The first step is to initialize the class with the vital data:
+
+.. code-block:: python
+
+    Calisto = Rocket(
+        motor=Pro75M1670,
+        radius=127 / 2000,
+        mass=19.197 - 2.956,
+        inertiaI=6.60,
+        inertiaZ=0.0351,
+        distanceRocketNozzle=-1.255,
+        distanceRocketPropellant=-0.85704,
+        powerOffDrag="../../data/calisto/powerOffDragCurve.csv",
+        powerOnDrag="../../data/calisto/powerOnDragCurve.csv",
+    )
+
+Then the rail buttons must be set:
+
+.. code-block:: python
+    
+    Calisto.setRailButtons([0.2, -0.5])
+
+In sequence, the aerodynamic surfaces must be set.
+If a lift curve for the fin set is not specified, it is assumed that they behave according to a linearized model with a coefficient calculated with Barrowman's theory.
+In the example, a nosecone, one fin set and one tail were added, but each case can be designed differently.
+
+.. code-block:: python
+
+    NoseCone = Calisto.addNose(length=0.55829, kind="vonKarman", distanceToCM=0.71971)
+
+    FinSet = Calisto.addFins(4, span=0.100, rootChord=0.120, tipChord=0.040, distanceToCM=-1.04956)
+
+    Tail = Calisto.addTail(topRadius=0.0635, bottomRadius=0.0435, length=0.060, distanceToCM=-1.194656)
+
+If you are considering the parachutes in the simulation, they also have to be added to the rocket object.
+A trigger function must be supplied to trigger the parachutes.
+Currently, the pressure `(p)` and the state-space variables `(y)` are necessary inputs for the function.
+The state-space contains information about the rocket's position and velocities (translation and rotation).
+For example:
+
+.. code-block:: python
+
+    def drogueTrigger(p, y):
+        # p = pressure
+        # y = [x, y, z, vx, vy, vz, e0, e1, e2, e3, w1, w2, w3]
+        # activate drogue when vz < 0 m/s.
+        return True if y[5] < 0 else False
+
+
+    def mainTrigger(p, y):
+        # p = pressure
+        # y = [x, y, z, vx, vy, vz, e0, e1, e2, e3, w1, w2, w3]
+        # activate main when vz < 0 m/s and z < 800 + 1400 m (+1400 due to surface elevation).
+        return True if y[5] < 0 and y[2] < 800 + 1400 else False
+
+After having the trigger functions defined, the parachute must be added to the rocket:
+
+.. code-block:: python
+
+    Main = Calisto.addParachute(
+        "Main",
+        CdS=10.0,
+        trigger=mainTrigger,
+        samplingRate=105,
+        lag=1.5,
+        noise=(0, 8.3, 0.5),
+    )
+
+    Drogue = Calisto.addParachute(
+        "Drogue",
+        CdS=1.0,
+        trigger=drogueTrigger,
+        samplingRate=105,
+        lag=1.5,
+        noise=(0, 8.3, 0.5),
+    )
+
+Simulating the flight
+--------------------
+
+Finally, the flight can be simulated with the provided data.
+The rocket and environment classes are supplied as inputs, as well as the rail inclination and heading angle.
+
+.. code-block:: python
+
+    TestFlight = Flight(rocket=Calisto, environment=Env, inclination=85, heading=0)
+
+Flight data can be retrieved through:
+
+``TestFlight.info()`` or ``TestFlight.allInfo()``
+
+This function plots a comprehensive amount of flight data and graphs but, if you want to access one specific variable, for example Z position, this may be achieved by `TestFlight.z`.
+If you insert `TestFlight.z()` the graph of the function will be plotted.
+This and other features can be found in the documentation of the `Function` class, which allows data to be treated in an easier way.
+The documentation of each variable used in the class can be found on `Flight.py` file.
+
+Further considerations
+======================
+
+RocketPy's classes documentation can be accessed in code via `help(<name of the class>)` command.
+For example, to access Flight class parameters, you can use:
+
+.. code-block:: python
+
+    help(Flight)
+
+More documentation materials can be found at [read the docs](https://docs.rocketpy.org/en/latest/?badge=latest).
+It can also be found on RocketPy's GitHub page on the badge "docs".