Technical Report Example

Reports Overview

For details regarding the ERE Report Requirements, see the ERE Report Requirements page.

This page contains the following sections:

• Lab 00 - An Example Submission
  1. Downloading an example laboratory source code and report typset in \text{\LaTeX}.
  2. Compiling the Fortran and gnuplot source code
  3. Compiling the \textbf{\LaTeX} Source Code
  4. Studying the Source Code
  5. Packing the files for Moodle Submission

An Example Laboratory Submission

An example laboratory, including \text{\LaTeX}, Fortran, gnuplot, and make source code, can be downloaded as tgz here. The makefile to unpack the files and compile the Fortran source code can be found here but is also included within the tgz in the src directory.

Note: You are not required to use \text{\LaTeX}.

A brief tutorial on how to explore these files using Windows and Cygwin follows. Note that the tools used include a POSIX command environment (Cygwin installation) and a \text{\LaTeX} package manager (MikTeX). Equivalent elements are readily available on ERE computers. They also can be made available by properly building a Linux or Macintosh workstation. For more information on software, see the Software Resources page.

Note: In the following instruction, $ indicates the command terminal.

1. Download and Unpack the Example Laboratory Source
   1. Create a directory to store the example project and change directories to your target destination:
      $ mkdir ~/Engr325
$ mkdir ~/Engr325/Labs
$ mkdir ~/Engr325/Labs/Lab00
$ cd ~/Engr325/Labs/Lab00
   2. Download the tar-zip file and makefile to your target directory
      
   3. unpack the contents using the tar command OR the script available in the makefile
      • Unpack using terminal commands:
        $ mkdir ./unpack
$ tar -xvf lab00_drs37.tgz -C ./unpack
        
        Notes about the tar command:
        • For more information about tar, type:
          $ tar --help
        • Three switches are passed to tar to specify its behavior:
          • -x specifies extraction
          • -v specifies verbose mode (report paths of extracted files)
          • -f specifies that the next specification will be the file to extract from
          • -C specifies that the output should be stored to the following directory
      • Unpack using the makefile by typing:
        $ make unpack
        

        

      Note that the command invokes the same sequence of commands performed manually above.
2. Compile and Execute the Fortran and gnuplot Source Code
   This step is not necessary as the results have been included in the tar-zip archive.
   However, the following steps can be used to reproduce the data from the Fortran source and images from the gnuplot scripts and data produced by the Fortran program.
   1. Compile the Fortran code using gfortran OR the commands contained in the makefile
      • Compile using terminal commands
      1. Switch to the unpack/src directory by typing
         $ cd ./unpack/src
      2. Type the following command at your terminal:
         $ gfortran main.f90 calcPowerIR.f90 -o main
         
         Notes about main.f90:
         • the file contains the main program
         • the main program contains an internal subroutine: calc_voltage_ir
         • the main file uses an external function: calc_power_ir
         Notes about calcPowerIR.f90:
         • the file contains the external function calc_power_ir used by the program main contained in the file main.f90.
         • the file is listed during the gfortran compile command so that the compiler can search its contents for the external function calc_power_ir
      • Compile using the makefile
      1. Switch to the unpack/src directory by typing
         $ cd ./unpack/src
      2. Execute the makefile by typing
         $ make
         
         Notes about make:
         • # is the comment character for the make language.
         • The make command looks within the makefile for the first target listed. In this case
           
           main : main.o calcPowerIR.o
           
           which tells make that we want to create a target file called main with prerequisites main.o and calcPowerIR.o
         • The recipe to make the target, main, is given by
           $(FC) $^ $(OFLAGS) main
           where
         • $(FC) is a variable used to store the Fortran compiler (gfortran),
         • $^ is the special character that lists all prerequisites (main.o and calcPowerIR.o) listed for the target (main),
         • $(OFLAGS) are the list of compiler flags specified in the variable defintion: OFLAGS = -o, and
         • main is the target output file required since the -o flag is specified.
         • The target file will only be recompiled if changes are detected in any of the prerequisite files. The prerequisite files are also investigated by the make command.
         • If the prerequisite files are missing or altered since the last compilation, the make command will seek other targets in the file allowing the creation or recreation of the prerequisites from the listed prerequisites and recipe listed for the prerequisite-target. See the makefile's targets for main.o and calcPowerIR.o as an example.
         • For more information on make see the make tutorial
   2. Execute the Fortran program by typing ./main at the terminal
   3. Test to see if gnuplot is installed on your terminal by typing
      $ gnuplot
      
      This should change your terminal to the gnuplot command line. To exit type
      gnuplot>
      
      To exit, type exit and return
gnuplot> exit
      
      There is currently a gnuplot library error that does not allow gnuplot to run these scripts on the Linux side of ERE labcomputers. If this error is resolved, the following should work.
      
      To execute the gnuplot scripts simply type the following at the command terminal.
      1. ./voltage.gnu to produce ../output/voltage.pdf
         from the data in ../output/voltage.dat
         See voltage.gnu for more details.
      2. ./power.gnu to produce ../output/power.pdf
         from the data in ../output/power.dat
         
   
   The gnuplot script provided uses the shabang-interpreter specification
   #!/usr/bin/gnuplot
   at the first line of the script so that the interpreter does not need to be included in the command
   See the gnuplot documentation and the source code provided for more information.
3. Compile the \textbf{\LaTeX} Laboratory Report
   1. Once all files are available, the user should change the working directory to doc. Here you'll find one tex file and one jpg image file used for the cover photo.
   2. The command pdflatex should be available at your terminal. Try it! If it's not installed, consult the literature on how to install a \textbf{\LaTeX} package manager for your operating system.
   3. Compile the document by typing
      $ pdflatex lab00_drs37.tex
      
      
      
      Note: The harpoon.sty file was not available on the ERE Linux distribution. This missing style file will produce an error during compilation. To resolve this issue, comment out the line
      \usepackage{harpoon}
      by typing a % sign in front of the usepackage command - no commands from the harpoon package is used in this document.
      
      If you perform this command on a Linux machine, you may receive a pdflatex compilation error due to a missing file: makefile(.)
      This error would be reported in the pdflatex progress. To resolve this issue, delete the period after makefile on line 359 of lab00_drs37.tex and try again.
      
      Old Code:
      \includecode{../src/makefile.}{make}\newpage
      
      New Code:
      \includecode{../src/makefile}{make}\newpage
      
      The output is stored in lab00_drs37.pdf. The output file is the input file name with a .pdf instead of a .tex extension.
      
      and retry to compile.
      
   4. Take a look at lab00_drs37.pdf and try to match the contents in the document to the code written in lab00_drs37.tex
      
      I've received some reports that the permissions may not allow you to read the pdf. The terminal command chmod can resolve the issue for us. chmod changes the permission of target files. While in the doc directory try typing:
      $ chmod 755 *
      
      This will provide full access to all files in the directory for all users. See the chmod documentation for more details. Use the --help switch by typing
      $ chmod --help
      
      Notes about lab00_drs37.tex:
      • % is the comment character in \text{\LaTeX}
      • \text{\LaTeX} documents contain two sections:
        1. Preamble: used for specifying the document class, formatting, custom definitions, and custom functions used in the document.
        2. Body: where the content of the printed document is entered
      • Preamble
        • the example document uses a large number of \text{\LaTeX} packages to enable inclusion of images, special formatting, math typefaces, embedded files, automatic inclusion of source code, hypertext referencing, bookmarks, custom names, custom vector symbols, and more.
        • Each package has detailed documentation available on the internet. Simply search the package name with the LaTeX keyword.
        • Custom definitions are included allowing the centralization of things like the author's name, lab number, etc. at the top of the document. These definitions are reused several times in the document allowing for changes throughout the document to occur in one location. Learn more about definitions by reading any of the many online resources for \text{\LaTeX}
        • Custom commands, or macros, are included in the file that make typesetting mathematical expression faster and more compact.
        • This document uses the fancy heading package which requires specifying the different sections of the header and footer.
      • Body
        • The body of the document is included between the commands:
          \begin{document} ... \end{document}.
        • The document is broken up into sections using the \section and \subsection commands.
        • \begin{figure}[H] ... \end{figure} commands create a figure environment.
          • The [H] at the end of the \begin{figure} command forces the image to stay at the place the figure was included in the document, otherwise the figure would "float." The float package allows us this functionality.
          • When compiled, the \caption command is used to build a list of figures in the document.
          • The \label command is used to specify a referencing label for the image. This allows automatic updating of figure numbers and the references to them.
        • \begin{table}[H] ... \end{table} commands create a table environment.
          • \begin{tabular}{} ... \end{tabular} manually specifies a table. See the command's literature.
4. Study the Source Code
   Once you've successfully compiled the \text{\LaTeX} document, you should look into the \text{\LaTeX}, Fortran, gnuplot, and make source code provided to understand how this all works. Use the notes provided as a guideline. Additional details about software elements can be found on the Software Resources page.
   
   To report errors in this tutorial or ask additional questions, please send an e-mail to doug<at>humboldt.edu
   
   Note: The \text{\LaTeX} laboratory report template provided can be adapted to the required project report format.
5. Packing the file for Moodle submission
   • As you've likely noted, this example laboratory consists of multpile files. To submit this assignment to Moodle, we will need to package all relevant content into a single file (tar-zip) and upload to Moodle.
   • To tar-zip the relevant files, you can either use terminal commands OR use the pack command in the makefile.
     • Using terminal commands to package the files
     1. Change directory to Lab00/src. If you are starting in the Lab00/doc directory, simply type at the command line:
        $ cd ../src
        
     2. Make a script of the program compiling and running. Use the following commands to create the script:
        $ script script.txt
$ gfortran main.f90 calcPowerIR.f90 -o main
$./main
$ exit
        
     3. Switch to the top of the unpack directory. From the src direcotry type:
        $ cd ..
     4. Use the following commands to create the tar-zip.
        Note: <user> is a placeholder for your user ID.
        $ tar -czf lab00_<user>.tgz ./src/script.txt ./src/main.f90 ./src/calcPowerIR.f90 ./doc/lab00_<user>.pdf
     5. Submit your tar-zip archive to Moodle