Simulation - Command Line

RealFlow's graphical user interface (GUI) helps you to create your project, but it is not always necessary for simulation. In fact, RealFlow can be launched in two different ways:

• In GUI mode, providing the well-known interface.

• From a terminal application without an interface.

The first question coming to mind is: “Why do I need different versions of the same application?” The answer is easy: “Because of simulation speed.” The graphical representation of particles, objects, meshes and maps can be a heavy computational task, and always uses a certain amount of CPU power. Though RealFlow offers a variety of tools to speed up redrawing or viewport representations, a certain amount of processing power is always needed.The drawing of meshes, for example, can sometimes take longer than the real creation process. But even if you have disabled a mesh’s viewport representation, the user interface takes up resources. Resources you could use much better for increasing simulation speed. We are not talking about a few seconds, but up to 30%.

Especially for batch simulations, side-by-side comparisons, large projects, different versions and so on, RealFlow’s command line version is the ultimate tool to get results much faster. You can start this version, for example with a shell or batch script, and simulate various projects overnight. You do not have to monitor this process or wait until a project is done and start the next one manually. The entire simulation process is done automatically and you do not have to worry about “FPS output”, “MAX substeps”, number of threads or anything else, because all these parameters can be adjusted individually while preparing your scenes. Then these projects are saved and simulated in RealFlow’s command line mode. You can also make use of your computer’s 64-bit mode.

Each full, GUI-based license of RealFlow can be launched in command line mode and Next Limit Technologies also offers “Simulation Node” licenses without an interface. For more information, please visit Next Limit's RealFlow homepage or contact our sales department.

How to Trigger Command Line Simulations from the GUI

RealFlow’s home directory does not show a particular application for launching the command line application. As mentioned before, it is not a separate program, it is just another way of starting the program. Before you fire off the “NOGUI” version, your scene has to be simulation-ready – just as if you are about to start a simulation in the “GUI” version. This does not only concern body dynamics, particle or grid fluid simulations, but also meshing and even Maxwell “FIRE” previews.

The easiest way is to trigger the simulation directly from the GUI. Please take a look at the “Simulation” button. There you will see a small triangle next to the button. When you click on this triangle, a context menu is opened:

If you want to send a simulation to the "NOGUI" application, simply activate “Command line” by clicking on the menu's entry. Another click on the “Simulation” button will assemble the entire command line string and start your operating system's terminal application. The scene will be simulated with the command line version instead of the GUI version, but the program's main window remains visible. You will be able to update the timeline at any time and monitor the simulation's current state. To update the timeline, use the Alt + U command or the appropriate button:

When your simulation is finished and you do not want to perform any command line tasks, please do not forget to uncheck the simulation menu's entry.

How to Trigger Command Line Simulations Manually

Another method is to open a terminal window from your operating system (e.g. Bash, Terminal or Window’s command line – “DOS”) and call it from RealFlow’s directory. This is done with the “cd” command:

prompt> cd /Program files/Next Limit/RealFlow 2013/

It is possible that your OS expects a certain notation with quotation marks for directories with blanks:

 prompt> cd /Applications/"RealFlow 2013"

With a “dir” (WIN) or “ls” (Linux/OS X) command you can list the directory’s content:

 prompt> dir (or ls)

Now look for the RealFlow application and enter:

 prompt/directory> realflow -nogui

Please note that Mac users have to use “realflow64”, because this command will launch the 64 bit version which supports the entire amount of your installed memory.

 prompt/directory> RealFlow.app/Contents/MacOS/realflow64 -nogui

Now RealFlow welcomes you with a typical message and shows a variety of options that can be used to start RealFlow. By entering “realflow -nogui” you have already used such an option, also called “flag”. These flags can be used to customize a simulation without having to alter the original project file. If you want to open RealFlow’s GUI version directly from the terminal, simply omit the “-nogui” flag.

There is also a possibility to call the command line application from any directory, such as your home directory. To achieve this, you should define a so-called environment path. In this case you do not have to go to browse to RealFlow’s home folder and you simply enter (please check your operating system’s manual or help function about how to set an environment variable. The process of creating it is different for most systems and can therefore not be explained in detail here):

prompt> realflow -nogui

Another method is to use absolute paths, e.g.:

prompt> "C:/Program files/Next Limit/RealFlow 2013/RealFlow.exe" -nogui

prompt> "/Applications/RealFlow2013/RealFlow.app/Contents/MacOS/RealFlow64"

prompt> ./bin/realflow -nogui

Command Line Version Flags

The RealFlow command line version provides a wide variety of settings to customize a simulation. The most important option is “scenePath”, because it describes the “way” to a project file. If it is not set correctly, RealFlow aborts the simulation process. You have to be especially careful when your file is located on another volume or the folders contain blanks. Folder names with special characters should be avoided under all circumstances, not only in combination with RealFlow. Under Windows a scene path could look like this:

prompt> realflow -nogui E:/RF5_Simulations/BeachScene_01/BeachScene_01.flw

Linux commands are similar, though the path notation is different:

prompt> realflow -nogui /home/att/projects/emitter/emitter.flw

And under OS X (“RealFlow.app/Contents/MacOS/” is not written here):

 prompt> realflow64 -nogui /Volumes/RF5_Simulations/BeachScene_01/Beach_Scene_01.flw

It is also sometimes required to change the number of threads:

 prompt> realflow(64) -nogui - threads 8 scene path...

Another interesting option is called “mesh”. To use this feature it is, of course, necessary to have an accordingly prepared scene: You need a complete project including at least one mesh node with appropriate settings and cached simulation data. The “mesh” flag does not create these entities for you, it only tells RealFlow to switch to meshing mode. The usage is the same as before:

prompt> realflow(64) -nogui -mesh scene path...

It is even possible to trigger a preview with the integrated Maxwell “FIRE” engine from the command line. Here, the first 50 images will be rendered:

 prompt> realflow(64) -maxwell -range 0 50 scene path...

Here is an example with the "help" flag:

With a shell or Python script it is no problem to prepare several “RealFlow -nogui” calls and batch simulate your scene over night, for example. It is a convenient way to run multiple projects without the need to monitor everything and start each process manually. This is a list of all available flags:

Command Line Previews

If you have already had a look at the table with the flags, then you know that it is even possible to render previews with RealFlow's implementation of the Maxwell Render engine via the command line application. The “-maxwell” flag tells RealFlow that it has to switch from simulation to render mode. An example (Linux):

"./bin/realflow -nogui -maxwell -range 10 50 ~/scenes/test/test.flw"

The mode of operation for previews and renders is exactly the same as described above. If you want to shorten this process and trigger a render via the command line over RealFlow's GUI application then you only have to click on an icon: