MW applets and MWScript-JavaScript interactions

Now that you can publish a Molecular Workbench simulation as an applet and embed it on your web page, you may be wondering how you can control it and get data in and out. It may be interesting for web developers who would like to link an existing Flash animation with a molecular dynamics simulation in MW. For example, when the visitor clicks something in the Flash animation, a molecular dynamics simulation will pop out to show the molecular mechanism of what is going on underneath.

With MW, this can now be done using MWScript and JavaScript. MWScript is a scripting language used in MW to support modelers and animators to design simulations. The model builders in MW do have some simple GUI for building models and designing simulations, but their functionality is limited (as with any GUI). Syntactically, MWScript is a cousin of JmolScript, which supports scripting with the popular Jmol molecular viewer. So anyone who is already familiar with JmolScript may find it easy.

Before we talk about scripting, let me show you how to set up an MW applet on your web page. If you just want to show an existing MW simulation from mw2.concord.org (which hosts MW) on your web page, just embed the following applet code within the body of your HTML file:

<applet id="applet_id"
archive="http://mw2.concord.org/public/lib/mwapplet.jar" 
code="org.concord.modeler.MwApplet" codebase="http://mw2.concord.org/public/" 
width="100%" height="500"> <param name="permissions" value="all-permissions"/> 
<param name="script" value=
"page:0:import http://mw2.concord.org/public/student/classic/motion/undershotwaterwheel.cml"/>
</applet>

In the above example, I have randomly chosen an existing simulation from MW to show how this works. If you want to show other simulations, just replace "http://mw2.concord.org/public/student/classic/motion/undershotwaterwheel.cml" with whatever else.

This following shows the embedded MW applet specified by the above code:





This is very easy to do. But it has a limitation. Suppose you have created an MW simulation of your own and the name of the main file is "simulation.cml" (an MW simulation has other files associated with it as well). Now you have to upload the files to the Web. If you use its URL in the embedding code, the MW applet will not load it. Because of a good security reason, an applet is allowed to read files from only the same code base where the Java executable is located (in this case, http://mw2.concord.org/public/lib/mwapplet.jar).

To avoid this problem, you would want to have your own code base instead of using mw2.concord.org. First, you download the jar file: mwapplet.jar to the same folder where "simulation.cml" and the HTML file sit. Second, change the embedding code to:

<applet id="applet_id" archive="mwapplet.jar" 
code="org.concord.modeler.MwApplet"  codebase="http://mw2.concord.org/public/"
width="100%" height="450"> <param name="permissions" value="all-permissions"/> <param name="script"
value="page:0:import simulation.cml"/>
</applet>

Having done these, you just need to make sure to also upload "mwapplet.jar" to the same web folder where "simulation.cml" has been uploaded to.

If you have done these and succeeded in getting an MW applet to work properly, let's see how to get it to work with JavaScript as well. First, download this file: mw.js to the same folder. Second, put the following script declaration in the header of your HTML file:

<script type="text/javascript" src="mw.js"></script>

The MW applet is now ready to interact with JavaScript. The applet works offline as well, so you can conveniently test your JavaScript before deploying the whole thing to the Internet, by just double-clicking on the HTML file and see how it works.

There are currently three types of interactions between MWScript and JavaScript.

• Use JavaScript to send MWScript to control an MW applet
• Use JavaScript to feed data to an MW applet
• Use JavaScript to get data out of an MW applet

The runScript(id, script) method in mw.js can be used to send MWScript to an MW applet with the specified ID. An MW applet is an MW page that can have multiple models, though in practice you would only use one model per applet. To specify which model you would like to send the MWScript, you have to following the following protocol:

[model type]:[index or UID of model]:[script body]

For instance, mw2d:1:run instructs the first model within the MW applet to run. You can pass a variable from JavaScript to MWScript by concatenating the variable with a script command. For example, var temp = 300; runScript("applet_id", "mw2d:1:set temperature " + temp) sets the temperature of the system to be 300 K.

The get command in MWScript was specifically designed to fetch data out of an MW applet. For instance, you can get the temperature by using the following code: var temp = runScript("applet_id", "mw2d:1:get %temperature");.

This page demonstrates all these three types of interactions with one applet. It is inconvenient for me to mix code in this blog as it interferes with the blog's setup. When you go to that page, you can view the page source to see the JavaScript code. If you have Firebug, it can also be used to view the code easily.

For more information about MWScript, go to http://mw.concord.org to launch the standalone application and check out the "Script" section in the User's Manual.

Publishing Molecular Workbench simulations as applets

For a while I have been asked whether or not an MW simulation can be made to run directly within a browser page instead of a pop-up window. Several collaborators would like to deploy MW simulations within their web portals or delivery systems. For them, embedding a simulation within a web page is desirable. The current way of using the Java Web Start to launch an MW simulation sometimes irritates users as it can appear to be yet another kind of annoying pop-ups.

So I did some work in the past week to make it possible for users to save an MW page as an applet, which can then be deployed anywhere without having to rely on my company's server. This is always good for the integrity of a web site, as no serious web developer wants to depend on other people's servers to be up and running forever.

Here are some demos:








This new mechanism of publishing MW simulations provides an option for people who want to integrate MW simulations with their web applications, if they don't mind the relatively slow loading speed.

Energy2D: Interactive computational fluid dynamics

Computational fluid dynamics (CFD) uses numeric methods to study any natural phenomenon and solve any engineering problem related to fluid flow. It has been an indispensable tool for many engineers. Mature, powerful CFD products are available nowadays. While these products are very useful tools for engineers, they were not designed for kids to play with. Understandably, the business community lacks the financial incentive to push the agenda of making a product friendly to students for learning science and engineering. With all these years passed while CFD products got better and better, all the wisdom developed for modeling and understanding the natural and man-made systems never got spread to schools in a satisfactory scale.

This tragedy was, in part, caused by the unfortunate fact that few people in the education community had realized the enormous power of CFD for teaching science and engineering. Educators had a very good reason for not seeing it, because the power has never been brought close enough to matter in their professional careers. Most CFD tools are either too complicated to use or do not deliver the needed visual effects and user interfaces to matter. This is an issue that cannot be simply said solved by sending a demonstrator from the CFD community to the education community. Talking and showing are cheap. To bridge the gap, we need actions that will truly make a difference.

Supported by the National Science Foundation with an urgent need for educating young students with energy science and technology, we are developing a versatile CFD package suitable for teaching the scientific and engineering principles related to energy flow, particularly about energy-efficient passive solar buildings. The package consists of two programs called Energy2D and Energy3D, respectively, for the 2D and 3D versions of the CFD simulator.

Energy2D and Energy3D are based on solving the heat equation for modeling thermal conduction, coupled with the Navier-Stokes equation for modeling convection. A ray-tracing method is used to model radiation. The minimum requirement is that the simulation must run fast enough to be interactive so that students can play with it.

After a few weeks of work, I came up with a primitive version of Energy2D. The following two screenshots show that if the obstacle has a small cross section against the flow, turbulence will not occur.

It turned out that writing an unconditionally stable heat solver was not a big deal. After all, it is just a simple diffusion equation that can be easily solved using an implicit method.

Writing a fluid solver is more challenging as it is non-linear (which is where all the fun comes from). I played and tested Jos Stam's fluid solver, which is based on an unconditionally stable Semi-Lagrangian method that is also used in weather prediction. Unfortunately, the solver is covered by a pending patent that we didn't succeed in convincing the current patent owner to license to us in any way--open-source or not. So I had to give up Stam's method and sought to reinvent the wheel.

I implemented the MacCormack method, which turned out to work fine for now. Compared with the Semi-Lagrangian method that achieves its stability by overdamping the fluid, the MacCormack method has no overdamping problem so it has to suffer from the stability problem. As a side note, I also found that after using the vorticity confinement method to re-inject vorticity to the solution of the Semi-Lagrangian method to make it more turbulent, it would also suffer from the stability problem. There seems to be no free lunch in seeking a fast, yet accurate, fluid solver.

Beyond Google SketchUp

Google SketchUp is a wonderful program that you can use to design 3D structures such as a building WYSIWYG-ly. It offers by far the most advanced user interface for creating 3D objects. Within ten minutes, you can sketch up a simple house with a roof, a few windows, and a door, as shown by the image below (if you have learned the basics). While the learning curve may take a little while to overcome--not because the program does a poor job but because the task of creating 3D objects is inherently difficult, the program still provides tremendous opportunities for education.

If you are a teacher, you may have used it in your classroom, or seen someone using it to engage students to design things like a house. These activities are just wonderful as students really love designing their own homes or schools. SketchUp provides them a simple platform to do exactly that.

Now, the question is that what students learn from designing their dream houses. The obvious answer is that they learn solid geometry, without which one cannot really design any 3D structures.

Solid geometry isn't an easy subject and being able to reason in three dimensions is an important skill to have. All these things are very good, but what about teaching other topics in science and engineering?

As many students use SketchUp to design buildings, those who have a mindset of energy efficiency may come up with some green designs, for instance, some neat passive heating or cooling architecture. After they draw their structures, they would like to evaluate if their designs are really green. This goes beyond what SketchUp can do, because it doesn't deal with heat and mass transfer for the created structures.

There has been a plug-in to SketchUp called OpenStudio, which was developed by the Department of Energy to integrate SketchUp with their EnergyPlus software. EnergyPlus is a program written in Fortran that was created for architects to evaluate thermal performance of buildings they design.

OpenStudio, however, doesn't quite do the job one would like to get done (judged from a demo video). The image below, taken from Wikipedia, is what we have in our mind that we would like to see. The image is a thermogram of a passive house in the background of traditional houses, taken by an infrared camera.

Wouldn't it be great if students can design a building and then do some thermal physical analysis using some kind of virtual thermography? This ability will truly extend what students can do with a geometric design tool such as SketchUp. By giving the power of physics-based simulation to the design tool, it will be transformed into a useful experimental tool that allows students to learn the scientific and engineering principles behind energy efficiency.

This is exactly what we set out to do since October 1, 2009, thanks to the generous funding by the US National Science Foundation.

Heat transfer calculations aren't new things to engineers. There have been plenty of commercial software that have been developed to simulate heat transfer. But many of them do not meet our criteria for creating an interactive learning environment. Unlike an industrial application with which engineers can take their time and make all kinds of valid assumptions, there isn't much flexibility for an educational program.

First, students cannot wait. The calculations must be done relatively quickly. Anything that takes a long time to compute kills interactivity.

Second, again required by interactivity, transient heat transfer is a must-do, leaving us no steady state to retreat to. An interactive learning environment requires that the user can intervene at any time when he or she would like to see the causality. There is simply no such thing as a steady state when the user is interacting with a simulation as user's action is totally unpredictable.

Third, the simulation must render a convincing visualization that shows what happen to the heat inside and outside a house. All things must be considered so as to support as many explorations as possible. This requirement is at odd with the first one, as it will load the engine with all kinds of calculations that may slow each other down.

So how do we model the heat transfer of a house? In a model of building, there are two different kinds of things: solid structures and air. The major difference between the heat transfer in them is that there is only conduction in a solid structure but there are both conduction and convection in the air because air is a fluid.

Mathematically, what we have boils down to two fundamental equations: the heat equation and the Navier-Stokes equation. The heat equation models conduction and the Navier-Stokes equation models convection. These two equations are coupled to simulate the heat transfer in the air. For the heat transfer in a solid structure, only the heat equation is needed. A convective boundary condition is applied to the edge of the border to model the effect of heating or cooling through the flow of air over the surface of the structure.

That is pretty much all the computational physics involved in modeling the thermal performance of a house. We leave out radiation, but it should not be hard to add it to the boundary conditions.