besssugo

a tool to build videos out of scientific calculations

besssugo

besssugo is a free computational tool specifically designed to aid a cognizant expert—i.e. you, whether an engineer, scientist, technician, geek, etc—to build videos showing the result of a certain scientific calculation or whatever data can be computed or storied in a digital computer. Technically speaking, it is a plugin for the computational tool wasora, which provides means to parse and understand a high-level plain-text input file containing algebraic expressions, data for function interpolation, differential equations and output instructions amongst other facilities. Therefore, any mathematical computation which can be done by wasora—i.e. solving systems of differential-algebraic equations, multidimensional interpolation of scattered data, numerical integration and differentiation, etc.—can be combined with the facilities that besssugo provides to create visual representations in the form of animations.

Last modification: Sat, 12 Apr 2014 16:27:03 -0400.

download

The recommended way to get besssugo is to download the latest (0.2.20) source tarball and compile besssugo from scratch:

Please note that to compile besssugo, the Simple DirectMedial Layer library (version 2) has to be installed in the system, along with its header files. In modern Debian-based distributions, it should be enough to install the development version of the library from the official repository:
$ apt-get install libsdl2-dev
It should be noted that besssugo includes into its sources code from SDL2_gfx and SDL2_image, both released under the zlib license, which is GPL-compatible, so there is no need to explicitly install these libraries. However, the latter further depends optionally on libpng and libjpeg, which are needed to load images from within besssugo. Again, they can be installed with apt:
$ apt-get install libpng12-dev libjpeg8-dev
Other non-standard libraries such as SUNDIALS or Readline are optional. See both the projects wasora and besssugo relies on.

bazaar repository

bazaar If you plan to contribute to besssugo, modify its sources or just want to get updated versions easily, you will need to branch the development tree of besssugo, which is hosted at Launchpad using bazaar as a control revision tool. The besssugo tree can be browsed online or branched into a local copy with
$ bzr branch lp:besssugo
If you use bzr to get the development version, you will need automake, autoconf, libtool and GNU m4. See details in the README.dev.txt file. Regular users just downloading the tarballs listed above will not need such advanced tools. Feel free to ask whatever question you may have in the mailing list.

quickstart

First, download the source code, uncompress, configure, make, check, install and go to examples directory:

$ wget http://www.talador.com.ar/jeremy/wasora/downloads/besssugo-0.2.20.tar.gz $ tar xvzf besssugo-0.2.20.tar.gz $ cd besssugo-0.2.20 $ ./configure $ make $ make check $ sudo make install $
See the documentation for detailed installation instructions.

the yellow bouncing ball

The first problem solved in the make check step is a yellow ball that travels from left to right bouncing at the floor over a purple background that slighly changes over time. The time of the video, the canvas size, the ball radius and the enery-loss coefficient are chosen at random:
CONST end_time w h b r c

end_time = random_gauss(4,1)
realtime_scale = 1
dt = 1/32

w = random_gauss(480,60)
h = random_gauss(360,40)
b = random(2,4)
r = random_gauss(0.05,0.02)
c = random(0.5,1.5)

WINDOW WIDTH w HEIGHT h CAPTION "the yellow bouncing ball"\
  COORDINATES 0 h w -h w HARDWARE \
  COLOR 0.5+0.1*sin(2.123*t+1) 0.25+0.15*sin(1.321*t+2) 0.8+0.1*sin(1.707*t+3)

x = t/end_time
y = abs(cos(x*b*pi)) * exp(-c*x)
CIRCLE R r  X x  Y y COLOR yellow

BESSSUGO_DRAW

Actually, this input shows the bouncing ball on the screen. Nevertheless, the following input (which is also included in the test suite) generates a video output by first dumping the frames to individual PNG images and then using avconv to create a WebM video. The FPS are chosen at the commandline:

INCLUDE ball.was
dt = 1/$1
realtime_scale = 0

OUTPUT_FILE frame ball-%04g.png step_transient
BESSSUGO_DUMP FILE frame

IF done
 PRINT "encoding video..." NONEWLINE
 SHELL "avconv -y -f image2 -framerate $1 -i ball-%%04d.png -vcodec libvpx ball.webm -v quiet"
 PRINT "ok!"
 PRINT "removing temporary frames..." NONEWLINE
 SHELL "rm -f ball-*.png"
 PRINT "ok!"
ENDIF

find the green spot

The next tiny input generates an optical illusion. Can you find where the green spot is defined?
NUMBER n = 12
R = 0.45
r = 0.05
T = 1.25

dt = 0.5*T/n
end_time = 10*T
realtime_scale = 1

WINDOW WIDTH 1440 HEIGHT 920 COLOR grey50 \
    CAPTION "find the green spot"
CIRCLE ARRAY n X R*cos(2*pi*i/n) \
               Y R*sin(2*pi*i/n) \
               R r*(mod(t+(i-1)*T/n,T)>T/n) \
               COLOR magenta
BESSSUGO_DRAW

Again, besssugo uses the actual screen to output the trick. However, here is an scaled video of the output:

the lorenz system

Build your own version of the Lorenz attractor by first stating which variables belong to the phase space, setting the integration time, defining the constant parameters and the initial conditions. Instead of writing the output to a text file (as in wasora's quickstart), now send the results online to the screen:
# the contents of these file between the dashed lines is
# exactly equal to wasora's example file lorenz.was
# -----8<--------- cut here -----8<---------
# lorenz' seminal dynamical system
PHASE_SPACE x y z
end_time = 40

CONST sigma r b  
sigma = 10            # parameters
r = 28
b = 8/3

x_0 = -11             # initial conditions
y_0 = -16
z_0 = 22.5

# the dynamical system
x_dot .= sigma*(y - x)
y_dot .= x*(r - z) - y
z_dot .= x*y - b*z

PRINT t x y z
# -----8<--------- cut here -----8<---------
# these four lines are the ones that besssugo reads and
# uses to draw a colorful representation of the
# x-z phase-space plane of lorenz' butterfly
# realtime_scale = 1
WINDOW WIDTH 640 HEIGHT 480 COLOR black PERSISTENT \
 COORDINATES 320 480 15 -10 15 HARDWARE
SEGMENT X1 last(x) X2 x Y1 last(z) Y2 z \
        COLOR 0.5*(1+cos(5.071*t+1.5)) \
              0.5*(1+cos(-2.241*t+1)) \
              0.5*(1+cos(9.457*t))
BESSSUGO_DRAW 

See also the section about The Lorenz chaotic system and The chaotic Lorenzian waterwheel amongst other further examples in The wasora Real Book.

chaos

Study the chaotic nature of the Lorenz equations by slighly perturbing the initial conditions for one hundred of systems:
# this example illustrates the sensitivity to initial conditions
# of the lorenz system by solving one hundred systems with
# slightly different initial conditions
NUMBER N 100
VECTOR vx SIZE N
VECTOR vy SIZE N
VECTOR vz SIZE N

PHASE_SPACE vx vy vz
end_time = 40

# same parameters for all cases
CONST sigma r b  
sigma = 10            
r = 28
b = 8/3


# slightly different initial conditions
eps = 1e-3
vx_0(i) = -11  + eps*i  
vy_0(i) = -16  + eps*i
vz_0(i) = 22.5 + eps*i

# the dynamical systems (v stands for vector)
vx_dot(i) .= sigma*(vy(i) - vx(i))
vy_dot(i) .= vx(i)*(r - vz(i)) - vy(i)
vz_dot(i) .= vx(i)*vy(i) - b*vz(i)

# realtime_scale = 1
WINDOW WIDTH 640 HEIGHT 480 COLOR black COORDINATES 320 480 15 -10 15 HARDWARE
CIRCLE ARRAY N X vx(i) Y vz(i) RAD 0.1 COLOR 1-exp(-3*i/N) sin(pi*i/N) cos(0.5*pi*i/N)
BESSSUGO_DRAW 

documentation

the wasora real book

The following sections of the wasora Real Book include examples of videos generated by besssugo:

realbook

the examples subdirectory

Following the idea of the wasora Real Book which consists of examples of application, the besssugo source tarball includes a subdirectory called examples which contain some ready-to-use examples. They can be browsed online at the bazaar repository.

further examples

the simple pendulum

From the Newton, Lagrange & Hamilton section of the Wasora Real Book:

the double pendulum

From the The double pendulum section of the Wasora Real Book:

the lorenzian chaotic waterwheel

From tge The chaotic Lorenzian waterwheel section of the Wasora Real Book:

mailing list

There exist a mailing list < wasora @ talador.com.ar > where questions can be posted about any aspect of the code, including intallation, usage and development. Besides suscribing and directly asking a question, you can also browse the archives. Bugs reports are also welcome.

platforms

besssugo is free software, and as such it is developed under a free operating system, namely Debian GNU/Linux. The distribution tarball is based on GNU Autoconf & friends, so besssugo should build in any POSIX-compliant environment. However, besssugo is a fairly complex piece of software, so portability is not guaranteed (but improvements are welcome). Running besssugo in non-free operating systems is discouraged, and such topic is not of the interest of the author of besssugo. However, contributions and experiences may be well received if discussed in the mailing list.

license

besssugo is released under the terms of the GNU General Public License version 3, or at your option, any later version. Bottomline is, you get the four software freedoms

  • The freedom to run the program, for any purpose (freedom 0).
  • The freedom to study how the program works, and change it so it does your computing as you wish (freedom 1). Access to the source code is a precondition for this.
  • The freedom to redistribute copies so you can help your neighbor (freedom 2).
  • The freedom to distribute copies of your modified versions to others (freedom 3). By doing this you can give the whole community a chance to benefit from your changes. Access to the source code is a precondition for this.
The condition is that if you modify the code and/or include it in a larger package and you want to distribute it, you have to release it under the same terms of the GPLv3+. That is to say, you cannot turn any derivative work based on besssugo into a privative software. However, private modifications not intended for distribution may be produced and, if desired, never undisclosed at all. See the GPL FAQs or contact the mailing list for further details.

projects besssugo relies on

required libraries

Simple DirectMedia Layer
besssugo uses the SDL to access the video card. Version 2 is needed, version 1.2 does not work with besssugo.

In Debian-based systems, the needed components can be installed with

$ apt-get install libsdl2-dev

optional libraries

To be done.

 

 

© jeremy theler 2004—2014