SMN v5.1 ParticleDraw Help

by John Ringland [] (2006-02-26)


The Program:
Getting Started:
The Simulated System:
Interacting with the Simulation: especially the hotkeys.
Billiards Mode:
Model Parameters:
Trouble Shooting:

The Program:

Unzip the folder then run "ParticleDraw.bat".

In Windows: If you wish to place an icon on your desktop right click and drag the file "ParticleDraw.bat" onto your desktop and then from the menu choose to create a shortcut.

This is only a very simple example of some of the core functionality of SMN. Fututre versions will become gradually more general, flexible and will exhibit advanced system analysis and simulation features.

The Simulated System:

The system consists of a series of particles scattered in space. One can interact with these particles and thereby construct systems of particles. The particles interact via a gravitational force and an electrostatic force. The simulation is not meant to be physically realistic to the n'th degree, it is just an example model to illustrate the core simulation capacities of the SMN modeling paradigm and it happens to make an interesting drawing program as well as other things.

These systems of particles have been augmented with an associative network. That is, particles can be 'associated' with other particles. This is part of a transitional phase whereby the Particle Simulator forms part of a new "topic map" program for the creation of topic maps (or concept maps or mind maps). When two particles are associated there is a line drawn between them. If these lines are not tidied up as they sweep through space then the result is a drawing brush with multiple colours and complex dynamical behaviours. One simply grasps one of the particles and drags the enitire assembly around the screen, or one can propell it using the billiards mode.

The system model is defined in the file "smModels.exw" and the interface is defined in the file "interact.ew". The other files are either common SMN code or Euphoria code. All files are written in the programming language "Euphoria" ( with win32Lib windows API and are executed using the Euphoria interpreter (ex.exe).

Getting Started:

Initially the simulation engine is paused, press 'p' to start and stop the simulation. The default model consists of three particles sitting stationary close to each other, which are identical except for their charges. Press 'p' to start the simulation engine then click on one of the particles to select it, then one can drag it around and see the other two particles move in response. Press 'p' again to pause the simulation.

Try loading a pre-made model by pressing 'm' then '7' then loading up one of the "brush_##.mdl" files. Grasp this and get a feel for how it moves. Note: whenever the main view window loses focus the simulation is paused if one is still holding a particle and the pen is lifted if one is in drawing mode. This is to ensure that ones work won't get corrupted when the window receives focus again. So after using a menu you may need to press 'p' or 'space' to un-pause the engine and lower the brush. To make sure you are holding the brush by it's designed handle, press 'g' then change the grip width to 100 so that the handle is the only particle that can be selected (but other grip points lead to different behaviour as well). Also maybe press 'z' then zoom out to 0.1 or 0.05 to give yourself a bit more space.

How to draw with it...
Press 't' to cause the particles to leave traces on the screen and experiment with this effect. In this mode try pressing 'a' to switch association_drawing mode off and see what effect this has. Press 'a't' to go back to no drawing then press 'l' to cause the association lines to sweep out colours on the screen, this is line colouring mode (you can press 'w' to vary the line width, 'd' for dotted lines or 'H' for half lines that show both colours for two way associations). Now press 'e' to erase the image if you want, and maybe press 'z' to zoom out to about 0.1 then try drawing with the brush.

When drawing, the held particle is only a focal point of the brush so one cannot just swing it around without regard to the other particles. One must engage in a dance with the whole system of particles in order to fully control the brush. It takes a little practice before one can easily write with it, for example.

Also try pressing the space bar to lift or lower the brush, then one can move it around the screen without effecting the image. If you want an eraser simply turn off the drawing functions (but stay in draw mode) and the particles then sweep away regions of colour leaving the background.

When one has made an image press 'i' then enter to save it as a bitmap. To exit drawing mode entirely and return to simulation mode press 'D', this erases the image and keeps the background clear since in sim mode it represents empty space.

How to create models...
Press 'm' then 4 to load a model from a parameter file, these are model 'templates'. The file "03 particle spring like system.pmt" has a system like the default model, it is a good one to start with. With the simulation engine paused edit the system's parameters (described below) by pressing 'T', one can add or remove particles and adjust all of their properties. Then press 'A' to enter association editing mode in which one can draw associations between particles (redrawing any association removes it). If one draws from particle A to particle B then A is associated with B, and the force experienced by A from B is magnified by 50 times (press 'F' to change this value). Drawing only one way creates a one way association. Unbalanced associations create unbalanced forces that cause the system to whirl around. Thus if you associate two particles to a third particle the two will whirl around the third one which remains mostly stationary. Or if you associate particles into a ring the collective system has an intrinsic spin. Another way to create non-physical unbalanced forces is to set some particle's close range behaviour to be "repulsion" whilst other are "attraction". For example, particle A responds with repulsion to the presence of particle B so it moves away, but particle B responds with attraction to particle A so it chases after, thus the two run off in some direction. These create sources of perpetual motion or unlimited energy that can be woven into a system network and used to power the behaviour of drawing brushes.

When creating a brush, if it is to have a particular 'handle' then it is best to make that the last particle (highest system number) and to associate the particles based on this. Then one can press 'g' to set the grip width to a large value (e.g. 100) so whenever you click in the viscinity of the system of particles the handle is selected. Once the brush is constructed press 'u' to update the stored model, this stores the new configuration so that it can be reloaded by pressing 'r' if you need to, for example if the particles fly way off screen. Now press 'A' to exit associating_mode and grasp the main particle then press 'p' to restart the simulation engine. Now one can see how the system behaves as a brush, try draging it around and see how it responds. Now comes the time to tweak the particle system, there are many parameters that determine the intricate behaviour of the system. One might reduce the friction so the particles glide more effortlessly, or change the masses and charges, or the softness values (whether they keep responding as they intersect softness=0 or they glide straight through each other softness=1), or the overall force strength, and so on. It takes time to get a feel for how these parameters effect the system, but when one masters it the systems are extremely flexible and intricately programable. Some knowledge of the basic physics of systems of particles would also probably help.

When one is happy with the brush press 'm' to save the model. Save it as a data file not a parameter file. A parameter file is a compact way of storing basic system configurations but it doesn't capture the entire state of the model such as the associations. Note: new versions of this program may employ different internal data formats so old model files will become obsolete. This is because the program is still in the early stages of development. Sorry for any inconvenience, the parameter files should be more stable.

Interacting with the Simulation:

When the simulation runs there is a system of particles displayed on the screen, which one may interact with. There are also many hotkeys giving access to menus and functions.

Most Used Hotkeys:


Drawing: Model Design:

All Hotkeys


  • q = Query the program's state (i.e. it's operational parameters and modes, also see the main window title bar)
  • M = toggle fullscreen window
  • F1 = Help screen
  • I = change the Idle Threshold, (large values means the engine goes onto idle easily) Empirical Transcendent:


    If one left clicks on a particle one can move it to a new position on the screen. In billiards mode one uses the left mouse button to apply an impulse force to particles. Press 'b' to toggle between these modes. In billiards mode one can shoot particles around using the mouse as a billiard cue. One can also edit associations in associating mode.

    If one right clicks on a particle its observable state is displayed (e.g. position, velocity, force) and one can edit the values to construct scenarios.

    I will describe the new options in time, but most of the interface should be self explanatory.

    Billiards Mode:

    One can toggle billiards mode by pressing 'b' and then shoot particles around using the mouse as a billiard cue. This can be useful whenn drawing if one wishes to nudge the brush. One can also pause the simulation, apply forces to all the particles using the billiard cue and then un-pause and the brush moves off on its new trajectory. With judicious use of the pause button and billiard cue one can control things quite finely. One can vary the strength of the impulse force by pressing 'B'.

    Click the left mouse button on a particle then move the mouse. This draws out a fine white line that represents a sort of billiards cue. The direction in which the line is pointing indicates the direction of the applied force. The length of the line represents the strength of the applied force. When the mouse is clicked again an impulse force is applied to the particle and it responds appropriately, perhaps by flying accross the screen or bouncing into other particles.

    Model Parameters:

    The system model is either stored as a sequence of parameters in a *.pmt file or as a full model in a *.mdl file. In a parameter file you can easily edit the parameters, which is a good way of constructing basic systems. Just edit the parameter file and reload to test the results, then tweak the simulation a bit and save again as a parameter file. In a model file the full system state is stored, including all associations, velocities, forces and so on. Note, you can also create a model by typing in a parameter sequence during runtime.

    Generally one creates a model using a set of parameters. This can then be adjusted into some configuration (perhaps adding particles and moving them around, changing their properties and making and breaking associations). This can then be saved as a model file for further development.

    example of a parameter sequence for two particles:
      sequence of coords    sequence  time friction  radius   softness  charge
       |                   of masses  step   |    size |   scale   |   / 
       |                    |          |     |     |   |      |    |  | 
    {{{360,210},{320,260}}, {1,1000}, 0.08, 0.05, 61, 61, {4e2,0}, 0, 1}

    Note: mass, size, radius, softness and charge can be either a sequence of values for each particle or a single value to be applied to all particles.

    time step:
      determines the temporal resolution of the simulation, the duration between computed moments. This is a single value that applies to the whole simulation.

      is the size of a particle as it is visually represented on the screen. This parameter has no effect on the simulated dynamics.

      is the size of the particle within the computed dynamics. This parameter does effect the simulated dynamics.

      determines the degree of close range interaction between particles. When softness is zero particle's interact normally right up to the zero threshold. As softness tends to one particle interactions become weaker until they eventually experience no force due to each other when at close range. This variable doesn't effect whether the field is attractive or repulsive, it just effects the strength of the field. Thus a particle with zero softness is only 'hard' when there are repulsive forces at play. There are two ways of making hard particles, discussed shortly.

      relates to the viscosity of space.
        f=0 means no viscosity and
        f=1 means full friction or maximum viscosity.

      is a scaling factor to tune the strength of the gravitational and electrostatic fields {Gscale, Escale}. Setting scale = 0 turns the field off. Changing the scaling factor is equivalent to uniformly adjusting all of the particle masses or charges.

      can be any positive or negative value. If the charges don't sum to zero there will be global unbalanced forces that pull the model around.

    By modifying these one can design different particle simulations.
    Note: In order to get a stable system of particles the parameters need to be tuned appropriately, otherwise they may just fly off and disperse or fall together into a clump.

    E.g. if one increases the simulation time-step, each simulated step becomes larger, thus paticles may jump very close together in a single leap, this may expose to a Huge force that is then applied over a large time step, which propels them far apart. Thus if one increases the time-step one should also reduce the force scaling factor. Or if one decreases the time-step one may wish to turn up the force scaling factor. Or one could also adjust the masses or charges or friction and so on.

    Note: another parameter not included in the file but worth mentioning is repulsion   this value is either one or zero (true/false). The default is to have repulsion turned off, this approximates normal gravity. If repulsion is turned on, then the particle experiences normal gravity at some distance but at close range the gravitational field becomes repulsive. Thus repulsive particles experience gravity as a repulsive force at close range and thereby exhibit a kind of 'solidity'. This is however very un-physical and if you place a single non-repulsive particle into the scenario things get interesting. Because it is always attracted to the other particles, expecially at close range, but the others are always repeled. Thus there arises a never ending chase due to the unbalanced forces.
    Note: when using repulsive particles, the softness value is critical. Don't set it to zero because this makes them infinitely hard and the repulsive forces are HUGE. Use a value around 0.1 or so.

    The best way to make hard particles is to set the softness to zero, use non-repulsive particles and set all of the charges to the same polarity. Then gravity pulls them inwards but the electric field pushes them apart. This can be tuned to a desired balance of attraction and repulsion.


    Ex: (load, play, zoom, pan)
    Load a simple three particle brush (e.g. brush_01.mdl) by pressing 'm' then '7'. Grasp one particle (left click), then press 'p' to start the simulation engine, then try moving the particle around, then try getting the other particles swinging and then click once more to release the brush and then watch it swing about chaotically of its own accord (the associations induce an unbalanced force that causes the particles to swing about chaotically). Then press 'c' to change colour scheme. Then try SHIFT + UP or DOWN arrows to alter the zoom. Notice that by zooming one effectively changes the size of the brush. Also try the arrow keys on their own to move the brush around on the screen.

    Ex: (drawing)
    Now try pressing 'l' so that the associations lines sweep out regions of colour whilst the particles sweep the colour away leaving black traces. Try drawing with this for a bit, you can press 'a' to turn the lines on and off or you can also press the 'space bar' to lift the pen so that it doesn't mark the image. Using pause 'p' or step 's' is also good for fine control. You can also use billiard mode 'b' to propell the particles using the left mouse button as a billiard cue (next exercise). Also try pressing 'd' and 'H' as well for dotted and half lines. Also try changing the line width with 'w'.

    Also try turning line drawing off 'l', then press 't' so that the particles themselves leave traces whilst the association lines sweep them away. Press 'a' to hide the association lines if you want just particle traces.

    Press 'e' to erase the image or press 'i' to save it to file.

    Ex: (billiards mode)
    Go into billiards mode (b) and apply a force to a particle (left click, drag, left click). Adjust the impulse force using 'B' if desired to tune the effect that this has on the particles. Use small shots at first until you get a feel for it otherwise you might blast it way of screen, see a later exercise for this.

    Ex: (particle interactions)
    First pause then drag a particle away from the main group of particles, then edit it's velocity (right click -> change velocity '3') to send it into the main group as a projectile, or use the billiard method to propel the particle, then un-pause the simulation and see what happens. If they are soft particles the projectile will pass straight through but if they are hard there will be scattering. However if the velocity or impulse force is HUGE it will send the particle flying through the others so fast that they do not have time to interact and scatter.

    Ex: (collecting lost particles)
    Increase the force field strength to make the brush go a bit wild ('T' then '17'), then when some of its particles fly way off-screen one may need to retreive them. Pressing 'z' is another way to zoom, try a small zoom factor, perhaps 0.05 and then press 'g' to change the grasp size; when the particles are very small on screen they can be hard to grasp with the mouse but a large grasp size makes it much easier. Then drag the particles back toward the center of the screen, release them, then zoom back in with the arrow keys to an approriate level and readjust the grasp size, (when one zooms back in the grasp size must be changed back to a smaller value if one wishes to select particular systems at close range).

    Ex: (altering a brush)
    Starting with "brush_01.mdl", get a feel for how it behaves, i.e. the particle's tendency to pass right through each other (their soft or bosonic behaviour). Now change them all to hard (or fermionic) particles that experience close range repulsion, thus they now have solidity and they bounce off of each other 'T' -> change softness values (8) -> then enter 0 to make them all minimally 'soft'. Now make them all positively charged 'T' -> (9). Make sure the electrostatic field is turned on 'T' -> (17). Now watch how they behave. Note, you may need to adjust the force strength, time-step or friction to make the new configuration stable. It is often advisable to set the friction right up or the force right down to begin with so that it is definately stable. Then one can tune it up to near the region of instability at which point it starts to take on interesting behaviours. It is convenient to make use of the 'u' and 'r' hotkeys when tuning a model so that one can undo changes. Press 'u' to update the model (brush type). Now whenever one presses 'r' to reload the model the current brush is brought back onto the screen in its current location. Try making some changes to the model, such as the masses, radii, on screen size, softness values, add or remove particles, time-step, friction, force strength or computational method. Then press 'r' to bring back the previously updated brush. Also experiment with loading and saving different brushes, just press 'm' to load or save a Model.

    Ex: (association editing)
    Given any brush system, change the associations between them and observe the changes in behaviour due to the different arrangement. Note, all particles interact via the force field but associated particles interact much more intensely. Thus one can create one way associations which induce unbalanced forces that give rise to chaotic dynamical brushes (create only two way associations if you wish to keep the forces balanced). To alter the associations press 'A' to toggle the Association editing mode on or off. In this mode one clicks on one particle then draws a line across to another particle and then clicks on it to release the line. If the particles are already associated this removes the association, but if they are not already associated this creates an association.

    Ex: (Load a new model from a parameter file)
    Parameter files (*.pmt) store the key parameters of a system of particles in a compact form. They don't record the entire model, such as the associations, velocities and so on. They are useful as model templates that one can easily edit in a text editor and then load to see the effect. This can be a good way to 'program' small systems. Then you can add other features such as associations and then store it as a full model file (*.mdl).
    Press 'm' -> load model from parameters (4). Try the file "09 spring like lattice.pmt", it consists of nine hard particles originally placed into a lattice. Connect these up with associations, letting the bottom right particle be the handle. A network of unbalanced associations creates unbalanced forces and you may need to adjust the time-step, force strength or friction to stop this from going too wild. Either change these via the menu 't' or edit the parameter file directly.

    Ex: (what happens to hard particles at close range)
    Using a model with 'hard' particles, pause the simulation 'p', then place one particle almost but not quite directly on top of another particle, then un-pause the simulation 'p' and see what happens. You will then probably need to reload the current model (r) or load a new model or go out and retrieve the particles as described earlier.

    Ex: (playing catch)
    Using any model with at least one free particle (such as the default model), zoom out so that the particles have a lot of room, then incease the grip width to say 50, and the grasp a particle and take it out into open space and then throw it across to the other side of the screen and then catch it on the other side. There is an art to throwing well... A smooth deliberate action followed by a precisely timed release is required for good accuracy. Maybe even place a clump of particles on the other side to use as a target.

    Trouble Shooting:

    If you have any problems, let me know and I will attempt to resolve it.
    Here I'll build a list of known problems and ways around them.