Numerical C Code - Tutorial


Section 1

Untar the package of sample C on the class website named 'C.tar'. This will create a subdirectory named 'C' under the current directory. Change into that C subdirectory. Use 'less' to inspect the contents of the file 'damped_oscillator_1.c' from the C source file package:

	less damped_oscillator_1.c

Follow this simple C program that is written to send data points in the form of time and amplitude coordinate pairs for a damped harmonic oscillator system to the process standard output. Compile this source code into an executable binary file with the shell command:

	gcc -Wall damped_oscillator_1.c -o damped_oscillator_1 -lm

Note that the last option on this command line reads 'dash' 'ell' (as in a lower case letter 'L' character, not the numeral 'one') and an 'm' character. The line above is a command for gcc, the 'Gnu compiler collection', to compile the source file 'damped_oscillator_1.c' into an output executable file named 'damped_oscillator_1', and using the 'm' library, which is the standard math function library, to supply needed trigonometric and exponential functions that are called in the C code. The '-Wall' option enables gcc to display warnings of all types as it parses the C source code. This helps diagnose potential problems with your code. Now at the shell prompt, run the compiled program and save its standard output:

	./damped_oscillator_1 > damped_oscillator.dat

Verify that the data file was written properly with:

	less damped_oscillator.dat

Start an interactive gnuplot process and plot the data as with last week's tutorial. Hint: start a second shell terminal and cd into the same C working directory to run

        gnuplot

This will let you go back and forth between the two terminals, one used to edit, compile and run C code, and the other in which to keep a gnuplot process running to plot various data files generated by the C programs. With a gnuplot command:

	plot 'damped_oscillator.dat' using 1:2 with lines

You should see a plot that looks like:

Now back in the first terminal window still running the bash shell, prepare to edit the C source code by starting a gedit process running in the background with:

	gedit damped_oscillator_1.c &

Note the ampersand character '&' appended to this command line. This will cause the command to be run in the background but return to a bash shell prompt to allow bash shell commands for compiling C code to continue to be run in the terminal. This command starts a gedit process to edit the C source code, and you should see a separate gedit window pop up with the damped_oscillator_1.c source code ready for editing. Use the editor to change the natural frequency of the oscillator from 2 π radians per second to π radians per second, the resonator Q from 10 to 20, and the maximum time value over which the program simulates the oscillator from 10 seconds to 20 seconds. Save the source code file in the editor and recompile the new source code with the same gcc command as before:

	gcc -Wall damped_oscillator_1.c -o damped_oscillator_1 -lm

Rerun the newly compiled executable file with a similar command as before, but note the new redirection characters '>|'. This will overwrite the previous data file with the data from the new program:

	./damped_oscillator_1 >| damped_oscillator.dat

Now moving over to gnuplot, either by pressing the replot button on the graphics window or by typing 'replot' into the terminal running the gnuplot process, update the plot with the new data. Note how the new parameter values change the oscillator behavior and the maximum plot time.

Return to the gedit window and make an enhancement to the source code. Add a declaration of another double precision floating point variable named 'amp'. In this variable you will compute the exponential amplitude envelope function that establishes the maximum oscillator displacement so that it may be plotted along with the oscillator displacement. Inside the time loop add a new arithmetic assignment statement that sets the 'amp' variable to the exponential factor. Add the 'amp' variable to the printf statement so that a third data column is output. Save the edited source code, recompile the program and rerun the executable file. Inspect the new output data file with:

	less damped_oscillator.dat

to ensure the third column of data values is present. Replot the new data file in gnuplot, with both the displacement versus time and the amplitude envelope function versus time functions plotted together on the same graph. You should see a plot that looks like:

Section 2

Browse through the next source code file with:

	less damped_oscillator_3.c

Note the use of command line arguments in this source code to supply parameters values to the oscillator simulation. Compile the next source code file into an executable binary file with the shell command:

	gcc -Wall damped_oscillator_3.c -o damped_oscillator_3 -lm

First display the programs help text with a command line with no arguments:

	./damped_oscillator_3

Next run an oscillator simulation with the original nominal values supplied on the command line:

	./damped_oscillator_3 1.0 10.0 10.0 > damped_oscillator.dat

Replot this new data file using the running gnuplot process. Now try some different oscillator parameter values on the command line, without having to recompile the source code, such as:

	./damped_oscillator_3 2.0 5.0 5.0 > damped_oscillator.dat

and replot. Note that compared to the plots produced in Section 1, these plots are more angular and less smooth. Why?

In order to improve the smoothness of your plots, modify the program to add a fourth command line argument to allow you to set the time step of the program loop independent of the maximum time. Be sure to make appropriate changes to the section of code that displays the 'help' text. Then try another plot with:

	./damped_oscillator_3 1.0 10.0 10.0 0.01 > damped_oscillator.dat

Section 3

Browse through the next source code file and the argument sweeping helper function with:

	less damped_oscillator_4.c
	less sweep.c

Note the new oscillator source code makes use of the helper function and its attendant include file sweep.h to sweep the simulation time. The function 'osc' that computes the oscillator amplitude as a function of time is in the main program file, and a pointer to this function is passed to the sweep function. Compile this version with:

	gcc -Wall damped_oscillator_4.c sweep.c -o damped_oscillator_4 -lm

Note including the source code file for the sweep function on the compile command line to be linked with the main program into one output executable file. Try this version with:

	./damped_oscillator_4 2.0 5.0 5.0 0.01 > damped_oscillator.dat

and replot.