Report requirements
Project reports must satisfy all of the requirements listed in the following categories:
These requirements may evolve during the semester.
AIAA Format
| Label | Requirement |
|---|---|
| A2 | There should be no additional lines between paragraphs. |
| A3 | All paragraphs should be indented the same amount, exactly the amount specified in the template. |
| A4 | Symbols in the nomenclature must be listed with units. |
| A5 | You must choose either the word or latex template from AIAA and follow it exactly. |
| A8 | All equations must have one blank line above and below them. |
| A15 | There must not be watermarks or annotations (e.g., revision marks that result from tracking changes in Microsoft Word) that are not part of the AIAA template. |
| A17 | Code must be displayed as text in a code block (i.e., set apart from the rest of the text in a monospace font) and not, for example, as a screenshot or as text mixed in with the rest of the report. (Think carefully before you include code in your report, however — it is often better to share code in a different place, for example in the notebook that you are asked to submit as one of your final deliverables). |
| A23 | All text in the body of your report must be fully justified (aligned evenly along both the left and right margins). |
| A24 | Sections must be ordered as in the guidelines (consistent with the AIAA template): Abstract, Nomenclature, Introduction, Theory, Experimental Methods, Results and Discussion, Conclusion, Appendix, Acknowledgements, and References. |
| A25 | The title of each section (other than the Appendix, Acknowledgements, and References — as well as the Abstract, which has no title) should be preceded by a Roman numeral corresponding to its order in the document. |
| A26 | Each page must be numbered. |
| A28 | Each reference must be numbered. |
| A29 | All body text must be in the same font size. |
| A31 | Fonts for all text in the report (including section titles, for example) must be exactly the same — in terms of the name, size, and style — as in the AIAA template. |
| A36 | There must be an empty line between figure captions and paragraphs |
| A37 | There must not be an empty line between headings and the following text. |
| A43 | Unlike all other sections, (1) the Abstract must be neither titled nor numbered, and (2) the Appendix, Acknowledgements, and References must not be numbered. |
| A45 | Reports must be at most six pages. |
| A46 | Both the right and left margins of the abstract must be half an inch larger than the rest of the document, exactly as in the template. |
| A47 | Abstract text must be bold, exactly as in the template. |
Mathematics
| Label | Requirement |
|---|---|
| M1 | All equations should be numbered in parentheses flush right. |
| M2 | The number of significant figures (or digits after the decimal place) should be both consistent and reasonable. |
| M3 | Inline equations must not be taller than the standard line height. If they are, make them block equations. |
| M4 | Use symbols for Greek letters rather than spelling them out. |
| M5 | Write variables side-by-side to denote multiplication. Ex: (C = AB instead of C = A*B). |
| M6 | Variables should be italic. |
| M7 | Put indices, names, etc., of variables in subscripts or superscripts. |
| M8 | Words in equations — e.g., subscripts, superscripts, or words like “and” between different expressions — should be non-italic. |
| M9 | Remove unnecessary space between the equal sign and the variables/constants to maintain proper alignment and formatting. |
| M10 | Dots should be centered over variables, not also over subscripts or superscripts. |
| M11 | Variables should be denoted by symbols and not by names that are used in python code. |
| M12 | Names of units (whether or not they are abbreviated) should be non-italic. |
| M13 | Names of matrices or vectors should not appear in brackets (only the elements of matrices or vectors should appear that way). |
| M15 | Put a space between the number and the unit. |
| M16 | Units are incorrect. |
| M17 | Each matrix must be enclosed by a single pair of square brackets. |
| M18 | Numbers, whether in the text or Nomenclature, must be presented with units (e.g., “1.5 m” and not just “1.5”), unless these numbers are dimensionless, are elements of a matrix or vector, or are in a table that gives units in the row or column header. |
| M21 | Use “r x c” (where the “x” is a “\times” in latex) instead of “r * c” when describing the size of a matrix. |
| M22 | Use an overdot notation instead of a prime (apostrophe) for time derivatives. |
| M24 | Transposed matrices need a T superscript. |
| M31 | Multiplication of units must include either a dot or space between variables (e.g., ft • lb or ft lb not ftlb or ft*lb). |
| M33 | Use appropriate notation (e.g., summation) instead of writing equations in text form. |
| M34 | Be consistent in your use of bold font for variables. One option is to not use bold font for any variables. Another common choice is to use bold font for matrices and vectors and to use non-bold font for scalars. (Functions like “sin” or “cos” are never in bold font.) You must choose an option and stick to it. |
| M35 | Parentheses must be closed. |
| M38 | There must be enough space between elements of a matrix or vector so that it is clear they are separate elements and are not variables being multiplied. |
| M39 | Either present eigenvalues as elements of a list (e.g., “p = [-1 + 2j, -1 - 2j]”) or as separate, named values (e.g., “s_1 = -1 + 2j \qquad s_2 = -1 - 2j”) and not as elements of a vector (e.g., “p = \begin{bmatrix} -1 + 2j & -1 - 2j \end{bmatrix}”). |
| M40 | Equations must not have typos. |
| M42 | Inline equations must not be taller than the standard line height. If they are, make them block equations. |
| M43 | Equations must be centered. |
| M44 | Equations must be referenced as “Eq.” within a sentence, or as “Equation” at the beginning of a sentence. |
| M45 | Do not (1) use the same variable to denote two different things or (2) use two different variables to denote the same thing. |
| M46 | A subscript must be used to denote substitution of equilibrium values into a Jacobian matrix (e.g., $\frac{\partial f}{\partial m}\biggr\rvert_{m_e, n_e}$ not $\frac{\partial f}{\partial m}\biggr\rvert m_e, n_e$). |
Style
| Label | Requirement |
|---|---|
| S1 | Spell out “and” rather than using an ampersand (i.e., the symbol “&”). |
| S2 | Use of apostrophes must be correct (e.g., before the “s” for singular possession, after the “s” for plural possession, etc.). |
| S3 | Do not use run-on sentences. |
| S4 | Do not use sentence fragments. |
| S6 | Only indent the first line of each paragraph. |
| S7 | Block equations are part of the text and are subject to the same rules for grammar and punctuation as everything else. |
| S9 | Capitalization must be correct (e.g., do not capitalize words unnecessarily, always capitalize the first word of a sentence, etc.). |
| S10 | Spelling must be correct. |
| S11 | What comes before a colon or a semicolon must be a complete sentence. |
| S13 | Verb tense must be correct. |
| S19 | The word “this” or “they” should be followed by a noun (e.g., “this robot” or “this result”). |
| S20 | Do not denote items in a list with a “/.” |
| S21 | Capitalization should be consistent. |
| S33 | Quotation marks should not be mismatched. |
| S34 | Each sentence must end with a period. |
| S42 | Whole numbers under ten should be spelled out (e.g., “two” instead of “2”). |
| S43 | There must be no missing words or extra words (e.g., “We did an experiment.” not “We an experiment.” or “We performed did an experiment.”) |
| S46 | There should be no extraneous words that compromise the meaning of the intended statement (e.g. “I had to go at to the store.”) |
| S48 | There should be no repeated punctuation (e.g., “This sentence ends in two periods by mistake..”). |
| S57 | Nouns and pronouns should agree in terms of grammatical number (e.g., “robot” with “it” or “robots” with “they”.) |
| S58 | Block equations must be part of a sentence. (On its own, a block equation would be a sentence fragment.) |
| S59 | Sources referenced in-text must follow the formats of “It is shown by Smith [4] …”, “The effect of … should be taken into account [4].”, “For example, see Refs. [6, 7].”, “Further documentation can be found in [8-10].”, or “This procedure was proposed by Gelb [11, p. 250].” |
| S60 | Use “Section X” when referring to a specific section. |
| S61 | There must be no missing space: words in a sentence must be separated by a space, there must be a single space after the end of a sentence, there must be a space between a parenthetical remark and the preceding word, there must be space between items (i.e., after each comma) in a comma-delimited list, there must be a space between words and citations (e.g., “blah [3]” not “blah[3]”), etc. |
| S62 | There must be no extra space: there must be only a single space and not a double space after the end of a sentence, there must be no space between punctuation (e.g., a comma, period, colon, semicolon, etc.) and the preceding word (e.g., “blah.” not “blah .”), etc. |
Figures and Tables
| Label | Requirement |
|---|---|
| F1 | Plots must provide useful information (e.g., do not show a plot of a quantity that is constant or is always zero). |
| F2 | Each figure or table must be referenced at least once by number in the text. |
| F3 | Each figure or table must have a caption and a number. |
| F4 | Legends must not cover up plots or obscure results. |
| F5 | Labels in legends should be descriptive names (text) or symbols (math) and should not be code variables (e.g., with underscores). |
| F6 | Figure captions must be written as one or more complete sentences that follow the same rules for grammar and punctuation as everything else. |
| F7 | Plots should not have titles — descriptions should go in captions or subcaptions. |
| F9 | The caption of a figure must be underneath the figure rather than above the figure. |
| F10 | The caption of a table must be above the table rather than below the table. |
| F11 | Table captions must be “definitive titles” (e.g., “Table 1 Buckling results for blade-stiffened panels”). In other words, unlike figure captions, table captions must not be a complete sentence, must have only the first word capitalized, and must have no period or other punctuation at the end. |
| F12 | Use both different colors and different line styles to distinguish between lines in the same plot. Doing this makes plots readable for people with color blindness and makes plots more readable for everyone else. |
| F13 | All lines in a plot should be labeled. |
| F14 | If two different lines in a plot show upper and lower bounds on the same quantity (e.g., minimum and maximum torque), these lines should have the same style and should correspond to only one label in the legend (rather than two labels, one for each line). |
| F15 | Side-by-side plots — particularly ones that show results for comparison (e.g., results for different choices of initial condition) — should be the same size and should have the same axis limits. |
| F16 | Subfigures should be referred to by letter (e.g., (a), (b), etc.) and not by position (e.g., “left” or “right”). |
| F17 | Plots must be either vectorized images (e.g., PDF or SVG) or high-resolution rasterized images (e.g., PNG) and must not be screenshots or other low-resolution images. |
| F18 | References to figures and tables in the text should be by number (e.g., “Fig. 1”, or “Figure 1” at the start of a sentence) and not by location (e.g., “the above figure”). |
| F19 | Each figure or table must be numbered in the order of their appearance in the document. |
| F20 | The font size of all text in a plot (e.g., legends, axis labels, etc.) should be both readable and close to the standard body text size. |
| F22 | The font of figure and table captions must be bold, but otherwise should be the same size and style as the standard body text. |
| F23 | Units must be provided, either in a legend or an axis label. |
| F24 | The caption of a table must be centered. |
| F25 | References in the text should not be made to figures or tables that do not exist in the report. |
| F26 | References in the text should be made to the figure or table that contains the information being discussed. |
Content
| Label | Requirement |
|---|---|
| C1 | When describing performance, either use words that are widely understood to have a precise technical meaning or provide a definition yourself (i.e., say what you mean). |
| C2 | Use an italic upper-case “K” to denote the gain matrix for linear state feedback (unless you clearly explain some alternative notation). |
| C4 | Specify both the “of what” and “with respect to what” when talking about derivatives (including Jacobians). |
| C5 | The abstract should provide a summary of key quantitative results (with actual numbers) that were obtained. Placeholders can be used in drafts when final results aren’t available yet. |
| C6 | Do not provide unnecessary information about the computer, programming language, application, etc., that you used for implementation. |
| C7 | Theory should be in the Theory section, not also in the Introduction, the Experimental Methods, etc. |
| C8 | Provide enough information about the system to be controlled — including a clear description, a schematic, and a citation, for example — so that readers will understand even if they have not previously seen or worked with that system. Make sure all information provided is correct. (Note that it is usually best to describe the system exactly once, early in your report.) |
| C9 | Linear state feedback should be negative (i.e., “-Kx” and not “Kx”) unless you clearly explain why you are taking a non-standard approach. |
| C10 | We strongly recommend that you follow the four-step process described on the course website (see Reference > State space models > How do I put a system in state space form?) to linearize the equations of motion. The order of this process, in particular, is important. For example, you cannot define the state “x” or input “u” of the state-space model without having first chosen an equilibrium point, because “x” and “u” are defined in terms of this equilibrium point. If you choose not to follow this four-step process, you must explain clearly and justify rigorously whatever alternative process you are using. |
| C11 | Our method of deriving a state space model requires linearizing about an equilibrium point that is both constant and known in advance. Any other method should be clearly explained and justified. |
| C13 | Be specific enough about your methods so that another engineer could reproduce them. |
| C14 | Only the real or imaginary part of an eigenvalue can be positive or negative, not the eigenvalue itself. |
| C15 | You must justify your choice of gain matrix. |
| C23 | Variables must be defined in the text before they are used, even if they are listed in the Nomenclature (that list is for reference — it collects all of the variables that are defined and used in the rest of the report). |
| C24 | Use specific criteria instead of subjective terms (e.g., good or bad, best or worst, etc.). |
| C30 | When plugging numerical values into a symbolic expression, either say what those values are (i.e., give the actual numbers) or provide a reference to where those values can be found (e.g., the course website, a github repository, code submitted as one of your final deliverables, etc.). |
| C33 | Our convention is to denote the state and input of the nonlinear system by “m” and “n” and to denote the state and input of the linearized system (i.e., the state-space model) by “x” and “u”. If you use a different convention, you must make that clear. |
| C36 | Either clearly describe and rigorously justify any methods used or cite a reference that does this for you. Note that it is almost always better to cite a reference, if the method is not new and if a reference is available. In particular, it is likely impossible to provide a complete description of a method like eigenvalue placement or LQR in the context of a 6-page report (the reference page on the course website provides a minimally complete description, which is already too much for you to include) — use a citation for these sorts of things. |
| C37 | Nomenclature must list all variables used in the report along with their units (unless a variable is dimensionless). |
| C40 | Do not define any given variable more than once in the Nomenclature. |
| C45 | If eigenvalue placement is used, you must clearly state and justify your choice of eigenvalue locations. (Eigenvalues must have negative real part and — if they have non-zero imaginary part — must be in complex conjugate pairs, but otherwise their location is an engineering decision. They could have zero or non-zero imaginary part, they could have a real part that is more negative or less negative, they could all be at the same location or could be at different locations, etc.) |
| C46 | The gain matrix must have as many rows as there are inputs and as many columns as there are states. |
| C47 | Experiments must be described in enough detail that they could be understood and repeated by a colleague. |
| C49 | The length of each simulation must be stated. |
| C50 | The initial conditions for each simulation must be stated. |
| C51 | While it may be appropriate to describe experiments that were used to iterate on your control design, there must be a comprehensive set of experiments that validate your final control design (where “final” means “after you have stopped making changes”). |
| C52 | Quantitative results from many experiments — presented in figures and/or tables — should be used to support claims made in your report, for example that your controller “works” (however you have chosen to define that word). Results from only one experiment or a small number of experiments do not provide sufficient evidence in general. |
| C53 | You should make clear what “success” means (i.e., what it means for your controller to “work”), for example by providing a quantitative measure of performance. |
| C54 | Words like “optimal,” “optimized,” “optimization,” etc., must not be used without first defining a quantity that is being maximized (e.g., a reward) or minimized (e.g., a cost). |
| C60 | The number of simulations performed must be stated, particularly if these simulations are used to produce aggregate results (e.g., mean or standard deviation). |
| C65 | Experimental Methods should describe the experiments that were performed and should not present results. Results and Discussion should present the results that were obtained and should not describe the experiments. |
| C69 | Be specific about methods used. (For example, instead of saying that you “did calculations,” say what you calculated and how you did it. Similarly, instead of saying that you “wrote code,” say what it was that you implemented.) |
| C71 | Equations must be consistent with what is described in the text. (For example, if some eigenvalues in an equation do not have negative real part, the text should not claim that all eigenvalues have negative real part.) |
| C73 | If you present a result in Results and Discussion, you must describe the experiment that produced it in Experimental Methods. If you describe an experiment in Experimental Methods, you must present the results of that experiment in Results and Discussion. |
| C75 | Clearly define non-standard functions before they are used (e.g., “\lambda (A - BK)”). |
| C76 | If you apply LQR to design a controller, you must state and justify your choice of weights Q and R. (Remember that LQR computes K given Q and R — it doesn’t compute Q and R or otherwise tell you what these weights should be.) |
| C78 | If any work other than your own is used in your report (i.e. lecture notes, code, course website, textbook, articles, etc.), it must be cited in the References section. |
| C79 | Sources listed in the “References” section must be referenced within the text at least once. |
| C80 | The (nonlinear) equations of motion that describe the system to be controlled must be correct. If these equations of motion are not already in standard form, then the process of putting them in standard form must be described and the result must be correct. |
| C81 | The equilibrium point must be correct. That is, assuming the equations of motion are written in standard form as $\dot{m} = f(m, n)$, the equilibrium point must be a choice of $m_e$ and $n_e$ for which $f(m_e, n_e) = 0$. |
| C82 | The definition of the state x and the input u in the state-space model that is produced by linearizing the equations of motion about an equilibrium point must be correct. That is, assuming the equations of motion are written in standard form as $\dot{m} = f(m, n)$ and given a choice $m_e$ and $n_e$ of equilibrium point, the state must be $x = m - m_e$ and the input must be $u = n - n_e$. |
| C83 | The matrices A and B that define the state-space model that is produced by linearizing the equations of motion about an equilibrium point must be correct. While it may be hard for readers to know if the numbers in A and B are exactly right (without looking at your code and reproducing your results), it is often easy to know if these matrices have the right size and shape, if these matrices have zeros in the right places, etc. — double-check these things. |
| C84 | The elements of the state $m$ and input $n$ of the (nonlinear) equations of motion, when written in standard form as $\dot{m} = f(m, n)$, must be clearly defined. |
| C85 | The rank of the controllability matrix (or, some alternative measure like its determinant or its smallest singular value) must be stated, and the correct conclusion must be drawn about whether or not the state space model is controllable. |