AppMarkoPetek ReadMe
This directory contains a C# project for Visual Studio Express (2010 and above) which focuses on plotting resonance curves for oscillators, that can be described by ordinary differential equations. It has been written as a part of my graduate thesis (BA) and strives to conform to OOP standards set by its base library: the  Investigative Generic Library (IGLib). Since IGLib is not (yet) open source, only the necessary binaries are included.

The application can be run in one of the following ways (sorted from lowest to highest by the amount of effort required, which is of course proportional to the flexibility it provides):
  1. Running preset examples thorugh a one-click batch file.
  2. Running a modifiable script, allowing you to write and execute C# code without any third party software.
  3. Loading the project into VS Express and running it from there. Allows the modification of the whole project (instead of a single script file).
I shall describe each of these possibilities and hopefully show you a couple of interesting examples on the way. Before we start, you should unpack the compressed directory anywhere on your disk.

A quick peek: Preset examples

The included examples are intended to give you a quick impression of this project. Open the file "examples.cmd" in notepad (Right click > Edit). To try different available examples, you will need to uncomment lines one by one and then comment them back again. You can explore the examples yourself or follow this guide (recommended).

Example 1: Manipulating the graph. Simply remove the capital C at the start of the line that reads:
C 02DrivenPlotSolution
Save the file (ctrl + s) and run (double-click) the batch file examples.bat. A linear oscillator solution plot is shown. You can manipulate the plot in the following ways:
  • Pan the curve by holding down the middle mouse button (MMB),
  • Zoom in and out by scrolling the MMB.
  • Focus on specific areas by drawing a rectangle around it. Just hold the LMB and drag. This is useful for getting the entire curve to fill the graph pane without any gaps.
  • If you're zoomed in too much and don't want to scroll all the way back, just press RMB for the context menu to pop up and then choose "Set Scale to Default".

Make sure to add back the capital C (recomment the line) after you're done. The interpreter that reads the file ignores the lines with capital C in the begining. It also ignores empty lines, but be careful not to have any blank spaces in the empty line. Such a line will seem empty to you, but not to the interpreter - it will cause errors.

Example 2: Showcasing interpreter arguments.  The command that gets passed to the interpreter is the same as in example 1. This time you can modify some additional parameters of the linear oscillator:

  • The square of its eigenfrequncy (w0^2),
  • the damping coefficient (b),
  • starting time (start),
  • ending time (end),
  • solving method step size (stepSize)
  • whether individual calculated points are being plotted (Pnts) or an interpolated line (Lns),
  • point size or, in case of a line, line width (PntSize).

This example shows, that commands can also get passed to the interpreter with optional arguments (where these are implemented). As you have seen, the command 02DrivenPlotSolution has seven optional arguments, when none are specified the default values are used. The implementation is usually "all or none": If you decide to pass optional arguments, you must pass them all.

Example 3: A resonance curve for the linear oscillator. The curve that gets plotted is actually an analytical expression - the resonance curve for the linear oscillator can be written in a closed form. The blue dots on top are numerically calculated points. This way the accuracy of the method, that finds the steady-state amplitude of a single solution, can be observed. Zoom in to a single suspicious point and look for deviations (you shouldn't find any since the accuracy of the numerical method is set to one millionth of a unit). The optional parameter "samples" governs the number of numerical points that get calculated.

Example 4: Plotting multiple resonance curves on the same graph. This example does not allow any optional arguments. I haven't bothered to add them. Those will be available in the later examples, while plotting multiple curves for the nonlinear oscillator. All of the curves on the graph are analytical.

Example 5: The nonlinear magnetic oscillator in the chaotic regime. A solution in the chaotic regime is plotted. No periodicity is visible. When you close the graph, a second (phase space) graph is plotted.

Example 6: Nonlinear resonance curve and the disappearance of steady-state amplitude. At high driving amplitudes the slopes of the resonance curve of the magnetic oscillator become almost straight.

Try the following: change the driving amplitude parameter (M0/J) to 70 and run the app. The console will report, that the amplitude of the oscillations does not want to stabilise. If this ever happens to you, just input any letter in the console and press 'enter'. A plot of the solution as it appeared in the last iteration will be presented.

As you can see, the plot looks periodic. Nothing is wrong with the solution, it's just that the IterationLimitIncrement was set too low and the amplitude has not had the chance to stabilise. Simply close the plot and the calculation will continue for another 10 periods, however the amplitude will still not stabilise and the same message will apear. Input the ineteger '50' and press 'enter' to extend the iteration limit incrment to 10 + 50 = 60, the calculation will continue.

After a while the same message will appear again - even after extending the solution for 60 periods in each iteration, the solution did not want to stabilise. You should be suspicious. Instead of extending the IterationLimitIncrement any further, plot the last iteration (by entering any letter in the console). You will see that the solution is starting to wobble. This means, that the period of the oscillations has become a multiple of the driving period. You can make sure of this by measuring the period on the graph (measure the distance between the highest peaks) and comparing it to the driving period displayed in the console. In this case the period has tripled.

While such behaviour is still periodic, it is a sign that the oscillator will be entering the chaotic regime soon. And even though the function is periodic, the steady-state amplitude will not be found even if you extend the IterationLimitIncrement by a large number, because of the way the searching method works. Let's try it: close the plot and enter '1000' in to the console. A different message will appear, informing you, that an error has occured (oscillating period does not equal the driving period) and the last iteration plot will be shown automatically. The only way to fix this (in this case), is to close the program altogether (just close the console window) and enter more modest parameters (a lower M0/J), so that the steady-state amplitude exists everywhere.

However, sometimes this same message will be displayed (without prior requests to extend IterationLimitIncrement), but the plotted solution will look completely fine. In this case, only close the plot. You will be requested to enter a new InitialSolvingDepth. Enter a larger one and the calculation should continue without any problems.

Example 7: Phase scanned high driving amplitude nonlinear resonance. This is similar to the 6th example, only this time some points are plotted for different driving phases (at the start). At driving frequencies where two steady-state amplitudes exist, it matters how the driving is initiated - in what relation are the oscillator's motion and the driving force. The final steady-state amplitude depends on this.

The program plots multiple curves with the same parameters but different driving phases (gamma). The points of each curve are sligtly displaced from each other and colored differently, so that you can distinguish points with different driving phases. The relevant parameters for this are:

  • Starting gamma (st. gamma), which tells the gamma of the first curve.
  • Ending gamma (end gamma), which tells the gamma of the last curve.
  • The number of curves (gammaCurves) tells how many curves with different gammas reside on the interval defined by st. gamma and end gamma. The minimum is 1, which is just one curve at gamma = starting gamma.
  • The number of sample points in each curve (samples). Together with the width of the freqency interval and the number of curves, this determines the density of the plot.

The calculation time is proportional to the product of  gammaCurves*samples.

Example 8: Magnetic oscillator with a hard spring. This example plots multiple phase scanned curves. The color coding now only represents different curves and not different driving phases, as in the previous example (even though each curve is phase scanned). The behaviour of the Duffing oscillator is more prominent here.

For each curve the parameters:
  • st. gamma,
  • end gamma,
  • gammaCurves and
  • samples

have the same meaning as in the previous example and only effect a single visible (points of the same color) curve. The three new parameters are:

  • start M0/J, which tells the driving amplitude of the first curve,
  • end M0/J, which tells the driving amplitude of hte last curve,
  • NCurves tells how many curves reside on the interval specified by start M0/J and end M0/J and thus ultimately, how many curves are visible on the plot. The minimum is 1, which is just one curve at M0/J = end M0/J.

There is a reason, that the calculation begins at the curve with the highest driving amplitude: If on any of the curves the oscillator will enter the chaotic regime (where the steady-state amplitude disappears), it is going to be the highest one first. Therefore the user gets notified of the bad choice of end M0/J (too high) as soon as possible (instead of waiting until the end of the calculation just to learn, that it failed).

The calculation time is proportional to the product of  gammaCurves*samples*NCurves.

This concludes the preset examples showcase. There are more examples left in the examples.cmd file, Those were used in the graphs, which appeared in my thesis.


Things are run via the application's command-line interpreter.

In order to run the examples:

You can run the example command script file examples.cmd in which you uncomment (delete the Cs in front of commands) or modify the lines of interest and run the script by typing the following command in the command prompt (witht the current directory set to the directory containing the executable):

    guest_marko_petek.exe Run examples.cmd

You can also run individual commands directly by copying the desired command and its arguments to the command line, e.g.:

    guest_marko_petek.exe 07ResonanceCurveHarmonicFamily 0.2 1 5 100

Adding Custom Functionality via Script Files


   Additional flexbility is enabled by using the application's C# script interpreter. You can create your own script in C#, with custom commands added, and run these custom commands through the script. An example of such custom script is provided in the file script.cs, which you can extend with your own stuff. Since the script class inherits from the application's main script class, your extended script will already have all the existing commands installed.

In order to try the C# scripting functionality, you can run custom script commands by uncommenting the desired lines and running another command script file, the runscript.cmd:

    guest_marko_petek.exe Run runscript.cmd

As before, do not forget to uncomment the lines that you would like to run. In this command script file, there are commands that load the custom script file script.cs, compile it on the fly, and execute the specified script commands. This is done by the RunScript built-in command. You can also execute individual lines from the custom script file, e.g.

     guest_marko_petek.exe RunScript script.cs TestDerived arg1 arg2 arg3 arg3

In the command above, RunScript  is the name of the command that loads scripts and executes their commands, TestDerived is the name of a new command that is defined and installed by the script contained in script.cs, and arg1, arg2 and arg3 are parameter passed to the command. This command is not available in the existing application, therefore the following would not work:

     guest_marko_petek.exe TestDerived arg1 arg2 arg3 arg3  - does not work!

On the other side, the script contained in script.cs implements existing applicatino commands via inheritance, therefore these commands can be run either via the script or directly (since they are pre-installed on the application):

Running a pre-installed command through the custom script:
    guest_marko_petek.exe RunScript script.cs 07ResonanceCurveHarmonicFamily 0.2 1 5 100 

Running the pre-installed command directly by the application:
    guest_marko_petek.exe 07ResonanceCurveHarmonicFamily 0.2 1 5 100 

  Another command that is installed by the script file script.cs is ExampleDerived. This commands  plots a family of resonance curves for different damping coefficients as a 3D surface. You can run the coommand e.g. as follows:

    guest_marko_petek.exe RunScript script.cs  ExampleDerived  0.2 0.6 10 50

This command dose similar as the built-in 07ResonanceCurveHarmonicFamily3d, only that it is implemented in a script so that the user can change its function without needing to recompile the code. The majority of the implementation of what is behind the command is in the class AuxResonance that is defined within the script file, so you can modify its methods and changes will have immediate effect when you run the script command again.

  By using the custom script file (or creating a new one according to the rules) one can easily add new functionality to the application without having to have access to the source code. You can define new classes and methods within the file by using the complete object oriented syntax of the C# language and many of the classes contained in the linked libraries.

In order to install a new interpreter command by the script file (script.cs), you must follow these steps:
  1. Implement the command method within the script class (i.e. the first class in the script file).
  1. Define two constants - one for command name and one being a short help string.
  2. Install the command method on the interpreter.

Additional Information


The application's binary (guest_marko_petek.exe) is already in the root directory together with the libraries and can be readily run from this location. This is a console application controlled by a built-in command-line interpreter, therefore you must run it with command arguments that launch specific actions. A small number of examples are listed in the example command file (a file with the .cmd extension) within the root directory.

  For example, you can launch a particular demonstration 2D graphic plot by running the following command:

    guest_marko_petek.exe Shell Internal IG.Script.ScriptGraphics2dBase Graph CurvePlotLissajous 5 4

  This example is listed in the command file so command-line arguments can be just copied to the console where the application is run. Here "guest_marko_petek.exe" is the name of the application's compiled program, "Shell" is the command and the rest are arguments to this command. In the particular case, actually, "Shell" is the command that launches another nested command-line interpreter, "Internal" is the command of that nested interpreter that launches the internal (built-in) scripts, "IG.Script.ScriptGraphics2dBase" is a full name of such an internal script, "Graph" is a command built in this internal script, "CurvePlotLissajous " is parameter of this command that specifies which type of demonstration graph is launched, and 5 and 4 are two further parameters of this graph that define the final appearance of the plotted curve.

In the .cmd file, the first examples are related to Marko's graduate thesis. For example, the command

    guest_marko_petek.exe 07ResonanceCurveHarmonicFamily 0.2 1 5 100

will drat some resonance curves at different values of the dumping coefficient. The command

    guest_marko_petek.exe 07ResonanceCurveHarmonicFamily3d 0.2 0.6 10 50

does the similar thing, but instead of a familiy of curves a 3D surface plot is shown. See the .cmd file for more examples.

  Source code of the Marko's code is included in the code directory. Sources are in two project directories, namely the Guest_Marko_Petek_Lib and the Guest_Marko_Petek_App directory. The latter is the project that generates an executable and can be run. Both projects are loaded in Visual Studio or in Mono Develop if you open the file Guest_Marko_Petek_App/Bin_Guest_Marko_Petek_App.sln. Both solutions reference a number of dll-s from the directory containing the complete application.

  The IGLib depends on a number of third party libraries. Please read the IGLib's ReadMe file included in the root directory for information about these libraries and the IGLib itself.

More information about IGLib and the libraries on which it depends can be found on the library's home page:

http://www2.arnes.si/~ljc3m2/igor/iglib/

The complete code documentation can also be found at this address.