Skip to content

Commit 168b1b8

Browse files
planesplanes
committed
documentation
1 parent dc40d12 commit 168b1b8

File tree

4 files changed

+343
-178
lines changed

4 files changed

+343
-178
lines changed

‎documentation.html‎

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -83,9 +83,9 @@ <h3>Another Subheading</h3>
8383
<li><a href="documentation/code_style.html">Code Style</a></li>
8484
<li><a href="documentation/using_docs.html">Using the Documentation</a></li>
8585
<li><a href="documentation/missions.html">Mission Solver Structure</a></li>
86-
<li><a href="#">Consequat etiam lorem phasellus</a></li>
87-
<li><a href="#">Amet turpis, feugiat et sit amet</a></li>
88-
<li><a href="#">Semper mod quisturpis nisi</a></li>
86+
<li><a href="documentation/energy_nets.html">Energy Networks</a></li>
87+
<li><a href="documentation/optimization.html">Optimization Structure</a></li>
88+
<li><a href="documentation/faq.html">Frequently Asked Questions</a></li>
8989
</ul>
9090
<footer>
9191
<a href="#" class="button">More Random Links</a>
@@ -107,10 +107,8 @@ <h2>Left Sidebar</h2>
107107

108108
<span class="image featured"><img src="images/banner.jpg" alt="" /></span>
109109

110-
<p>Phasellus quam turpis, feugiat sit amet ornare in, hendrerit in lectus.
111-
Praesent semper mod quis eget mi. Etiam eu ante risus. Aliquam erat volutpat.
112-
Aliquam luctus et mattis lectus sit amet pulvinar. Nam turpis nisi
113-
consequat etiam lorem ipsum dolor sit amet nullam.</p>
110+
<p> <a href="http://suave.stanford.edu/doxygen">SUAVE is fully documented through doxygen.</a> However, some starter high level documentation is available below.</p>
111+
114112

115113
<h3>And Yet Another Subheading</h3>
116114
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ac quam risus, at tempus

‎documentation/energy_nets.html‎

Lines changed: 108 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
-->
77
<html>
88
<head>
9-
<title>Code Style</title>
9+
<title>Energy Networks</title>
1010
<meta charset="utf-8" />
1111
<meta name="viewport" content="width=device-width, initial-scale=1, user-scalable=no" />
1212
<link rel="stylesheet" href="../assets/css/main.css" />
@@ -65,64 +65,115 @@
6565
<div id="content">
6666

6767
<!-- Content -->
68-
69-
70-
<h2 id="suave-code-style-guide">SUAVE Code Style Guide</h2>
71-
72-
<p>SUAVE is built on a slightly modified PEP8 style guide, with changes made to implement a data-oriented view of the code. To help support discovering code, the SUAVE folder structure explicitly mirrors the package structure. Flexibility of the package structure is important, so in general all objects live in their own file, with the same file name as the object name. In order to maintain a separation between Analysis and Data structures, there are often parallel package trees inside the main branches of the package, like SUAVE.Methods.Aerodynamics and SUAVE.Analysis.Aerodynamics. Where possible the names of fields that live in the SUAVE package are written out verbosely, avoiding jargon built on mathematical variable names or acronyms.</p>
73-
74-
<p>Templates for new methods and objects can be found in the SUAVE repo’s <a href="https://github.com/suavecode/SUAVE/tree/develop/templates">templates</a> folder.</p>
75-
76-
<h3 id="naming-convention">Naming Convention</h3>
77-
78-
<p>In terms of typography –</p>
79-
80-
<ul>
81-
<li><code class="highlight_code">any_variable_name</code> - lower case with underscore <br />
82-
This includes working variables and instantiated objects.</li>
83-
<li><code class="highlight_code">field_name</code> - lower case with underscore
84-
Any field of an object should be lower case.</li>
85-
<li><code class="highlight_code">function_name</code> - lower case with underscore</li>
86-
<li><code class="highlight_code">Class_Type</code> - upper case with underscore <br />
87-
The underscores are chosen here to permit the inclusion of acronyms if needed and to maintain symmetry with field name styling.</li>
88-
<li><code class="highlight_code">Package_Name</code> - upper case with underscore <br />
89-
For example folders within the SUAVE package.</li>
90-
</ul>
91-
92-
<p>In terms of naming –</p>
93-
94-
<ul>
95-
<li>Chunk similar field types under a containing field</li>
96-
<li>Bias names towards being specific</li>
97-
<li>Write out field name verbosely, but try to keep short</li>
98-
</ul>
99-
100-
<h3 id="development-life-cycle">Development Life Cycle</h3>
101-
102-
<p>As you develop new features for SUAVE, this is generally how you can expect your feature to evolve, in terms of its level of abstraction, and where it lives.</p>
103-
104-
<ol>
105-
<li>
106-
<p>Prototype <br />
107-
Either a new function or class. You may want to test these within a separate folder. If you are developing a new analysis approach, for example for aerodynamics or weights, you can usually start with a function. If you are working off of an object like a wing, you can abstract the objects as needed. Generally the lowest level object you’ll use is the SUAVE.Core.Data class. <br />
108-
A lot of development can be accomplished in a local environment.</p>
109-
</li>
110-
<li>Initial Integration <br />
111-
Once you’re comfortable that your new feature works robustly, and that it has been tested, it’s time to integrate it into SUAVE. Here are some tips for identifying where it could live.
112-
<ul>
113-
<li>SUAVE.Methods - if it’s a python function. Ping the <a href="http:suavecode.github.io/forum">forum</a> if you want to double check your decision!</li>
114-
<li>SUAVE.Analyses - if it’s an object that manages an analysis like aerodynamics</li>
115-
<li>SUAVE.Components - if it’s a data storage container for a vehicle component like a wing or landing gear</li>
116-
<li>SUAVE.Attributes - if it’s a data storage container for any other type of object, like atmospheres or water<br /></li>
117-
</ul>
118-
119-
<p>At this point you might want to initiate a pull request to contribute the code back to the main repository.<br /></p>
120-
</li>
121-
<li>Full-Blown Subpackage <br />
122-
As you write more code, and follow the SUAVE style of keeping one file per object, you will need to create a folder to contain a subpackage. This step may come later in the life of your code, so don’t rush to it if you don’t need the extra overhead.</li>
123-
</ol>
68+
<article class="content">
69+
70+
<h2 id="energy_nets">Energy Networks</h2>
71+
<p>
72+
Energy networks are really a fancy name for your propulsion system. The reason we call them a network rather than “engine” or the like is that it encompasses far more than that. These “energy networks” are the complex systems that future aircraft will incorporate that can reduce or eliminate fuel burn. For example if you have a hybrid gas-electric aircraft you don’t have just an engine. You have an engine, a motor, batteries, a generator, a gearbox, a propeller or ducted fan, wiring, electronics… and that doesn’t include the parts inside the internal combustion engine. Modeling these systems completely is essential in designing such a vehicle.</p>
73+
74+
<p>To do this we depart from the typical SUAVE structure of analyses and methods. This was done because we want to look at each component of the network individually. All components behave in their own ways. The purpose of the network is to link together every component in the system to work together.</p>
75+
76+
<h3 id="file-structure">File Structure</h3>
77+
<p>One of the biggest sources of confusion for energy networks is the file structure. The files for every part of a network are located at trunk/SUAVE/<strong>Components/Energy</strong>. Within that we have several subfolders.</p>
78+
79+
<h4 id="converters">/Converters</h4>
80+
<p>Converters are defined as component that takes energy or power from one form to another. It could be electrical to mechanical, or even chemical to mechanical, etc.. Examples in this folder include a motor, a solar panel, and the compressor section of a jet engine.</p>
81+
<h4 id="distributors">/Distributors</h4>
82+
<p>Distributors move power from one part of the network to another. The common use of this is an electronic speed controller for a small UAV.</p>
83+
<h4 id="networks">/Networks</h4>
84+
<p>This is where all the “Network” scripts that tie together all of the pieces are kept. Examples in here are a turbofan network.</p>
85+
<h4 id="peripherals">/Peripherals</h4>
86+
<p>Peripherals are items that rely on the network but do not produce thrust or power for the vehicle. For example, avionics require electricity which must be accounted for.</p>
87+
<h4 id="processes">/Processes</h4>
88+
<p>Processes are non tangible parts of a network that are necessary. For example the process is thrust. This function is useful for jet engines to combine and dimensionalize the final thrust once all the components are combined in the network.</p>
89+
<h4 id="storages">/Storages</h4>
90+
<p>Storages, for now, include batteries. However, in the future we could have fuel tanks here. Currently fuel is only handled as a mass variation.</p>
91+
92+
<h3 id="component-example">Component Example</h3>
93+
<p>Below is a simple example of the most basic energy component in SUAVE. All energy components are classes. The A solar panel is a converter since it converts a photonic flux calculated by a solar radiation model and converts it to a power.</p>
94+
95+
<div class="highlight_code"><div class="highlight_code"><pre class="highlight_code"><code># Solar_Panel.py
96+
#
97+
# Created: Jun 2014, E. Botero
98+
# Modified: Jan 2016, T. MacDonald
99+
100+
# ----------------------------------------------------------------------
101+
# Imports
102+
# ----------------------------------------------------------------------
103+
104+
# suave imports
105+
import SUAVE
106+
107+
from SUAVE.Components.Energy.Energy_Component import Energy_Component
108+
109+
# ----------------------------------------------------------------------
110+
# Solar_Panel Class
111+
# ----------------------------------------------------------------------
112+
class Solar_Panel(Energy_Component):
113+
114+
def __defaults__(self):
115+
self.area = 0.0
116+
self.efficiency = 0.0
117+
118+
def power(self):
119+
120+
# Unpack
121+
flux = self.inputs.flux
122+
efficiency = self.efficiency
123+
area = self.area
124+
125+
p = flux*area*efficiency
126+
127+
# Store to outputs
128+
self.outputs.power = p
129+
130+
return p
131+
</code></pre></div></div>
132+
133+
<p>These classes contain functions that simulate a process. Multiple functions can exist within a component. This component has defaults, inputs, and outputs. Defaults are provided that give the user an idea of what the fixed parameters of the component are. These values are set when initializing a vehicle. This is the recipe that all energy components are built off.</p>
134+
135+
<h3 id="network-scripts">Network Scripts</h3>
136+
<p>Network scripts are the link between these components. The network script allows you to reconfigure the connection between components to create your dream propulsion system. These must be logically created as components have set inputs and outputs. For example, you can’t magically go from a battery to a propeller without anything in between. Some knowledge of the inputs and outputs are necessary, however they’re generally quite intuitive. One interesting avenue for SUAVE is that you can create networks of networks.</p>
137+
138+
<p>The linking process works like this:</p>
139+
140+
<div class="highlight_code"><div class="highlight_code"><pre class="highlight_code"><code> # step 1
141+
solar_flux.solar_radiation(conditions)
142+
# link
143+
solar_panel.inputs.flux = solar_flux.outputs.flux
144+
# step 2
145+
solar_panel.power()
146+
# link
147+
solar_logic.inputs.powerin = solar_panel.outputs.power
148+
</code></pre></div></div>
149+
150+
<p>Notice the first step above is to calculate the solar radiation. Once the solar radiation is calculated the components are linked and step 2 can continue with the the power being calculated. From there a solar logic component will use that power.</p>
151+
152+
<p>The other main hallmark of a network is that they are called at every point in the mission to calculate the state of the system. Given some <em>conditions</em> data that defines the state of the vehicle the components must provide back to the mission being solved a thrust force and a mass rate. Other outputs can be stored back to conditions, however a thrust and a mass rate must be returned.</p>
153+
154+
<h3 id="vehicle-script-setup-of-a-network">Vehicle Script Setup of a Network</h3>
155+
156+
<p>Here we will provide a snippet of the turbofan setup for a B737.</p>
157+
158+
<div class="highlight_code"><div class="highlight_code"><pre class="highlight_code"><code># ------------------------------------------------------------------
159+
# Component 3 - Low Pressure Compressor
160+
161+
# instantiate
162+
compressor = SUAVE.Components.Energy.Converters.Compressor()
163+
compressor.tag = 'low_pressure_compressor'
164+
165+
# setup
166+
compressor.polytropic_efficiency = 0.91
167+
compressor.pressure_ratio = 1.14
168+
169+
# add to network
170+
turbofan.append(compressor)
171+
</code></pre></div></div>
172+
173+
<p>In the above example, a compressor is added to the network. The compressor is tagged as the low_pressure_compressor to distinguish it from the high pressure compressor. The polytropic efficiency and pressure ratio are set. Finall it is appended to the network.</p>
124174

125175
</article>
176+
126177
</div>
127178
</div>
128179
</section>

0 commit comments

Comments
 (0)