Apps Plotter Workbook Image Processing Script Editor Command Editor std Library Overview Road Map Developer


This section gives concise but essential information on ScienceSuit environment which is essential to correctly use the software.



1) Directory Structure

The directory structure is shown in the following figure:






2) Commit & Save

When you start a new project or open an existing project, a snapshot directory is created under the temp folder with the same name of the project or as "Unsaved Project" along with the current date appended to the name of the folder. When a project is opened, the snapshot directory contains the unpacked contents of the .sproj file and when a new project is started, it is empty.

Once you commit, the committed work is written to the snapshot directory rather than directly to the project file. Saving the project is equivalent to re-packing a copy of the snapshot directory as the project file. The generated (re-packed) project file replaces the existing one as you save.  The following example gives a clear picture of the process:

User opens C:\MyProject.sproj file
System creates MyProject --25133209 folder under the temp directory and unpacks contents of MyProject.sproj
User commits some work (data is written to MyProject --25133209)
User clicks save
System packs the contents of MyProject --25133209
Creates MyProject.sproj under the temp directory
Replaces C:\MyProject.sproj with temp\MyProject.sproj.
If replacement is successful, system deletes temp\MyProject.sproj file.
User closes the project
System deletes MyProject --25133209 folder

The sequence in the red-dashed region can be repeated many times during a run.


Why not just save?

You might be wondering why instead of a two step process, only one single step save was not implemented. Among the several some of the advantages of implementing a commit and save mechanism is as follows:

  1. ScienceSuit is comprised of several modules and commit and save mechanism allows you to save only from the modules you want to include in the final project file. A single save mechanism would have included all actively running modules.
  2. Once committed, the data is never lost and can be recovered even if, for some reason, the system crashes.
  3. A faster read/save mechanism can be implemented.


How to commit?

Very simple! For example, in order to commit your work for the workbook, go to Workbook page and click the commit button as shown:


Once a commit has been made, "Unsaved Commits" message will appear at the toolbar. Right-clicking on this part of the toolbar will show the following context menu:


Clicking on the "Show Committers" menu will show the following frame:

Here, you will be able to see from which parts of the framework commits have been made. In this example, only a single commit has been made from Workbook at 19:43:00.


How to save?

In order to save your commits, you can use either the save button at the home ribbon page or the save button that will appear, when there are unsaved commits, at the toolbar as shown below:



3) Open Existing or Start New Project

When you start ScienceSuit, the following screen will be displayed:

The screen is conceptually partitioned into three parts: i) The banner, ii) the buttons, iii) Recent Projects.

The banner: Depending on the time of the day a greeting message and the version information is displayed.

The Buttons: New Project and Open Project.

Recent Projects: A list of the recent projects. Please note that, before displaying the recent projects, the system checks whether each recent project is still available in its particular location.



4) Concept of Multiple Instance

Until v1.8.6 only a single-instance of ScienceSuit with multiple workbooks could be run. However, as of v1.8.6 multiple instances of ScienceSuit can be run at the same time and each instance is considered as a separate project and therefore each instance runs independently.

*instance: Running ScienceSuit.exe creates an instance of ScienceSuit. In single-instance environment, when an instance is running, the second was not allowed. However, in multiple instance environment, an instance is created each time ScienceSuit.exe is run.


Independence of Instances

  1. Workbook: Each instance has its own workbook isolated from other instances. For example, an app cannot make selection from other instances' Workbook.
  2. Lua virtual machine: Any variable, function, etc... created in one instance is not available in other instances.
  3. Anything based on the project itself (settings etc...).


Shared resources

The following resources are shared by each instance of ScienceSuit:

  1. Global settings: settings.sconfig file is shared by all instances.
  2. History file: Any command-typed and recorded to history file will be read by an instance at the time of instantiation (see start sequence).
  3. Log file: Each instance appends its log to the same log file.



5) Reserved Words

These are the identifiers which you are either prohibited to use or should definitely not use as variable names.


1) Reserved by Lua

The identifiers reserved by Lua (please see section 3.1) cannot be used as variable names. The internal Lua engine will issue an error if you do so. The reserved identifiers are (from the Lua manual):

and    break    do    else    elseif    end    false    for    function    goto    if    in
local    nil    not    or    repeat    return    then    true    until    while


For example, in the following we attempt to use and and if as variable names:

[string " and=3"]:1: unexpected symbol near 'and'

[string " if=2"]:1: unexpected symbol near 'if'

It is clearly seen that, Lua will issue an error should we attempt to use reserved words as variable names.


2) Reserved by ScienceSuit

The identifiers used by ScienceSuit system and should not be used as variable names. These are: std, iup and SYSTEM


--Now we are assigning a value to std
>>std="Assigning a string value"

--calling std.sum again
[string "return std.sum(t)"]:1: attempt to call a nil value (field 'sum')


Please note that, unlike Lua's reserved names, assigning a value to std is accepted by Lua as expected. However, assigning a value to std has overridden the std library and as of this point std library is not available anymore. Therefore, calling std.sum caused an error.


Considering the reserved words by Lua (1) and ScienceSuit (2), a simple guideline when declaring variables is:

  1. When scripting, always declare variables as local. This will prevent hard-to-debug problems.

    For example, if you accidentally declared a variable as std=1 in any script file, this declaration will affect the whole system as the std library will become unavailable. However, if you declare local std=1, this will only affect the file it has been declared in.

    However, as shown below, if you declare std library as const at the beginning of the script file then the above-mentioned problem is considerably alleviated:

    local std <const> =std

  2. Note that, all variables declared in Command Editor are, by default, not local. Therefore, it is available system-wide.



6) Start Sequence

The following sequence is followed to initiliaze an instance of ScienceSuit:

Welcome screen is shown, if settings.sconfig file does not exist, it is created.

Main frame, Workbook and Command Line are loaded.

Command history file (history.shist) is loaded or created.

Default Lua libraries are loaded.

Lua engine is prepared

std library is created.

SYSTEM library is created.

The functions and classes (such as Vector, Matrix...) programmed in C++ are loaded.

init.lua file located under sys directory is loaded.

Scripts in sys/std and all its subfolders are recursively loaded.

Scripts in apps folder are loaded.

iup library is loaded.

init.lua located under home folder is loaded.

Scripts under home/autoload are loaded.