Escolar Documentos
Profissional Documentos
Cultura Documentos
Justin Weber
1 Intro 2
2 Methodology 3
3 Installation 5
3.1 From Binaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.2 From the Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
4 Features 9
4.1 Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.2 Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4.3 Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.4 Quick-Access Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.5 Quick-Access Option Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.6 Information/Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.7 Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4.8 Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.9 Keyword Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
4.10 Grid Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
4.11 Condition Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.12 Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.13 Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
4.14 Command Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
5 Tutorials 27
5.1 Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.2 2D Fluid Bed with a Jet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.3 3D Flow over a STL Sphere . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
6 Developer Guide 29
6.1 Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
6.2 The make.py Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
6.3 Contributing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.4 Style Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
i
6.5 Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
6.6 Building Binaries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
7 Help 33
7.1 Log File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
7.2 Mailing List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
7.3 Issues/Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
8 Release Notes 35
8.1 Version 0.1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
8.2 Version 0.1Beta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
10 Code Statistics 39
11 Disclaimer 40
ii
mfixgui Documentation, Release 0.1 release
Welcome to the mfixgui documentation. Please use this documentation to learn more about the
mfixgui, including the methodology behind the gui, how to install the gui, the current set of fea-
tures, tutorials for learning the gui, as well as how to find help when problems are encountered.
CONTENTS 1
CHAPTER
ONE
INTRO
The mfixgui has been designed to act as a front end tool that allows users to quickly set-up MFiX1
(Multiphase Flow with Interphase eXchange) computational fluid dynamic (CFD) models, run the
developed models, and provide post-processing tools with the goal of making MFiX easy to use.
The mfixgui is not required to run MFiX and does not need a valid MFiX source code to function.
However, having a valid MFiX source code allows the gui to extract keyword documentation for
error checking and documentation.
MFiX2 (Multiphase Flow with Interphase eXchanges) is a general purpose computer code devel-
oped at the National Energy Technology Laboratory (NETL) for describing the hydrodynamics,
heat transfer, and chemical reactions in fluid-solid systems.
The GUI is written in pure Python, leveraging the strengths of Python for quick code development,
extensive existing libraries, and flexibility. The GUI will run on any operating system that Python
can be installed in including Linux, Windows, and Mac.
The GUI uses Qt either through PyQt4 or PySide wrappers. The GUI also takes advantage of the
following Python libraries which are included in the source:
spyder3 - Multilanguage text editor
pyqtgraph4 - Fast plotting library built on Qt
docx5 - Library for creating MS Office *.docx files
1
https://mfix.netl.doe.gov/
2
https://mfix.netl.doe.gov/
3
https://code.google.com/p/spyderlib/
4
http://www.pyqtgraph.org/
5
https://github.com/python-openxml/python-docx
2
CHAPTER
TWO
METHODOLOGY
The mfixgui is written in the Python1 programing language and utilizes the core Python libraries
as well as a collection of third party libraries including:
A Qt2 wrapper: PyQt43 -or- PySide4
Numpy5
As well as a couple third party libraries included with the source:
spyder6 - Multilanguage text editor
pyqtgraph7 - Fast plotting library built on Qt
docx8 - Library for creating MS Office *.docx files
The mfixgui uses the existing files and file structures of a typical MFiX input deck. The mfix.dat
file is the core file that stores the majority of the MFiX simulations parameters. This file is created
and/or opened by the gui.
The widgets of the gui interact with the mfix.dat file through a project manager, which sends the
required updates to the widgets that can change that value including the text editor. When an update
is received by the text editor, the text editor searches for the key/value. If it finds the key/value,
it will be replaced with the current value. If the key/value cannot be found, the editor tries to
intelligently place the key/value with similar keys/values.
If the mfix.dat file is edited using the editor, a diff is performed identifying the text that was change.
This text is then parsed with the updated key/values sent to the project manager. The project
manager then sends the updated key/value to the widgets that display and/or edit the key/value.
1
https://www.python.org/
2
http://qt-project.org/
3
https://wiki.python.org/moin/PyQt
4
http://qt-project.org/wiki/PySide
5
http://www.numpy.org/
6
https://code.google.com/p/spyderlib/
7
http://www.pyqtgraph.org/
8
https://github.com/python-openxml/python-docx
3
mfixgui Documentation, Release 0.1 release
4
CHAPTER
THREE
INSTALLATION
Using a system specific binary is the easiest and fastest way to get the GUI up and running. Simply
download the correct binary for your operating system and execute the binary. The binary files are
compressed collections of the source files, data files and libraries needed to run the GUI. Python
and the other required libraries are not needed since they are included in the binary.
3.1.1 Windows
Note: Command line arguments can be passed through the command line, see Command Line
Arguments.
3.1.2 Linux
5
mfixgui Documentation, Release 0.1 release
Note: Command line arguments can be passed through the command line, see Command Line
Arguments.
Since this application is pure python and the package construction is such that it can run outside of
PythonXX\Lib\site-packages, this package can simply be unzipped and copied anywhere
on users system and run assuming the requirements are met.
The gui source code is distributed as a compressed tar ball for Linux systems. To decompress and
extract the source, assuming that you are in the directory containing the source:
$ tar xzf mfix-gui.tar.gz
Note: The actual tar ball could be named differently depending on the release.
You can also use setuptools to install the source to your Python installation, however this is not
necessary:
$ python setup.py install
To start the GUI, the file .../mfixgui/startgui.py needs to be executed with python either
directly:
3.2.4 Requirements
Required Libraries
Optional libraries
Gui functionality that depends on these will be disabled if the libraries are not found.
1. lxml is required for building the mfix keyword documentation.
2. vtk is required for viewing 3D graphics and cut-cell post processing.
Checking Requirements
These requirements can be checked by running the make.py utility assuming the first requirement
Python is met:
$ python make.py requirements
Acquiring Libraries
These requirements can be easily met by using one of the python distributions which include
numerous python libraries such as:
Windows
Pythonxy3
Pyzo4
3
https://code.google.com/p/pythonxy/
4
http://www.pyzo.org/index.html
Anaconda5
Enthought Canopy6
Unofficial Binaries7
Linux
Pyzo8
Anaconda9
Enthought Canopy10
MAC OS-X
Pyzo11
Anaconda12
Enthought Canopy13
5
http://continuum.io/downloads
6
https://www.enthought.com/products/canopy/
7
http://www.lfd.uci.edu/ gohlke/pythonlibs/
8
http://www.pyzo.org/index.html
9
http://continuum.io/downloads
10
https://www.enthought.com/products/canopy/
11
http://www.pyzo.org/index.html
12
http://continuum.io/downloads
13
https://www.enthought.com/products/canopy/
FOUR
FEATURES
4.1 Project
A MFiX Project is simply a directory where the project files are located. At a minimum, this
directory contains a mfix.dat file. This directory will contain other files such as:
1. geometry.stl - stl file if used for geometry
2. mfix.exe - compiled mfix
3. and other files.
4.2 Core
The core gui is mainly comprised of a tab widget and a mdi area. The tab widget provides access
to a collection of widgets that allow editing of various key/values. The tabs include:
General - edit run name, description, units, time controls, etc.
Materials - import/edit material properties
Gas - edit constant gas properties
Solids - create/edit solids
Solids Model - edit drag model, restitution, packed void fraction, etc.
Grid - edit grid properties
Solver - edit solver properties
Output - edit output properties
Post - access to post processing tools
Developer - access to developer tools
The mdi area provides windows for larger widgets such as the grid editor and text editor.
9
mfixgui Documentation, Release 0.1 release
4.2. Core 10
mfixgui Documentation, Release 0.1 release
The File menu provides the major gui operations such as:
Open Project - Open a project
Recent Project - list of the 10 most recent projects
New Project - Create a new project
Save Project - save the current project
Save Project As - Copy and save the current files to a new directory
Open Text File - Open any text file (*.txt, *.py, *.f, *.c, etc.)
New Text File - Create a new text file
Run Model - run the current model
Restart Model - restart the current model (Not functional)
Compile - Compile based on current source profile
Paraview - Launch Paraview
C3M - Launch C3M (only on windows)
Close - Close the gui
A customizable quick-access tool bar provides a short-cut to functions in the main menu. The
functions can be customized using the drop down menu.
Some of the gui preferences can be quickly access through the Quick-Access Option Menu. Access
includes selecting of a source profile, rebuilding the mfix documentation, changing of the font size,
and access to the Preferences dialog.
The information/help menu provides quick access to this documentation through the default web
browser as well as the NETL MFS website and a collection of MFIX GUI video tutorials located
on YouTube.
4.7 Preferences
The preferences dialog allows the user to set various preferences. These preferences are saved in
the users home directory in a file named .mfixGuiConfig.ini. The preferences dialog has
several panes including:
1. General
The General pane allows the user to show/hide the developer tab.
2. Appearance
The Appearance pane provides access to the GUI font and size as well as the ability to change
the gui color scheme.
3. Feedback
The Feedback pane provides options to allow the MFiX gui to access the internet. Currently,
this is to only read the MFiX1 website to collect the latest news and display it on the splash
screen. The generation of the log file can also be turned on/off.
4. MFiX Source
The MFiX Source pan allows the user to setup mfix source profiles which point to a spe-
cific MFiX source directory and allow for various compiler options. The mfixgui uses this
information when compiling as well as running a project.
5. External Programs
The External Programs pane provide access to the system calls to C3M and Paraview through
the gui. On Windows, the GUI does a good job of finding Paraview and C3M if the Envi-
ronment Variable is selected (as apposed to Specific Path).
1
https://mfix.netl.doe.gov/
4.7. Preferences 14
mfixgui Documentation, Release 0.1 release
6. Text Editor
The Text Editor pane allows the user to change the text editor font and font size, independent
of the gui text font and size.
7. Grid Editor
The Grid Editor pane allows the suer to change the line colors and styles that are used to
draw the grid in the grid editor widget.
8. Run Options
The Run Options pane allows the user to change the sampling rate of the log file, in seconds,
as well as the name of the log file that MFiX generates while it is running.
4.8 Editor
The editor is a general purpose text editor that provides syntax highlighting for Python,
FORTRAN, C, C++, mfix.dat, as well as other files. This editor is based on spyder2 and pro-
2
https://code.google.com/p/spyderlib/
4.8. Editor 15
mfixgui Documentation, Release 0.1 release
vides a set of tools including a search toolbar, on-the-fly error checking, keyword completion (for
mfix.dat files), an outline, and keyword information.
4.8.1 Search
A search tool is included and can be display by pressing ctrl + f. The search bar supports
regular expressions, case sensitivity, whole words, and match highlighting.
Inline error checking is continuously performed. Errors are indicated with icons in the line number
area at the line with the error. Some error are also underlined to show specific text that is causing
4.8. Editor 16
mfixgui Documentation, Release 0.1 release
the error. Hovering over the error icon will display information about the specific error. The errors
that are checked include:
valid keyword
correct number of arguments
correct keyword data type (double, int, string, Boolean)
line lengths
Keyword completion is provided for mfix.dat files using ctrl + space. This will show a list
of all possible keywords, with the closest keyword highlighted. To complete the keyword from the
list, press the tab key.
Figure 4.10: Screenshot of the Editor widget showing the keyword completion.
4.8. Editor 17
mfixgui Documentation, Release 0.1 release
4.8.4 Outline
The outline provides quick navigation of a mfix.dat file. Major sections in the outline are defined
using # <name> SECTION where <name> is any text such as RUN CONTROL. Subsections
can be defined using ! <name> where <name> is any text such as Gas Outlet. Clicking on
these sections will jump to that location in the mfix.dat file. The outline is update periodically.
Keyword information can be displayed by placing the cursor in a keyword and pressing crtl +
i. A popup will appear displaying the first sentence of the keyword description. The keyword will
also be sent to the Keyword Documentation widget for more keyword information.
The keyword documentation can be view in this widget by entering the keyword in the combobox
and pressing enter. The documentation is built from the currently selected source code. This
widget is also linked to the editor so that if crtl+ i is pressed in the text editor, the selected
keyword will be sent to the keyword documentation widget.
The grid editor allows editing of the grid as well as ICs, BCs, ISs, and point sources. The grid
editor also displays stl files and allows for editing of the stl file.
All of the grid items allow editing. Items that can be resized or moved will respond
to mouse-over events, drawing resize handles, etc. Most items also have item spe-
cific toolbars which can be accessed by moving the mouse over the item and clicking the
right-mouse-button.
The objects (grid, geometry, ICs, BCs, etc.) in the grid editor (QtScene) are layered. Because of
this, only the object on top will be able to interact with mouse events. To access the other objects,
the objects on top need to be hidden. This can be accomplished through the option menu on the
grid editor toolbar or by clicking the right-mouse-button anywhere in the scene.
More detials on the grid editor tools:
4.10.1 Toolbar
This is the main tool bar for grid editor. The first set of tool buttons changes the 2D view of the 3D
grid. The second set of tool buttons allows for the editing of major gridlines and the creation of
conditions (ICs, BCs, ISs, and PSs). To create a condition, select a condition from the list. If the
condition is a IC, BC, or IS, use the mouse to create the condition by dragging the mouse while
holding the left-mouse-button. The last tool button provides access to various options. The
same option menu can be accessed by clicking the right-mouse-button anywhere in the grid
editor, not over a toolbar or graphic item.
The toolbar can be moved anywhere in the grid editor by using the grip. If the toolbar contacts the
edge of the grid editor, the toolbar will automatically rotate.
This toolbar shows the current position of the mouse in the coordinates of the model. Specific units
can be specified to convert from the standard MFiX units (cgs, or si). This toolbar can be moved
anywhere in the grid editor by using the handle.
STL files can be translated, rotated, and scaled using the STL editor. To access the STL editing
functions, mouse over the STL file and click the right-mouse-button. This will open the
toolbar where various transformations can be applied. Simply clicking anywhere on the grid editor
will hide to toolbar. Any transformations to the stl file will be saved to geometry.stl when the
project is saved.
Grid patches ( minor gridlines in-between the major grid lines) can be edited directly from the grid
editor by placing the mouse in the patch to be edited and clicking the right-mouse-button.
This will show the grid patch editor. The number of cells in that patch can now be edited. Simply
clicking anywhere on the grid editor will hide to toolbar.
The condition editor allows for the creation and editing of initial conditions, boundary conditions,
and point sources. The condition editor can either be included in the MDI are or the ribbon. This
can be changed through the preferences.
4.12 Plot
The plot widget provides a tabbed location for plots. Plots are populated through various widgets
located throughout the gui such as on the Post tab.
4.13 Console
The console widget provides a tabbed widget to store various consoles. This includes the guis
internal console which exposes the classes, functions, and variables of the gui. This is mainly for
4.13. Console 24
mfixgui Documentation, Release 0.1 release
4.13. Console 25
mfixgui Documentation, Release 0.1 release
debugging purposes, however could be used for scripting. The stream of a running simulation can
also be seen in a tab.
A collection of command line arguments have been provided to allow quick access and default
over-rides to gui features including:
Short Long Description
-h help Print the help message
-p P project P Open the project path P
-i interact Open interact GUI
-dg docwritegui Open document writer GUI
-l long Write all available keywords
-s S mfixsource S Path, S, to MFIX source code
-dx D docx D File path and name, D, to save keyword documentation to.
-w W H winsize W H Specify the window size, W H
-qt W qtwrapper W Force the usage of a Qt wrapper (pyqt4 or pyside)
-dp defaultpref Over-write user preferences with defaults
-d debug Force debug level: logging
-v version Show Version and exit
FIVE
TUTORIALS
Use these tutorials to help learn about the mfixgui interface and the various tools included with the
gui.
5.1 Quickstart
This tutorial demonstrates how to luanch, setup, and use the features of the MFIX GUI.
Link to YouTube video1
This tutorial demonstrates how to create a 2D Cartesian grid fluidized bed with a jet in the middle.
Two initial conditions and four boundary conditions are created. Running the model in serial and
showing the results in Paraview are also demonstrated.
Link to YouTube video2
The following properties are used:
Solid
Diameter: 0.04 cm
Density: 2.0 g/cm3
Gas
Density: 1.2E-3 g/cm3
Viscosity: 1.8E-4 g/(cm*s)
Two Fluid Model
1
https://youtu.be/oNP2ojlMejs
2
https://youtu.be/NEgsKR7Cvnc
27
mfixgui Documentation, Release 0.1 release
This tutorial demonstrates how to create a 3D Cartesian grid with compressible flow over a sphere
defined with an STL file. One initial condition and three boundary conditions are created. Running
the model in serial and displaying the results with Paraview are also demonstrated.
Link to YouTube video3
3
https://youtu.be/PyrUgw1EWQc
SIX
DEVELOPER GUIDE
29
mfixgui Documentation, Release 0.1 release
make.py contains a collection of scripts useful for performing a variety of tasks associated with
the mfixgui including:
checking to see if the requirements are met
$ python make.py -rq
running tests
$ python make.py -t
or
$ python make.py -r
6.3 Contributing
If you develop any tools or fix any bugs associated with the mfixgui, please consider contributing
your work to the continued development of the mfixgui. Contributions from the MFiX community
are encouraged.
Contributions can either be sent through the mailing list or if continued and significant development
is desired, access to the git repository4 can be arranged.
6.5 Tests
Any contribution should also include unit tests. pytest6 is used to run tests. Qt also includes a
testing tool that mimics user interaction with widgets:
from mfixgui.guilib.qtwrapper import QtGui, QtCore, QtTest
6.3. Contributing 31
mfixgui Documentation, Release 0.1 release
Binaries are located in the dist directory. Build files can be cleaned by running:
$ python make.py -cl
8
http://sourceforge.net/projects/pywin32/files/pywin32/
9
http://www.pyinstaller.org
SEVEN
HELP
Please read the docs! If you cant find help in the documentation, send detailed questions or bugs
to the mailing list.
If bugs do occur, the GUI creates and writes to a log file named mfixGui.log located:
On Windows: C:\Users\username\
On Linux: ~/
You need to subscribe to the mailing list before you can send or recieve messages. You may
subscribe to the mailing list here1 . You may also search the archived messages to see if a simular
question has already been submitted.
Mailing list etiquette:
Please allow sufficient time for a response.
Please describe the question or bug in as much detail as possiable. If avaliable include the
mfix.dat file and GUI log file.
7.3 Issues/Bugs
If you have access to the git repository2 , please search the current issues. If the issue has not been
reported, please create a new issue describing in detail how you got to the issue and what happened.
1
https://mfix.netl.doe.gov/sympa/subscribe/mfix-gui
2
https://mfix.netl.doe.gov/gitlab/develop/mfix-gui
33
mfixgui Documentation, Release 0.1 release
If you do not have access to the git repository3 , please search the mailing list archive. If the issue
has not been reported, please send a detailed message describing how you got to the issue and what
happened.
3
https://mfix.netl.doe.gov/gitlab/develop/mfix-gui
7.3. Issues/Bugs 34
CHAPTER
EIGHT
RELEASE NOTES
docx library dependency removed (#27). This issues was caused by lxml import errors.
QValidator.validate bug fixed (#28).
easy_install not copying all directories fixed (#30).
Duplicate files in editor fixed (#34).
matplotlib dependency removed (#36).
Units displayed in the GUI now show the correct units (#38).
Keywords are now deleted from the mfix.dat file (#40).
C1 and D1 are disabled when drag != syam_obrien (#41).
Log parser fixed to handle 2015-1 MFIX release (#44).
Fixed grid editor segfault (#45).
Grid editor overhauled, multiple bugs fixed.
Fixed a collection of bugs related to the log parser.
Fixed speacies_eq index issue.
Updated logo.
35
mfixgui Documentation, Release 0.1 release
Version 0.1Beta was the first release to the public. This release contained numerous bugs, issues,
and incomplete features. The goal of this release was to receive feedback on the layout, features,
usability of the GUI.
NINE
38
CHAPTER
TEN
CODE STATISTICS
39
CHAPTER
ELEVEN
DISCLAIMER
This report was prepared as an account of work sponsored by an agency of the United States
Government. Neither the United States Government nor any agency thereof, nor any of their em-
ployees, makes any warranty, express or implied, or assumes any legal liability or responsibility
for the accuracy, completeness, or usefulness of any information, apparatus, product, or process
disclosed, or represents that its use would not infringe privately owned rights. Reference herein
to any specific commercial product, process, or service by trade name, trademark, manufacturer,
or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favor-
ing by the United States Government or any agency thereof. The views and opinions of authors
expressed herein do not necessarily state or reflect those of the United States Government or any
agency thereof.
40
CHAPTER
TWELVE
genindex
modindex
search
41