Repository structure

vendor/

Third-party JavaScript runtime dependencies
for Lab are located in the vendor/
directory and are installed as git submodules
the first time make is run in a new checkout of the source code repository.

Only the necessary JavaScript library files and other resources needed for runtime operation along
with the associated README and LICENSE files are copied to public/vendor during
the build process.

All of the files copied to public/vendor are licensed and distributed under
one or more of the following licenses: Simplified BSD, The BSD 3-Clause, MIT, or Apache 2.0.

src/

The src/ directory
contains the main source code for the Lab framework, examples, and documentation. This
code is either copied directly or used to generate resources that are copied.

src/lab/

The [src/lab](https://github.com/concord-consortium/lab/tree/master/src/lab)
directory includes JavaScript source code for the Lab JavaScript modules.
During the build process individual files are copied into modules which are placed in
the public/lab directory.

src/lab/md2d

The md2d model-type contains a basic *Next Generation Molecular Workbench application. It built using a hybrid of a MVC design pattern
with a dataflow architecture necessary for performance and consist of following units:

The source code of the core molecular dynamics engine is currently located in the src/lab/md2d/models/engine
directory, which is organized as a set of related RequireJS modules. These modules are compatible
both with the Web browser environment and Node.

MD2D Headless Mode
node-bin/run-md2d

There is one working script for now: node-bin/run-md2d

It runs simulation for desired time and prints Time, Kinetic Energy, Total Energy every tick.

Usage:

./node-bin/run-md2d -i [path] -o [path or stdout] -i [num]

Options:
  -i, --input   Model JSON file        [string]  [required]
  -o, --output  Output file or stdout  [string]  [default: "stdout"]
  -t, --time    Integration time       [default: 100]

Example results:

Model file: public/imports/legacy-mw-content/converted/new-examples-for-nextgen/simple-gas$0.json
Output: stdout
Integration time: 150
time    KE      TE
0       3.0988  3.1003
50      3.1748  3.1011
100     3.1748  3.0998
150     3.1868  3.0986
Writing new scripts

In addition, new Node-based executables can be written. These are expected to be useful for verifying and tuning the model by running the model headless and saving summary results into a file for offline analysis.

If you want to create your own script running simulation in headless mode, the most reasonable solution is to use src/lab/md2d/models/modeler.js as it provides high level API and
allows to load model description using JSON file. To run simulation use the tick() method.

RequireJS package must be correctly configured and used to load this module (see the section about
RequireJS). It also depends on jQuery and d3.js libraries.

Fortunately, you do not have to think about this configuration each time. There is prepared the entry point for external Node.js applications:

src/helpers/md2d/md2d-node-api.js

This module configures RequireJS loader, environment (D3, jQuery) and exports MD2D Node API using Node.js/CommonJS approach.

Usage:

var md2dAPI = require("../src/helpers/md2d/md2d-node-api");
// (...)
// To create e.g. Modeler mentioned above:
var model = md2dAPI.Modeler(properties);

If you need to use something what is not included in this API, you can:

There is a chance that existing RequireJS config won’t be sufficient (e.g. if you wan’t to use dynamic cs files loading).

Hashbang scripts for starting these executables (i.e., files which start with the line #!/usr/bin/env node and which have the execute bit set) should be placed in the directory node-bin. Lab’s packages.json file
specifies node-bin as the
location of the executable scripts which npm should make available whenever Lab is imported into
another project as a Node module. (For developer convenience, bin/ is being reserved for Ruby
executables made available via Bundler.)

MD2D simulation stepping

Main parameters which define speed and accuracy of simulation in MD2D are:

To explain them let’s start from the definition of the model “tick”. One “tick” consists of:

The “tick” is constantly repeated while simulation is running.

So, when timeStepsPerTick= 50 and timeStep = 1fs, one “tick” causes that the engine performs calculations for 50fs.

timeStep defines a time value used during the one integration step in the engine internals. It affects accuracy of calculations. timeStepsPerTick in fact defines number of these integration steps during one “tick”. It is defined because it makes no sense to refresh view too often.

Using pseudo-code we can say that tick is:

for (i = 0 to timeStepsPerTick) {
   engine.advanceBy(timeStep)
}
view.update()

That’s why timeStepsPerTick = 50 and timeStep = 1fs is different from timeStepsPerTick = 25 and timeStep = 2fs.
First one will be more accurate and two times slower (more or less) than second one, however both configurations will cause that one “tick” advance model by 50fs (25 * 2fs or 50 * 1fs).

modelSampleRate defines how often we should execute “tick”. Of course, in most cases we should call it as often as it’s possible and that’s the default behavior (with upper limit of 60 times per second to avoid running simple models too fast).

You can test how these parameters work using the Model integration time step, period, and sample rate
interactive.

src/lab/grapher/

src/lab/common/

src/lab/import-export/

src/lab/energy2d/

The src/lab/energy2d model-type contains
a basic *Energy2D application*. It is a direct port of Java Energy2D.
Energy2D is also built over MVC design pattern and consist of following units:

and additionally:

GPU Toolkit is a small set of utilities which wraps basic WebGL structures and objects, providing
higher level API. It is useful, as Energy2D uses WebGL for General-Purpose Computing on
Graphics Processing Unit. So, a lot of physics calculations are performed on the GPU if user’s Web
browser supports WebGL technology.

The source code of the core physics engine is located in the src/lab/energy2d/models directory.
Especially important units are listed below:

Necessary GLSL (GL Shading Language) sources are stored in separate files. They are loaded using
RequireJS text plug-in which just allows to load plain text files. Finally, they are inlined in
the resulting library due to the RequireJS optimization process.

src/examples/, src/doc/, and src/experiments/

The src/examples/, src/doc and, src/experiments
directories contain additional resources for generating the html, css, and image resources
for the matching target folders in public.

Note: remember to make changes you want saved in the src/examples/, src/doc/,
and src/experiments/ and not in the target directories of the same names in public. Change made in public will be overwritten during the next
build process.

src/resources

The src/resources/ directory contains image resources and are copied directly to public/resources.

src/sass

The src/sass/ directory contains Sass templates and the Bourbon Sass library are are used
during the build process to generate CSS resources.

src/helpers

The src/helpers/ directory contains
CoffeeScript and JavaScript modules as well as Ruby programs only used as part of the testing and
build process and are not copied to public/resources.