Skip to content

Latest commit

 

History

History
140 lines (113 loc) · 10.4 KB

2_Manual.md

File metadata and controls

140 lines (113 loc) · 10.4 KB
Raw

Back to main page

  1. Installation
    1.1. Binaries
    1.2. Source
  2. Users manual
    2.1. The interface
    2.2. Quick Tutorial: Running the DomeExplorer step by step

Top

1. Installation

The two programs developed for the paper "Assigning probabilities to non-Lipschitz mechanical systems",[1] can be downloaded from this git repository:

  • NortonDomeExplorer An object-oriented program written in Pascal with a simple GUI, which allows you to investigate the discretized version of the dynamics on Malament's mounds. (The discrete dynamics represents a point-mass placed at a chosen distance from the apex of a Malament's mound with a chosen velocity.)
  • PhaseSpace A small support program written in Fortran-95 to generate the vector field of the phase space. An additional gnuplot script is provided to combine the results into a single animation.

For both programs, 64-bit Windows executables are available, as well as their source code.

1.1. Binaries

The binaries are located in the bin folder of the repository. To install, just download the zip-file and unzip. The programs should run out of the box on a recent Windows system.

1.2. Source

For those interested in the inner workings of the programs, the source is available in the source folder. The programs can be compiled from source as well.

1.2.1. DomeExplorer

The DomeExplorer was originally developed using the Borland Delphi-compiler. Since then, the code was ported to Free Pascal using the free Lazarus IDE, and the provided source and support files should make it easy for compilation with Lazarus. (In theory, the source should still be compatible with the Delphi-compiler as we retained the Delphi format-file for the main form.)

  • Download all files in the source directory to a folder of your choice.
  • Open de Dome_v1_5_00.lpi-file using Lazarus.
  • In the Lazarus IDE go to Project -> Project Options and set the Target platform options in the Config and Target (under Compiler Options) to your specific architecture. (If you do not know what to choose, just select default and you should be fine.) Save these settings by clicking the OK button.
  • Compile the program by simply clicking the Run button (or F9).

In case you are using the Delphi-compiler, you will need to open the Dome_v1_5_00.dpr-file instead. As Delphi and Lazarus have slightly different definitions with regard to the positioning of components, the layout of the main form may need some final tweaking.

1.2.2. PhaseSpace

The PhaseSpace support program is written in Fortran-95 and can be compiled with a Fortran compiler.

  • Download the source file.
  • Open in your favourite coding environment such as Code::Blocks or Visual Studio Code where you have a fortran compiler available.
  • Compile and run the program. For post-processing the results into an animated gif, download the associated gnuplot script and run in with your gnuplot installation.

Top

2. Running the DomeExplorer program

2.1. Graphical User Interface

GUI_Layout

Different parts of the DomeExplorer GUI.

The DomeExplorer comes with a simple Graphical User interface (GUI), which allows one to setup and run simulations, as well as evaluate and store the results. The GUI contains three major parts:

  1. Simulation Settings: In this panel, specific details of the impending simulation are defined (cf. Tutorial for the specific settings and our paper for further details).
  2. Simulation & Processing: This panel contains a set of buttons related to both running the simulation and presenting the results.
  3. Plot Area: The results are graphically presented on the screen in this part. A color scale is included, showing the range of values presented.
  4. Menu: The picture of the results presented in the Plot Area can be saved as an image via File -> Save Image, and the program can be terminated either via File -> Exit Program or through the close button. The Help menu provides access to these online github information pages.
  5. Information: Depending on the simulation settings, running the simulation may take a while. To provide a visual feedback to the user (showing the program did not get stuck), a progress bar is provided at the bottom of the Plot Area. The run time used for the last simulation is presented below, while the total run time for all simulations in the current session is shown at the top of the screen.

2.2. Quick Tutorial: Running the DomeExplorer step by step

With the DomeExplorer, the phase space of initial values for the different Malament-mounds can be explored. In our paper, we discuss how the real space finite difference approach implemented in the DomeExplorer provides insight in the infinitesimal phase space of our Alpha-theory based model of the dynamics on the mounds. In the short tutorial below, all simulations settings will be discussed. This will enable you to run your own simulations, to either verify the results presented in the paper or to perform your own investigation into the specifics of the dynamics on Malament's mounds.

GUI_RunA

Setting up a simulation using the DomeExplorer GUI.

2.2.1. Setting up a simulation

All settings of a simulation can be found on the simulation settings panel, as indicated in the figure above.

  1. Initial values: The two initial conditions of the initial value problem at hand can be formulated in two ways. Either as the position at time t=0 and the position after a first timestep (option R0,R1, or using the notation of the paper: Rn,0,Rn,1), or as the position and velocity at t=0 (option R0,V0).
    Depending on the selection, the recurrence relation given in equation 4: Rn(m) = Rn(m-1)a/n2 + 2 Rn(m-1) - Rn(m-2), is initialised by two initial positions directly, or by an initial position and a velocity, which is transformed into two initial positions. In practice, for both modes the same recurrence relation is iterated. However, the graphical representation in the Plot Area will either present initial pairs (R0,R1) or (R0,V0) depending on the mode.
  2. Points 1 and 2, minimum and maximum values: The DomeExplorer evaluates the recurrence relation for each initial value pair corresponding with a single pixel in the 500x500 pixel Plot Area (i.e. 250 000 initial value pairs are considered). Point 1 refers to R0, while Point 2 refers to either R1 or V0. For each pixel, the initial value pair is calculated as a linear grid ranging in [min,max], as provided by the user. Note: As the pair (R0,R1)=(0,0) corresponds to the singular solution of the initial value problem, which can be tought of as the only point with an infinite T value (or within the context of the DomeExplorer a value of DeltaT*(Maximum # Iterations) ), it is best to exclude it from the chosen intervals. Otherwise it will dominate the color scale, and one ends up with a black Plot Area with a single red pixel.
  3. a value: The power in the initial value problem of Malament's mound, given by equation 1. Values are limited to the range ]0,1[. The special case of Norton's Dome is obtained by setting a=0.5.
  4. DeltaT: This is the discrete time step (also 1/n, cf. paper) used in the recurrence relation. When modifying this variable, it is important to note that there exists a scaling relation between the time step (1/n) and the Rn values: n-2/(1-a). In practice, this means that for Norton's dome (a=1/2), if one reduces DeltaT by a factor of 10 and the maximum R0,R1 values by a factor of 10 000, the exact same picture is obtained.
  5. Maximum # Iterations: The maximum number of iterations of the recurrence relation that are being calculated. Higher values provide a more accurate estimate of the delay time T, corresponding to the time the mass starts sliding off the mound (in the continuous case).

GUI_RunB

Running the simulation and selecting the results to present using the DomeExplorer GUI.

2.2.2. Running the simulation

Once the settings are selected, the simulation can be run and results visualised using the buttons present on the Simulation and Processing panel.

  1. Run Simulation: Pressing this button starts the simulation. Progess of the simulation can be tracked via the progressbar.
  2. Draw T: Once the simulation has finished, the Time used will be shown and the Plot Area will turn into a grey square. Then, the results for the
    delay time T can be visualised by pressing this button. The color scale indicates the largest and smallest values obtained in the entire presented phase space.
  3. Draw Flips/Draw Error Code: Support functionality which for each pixel indicates how many times the path starting with these initial conditions crosses the apex (Flips) or if any numerical errors were encountered (Error Code: 0=No error, 1=Division by zero, 2=Overflow, 3=Invalid operation, 4=Endposition >1060).
  4. Draw Endval/log(EndVal): Plot the final position (or log thereof) of a path starting with the initial conditions as given by the pixel.
  5. File->Save Image : The image presented in the Plot Area can be saved as an image.