ESP: The Engineering Sketch Pad Rev 1.14 -- December 2018 1. Prerequisites The most significant prerequisite for this software is OpenCASCADE and in the past ESP has attempted to support any revision (after 6.5.1) of distributions from OpenCASCADE directly or from the OpenCASCADE Community Edition (OCE). This is no longer the case, though you can still build ESP against all of these versions. As of the last ESP release, only the prebuilt versions marked 6.8.1 (available at http://acdl.mit.edu/ESP) will be supported. Please DO NOT report any problems with any other versions of OpenCASCADE -- much effort has been spent in "hardening" this release. If you already have an OpenCASCADE 6.8.1, you may want to check the time/date stamp and see if you need to refresh. Another prerequisite is a WebGL/Websocket capable Browser. In general these include Mozilla's FireFox and Google Chrome. Apple's Safari works at rev 6.0 or greater. There have been some reported problems using Safari rev 11.0 under OSX 10.13. Reports that FireFox at 61.0.x on LINUX is flakey -- update to 62.0.0 (or higher). Internet Explorer/Edge is NOT supported because of a problem in its Websockets implementation. Also, note that there are some problems with Intel Graphics and some WebGL Browsers. For LINUX, "zlib" development is required. CAPS has a dependency on UDUNITS2, and potentially on Python and other applications. See Section 2.3. 1.1 Source Distribution Layout In the discussions that follow, $DISROOT will be used as the name of the directory that contains: README.txt - this file bin - a directory that will contain executables CAPSexamples - a directory with CAPS examples config - files that allow for automatic configuration data - test and example scripts doc - documentation ESP - web client code for the Engineering Sketch Pad externApps - the ESP connections to 3rd party Apps (outside of CAPS) include - location for all ESP header files lib - a directory that will contain libraries, shared objects and DLLs SLUGS - the browser code for Slugs (web Slugs client) src - source files (contains EGADS, CAPS, wvServer & OpenCSM) training - training slides and examples udc - a collection of User Defined Components wvClient - simple examples of Web viewing used by EGADS 1.2 Release Notes 1.2.1 EGADS The most significant recent change (Rev 1.13) is that the OpenCASCADE evaluators (and inverse evaluators) have been rewritten and replaced with code that is both faster and fully threadable. This is consistent with a new ESP offering EGADSlite, which is an evaluation-based library specifically designed for HPC environments that need to perform parallel meshing, solver-based mesh adaptation and/or curved (higher order) meshes in situ. 1.2.2 ESP There have been several new or modified commands, including EVALUATE, EXTRUDE, INTERSECT, OUTPMTR, REVOLVE, SELECT, and STORE. See section 8.1 of ESP-help.html for details. There have been a large number of bug fixes to ESP, all of which are described in section 8.2 of ESP-help.html. Several new UDPs have been added, including a simple turbomachinery airfoil generator (udpStag), a general hexahedron generator (udpHex), a radial waffle for fuselage structures (udpRadwaf), a method for recursively calling OpenCSM (udpCsm), a way of printing the bounding boxes (udfPrintBbox) and boundary representations (udfPrintBrep) of a Body, and a way of drooping the leading or trailing edge of an airfoil (udfDroop). Also, udfEditAttr and udpWaffle have been improved to allow users to alternatively use inputs from (in-line) files. 1.2.3 Known issues in v1.14: Edges are not always drawn in ESP when running a LINUX64 virtual machine under VMware with OSX as the host operating system. Some of the keyboard shortcuts are intercepted by some of the Browsers. Therefore a third line of buttons have been added to the left side of ESP; pressing the "L" button does the same thing as pressing . CAPS Bounds that span multiple Faces (with differing underlying Surfaces) may no be able to be reparameterized. 2. Building the Software The config subdirectory contains scripts that need to be used to generate the environment both to build and run the software here. There are two different build procedures based on the OS: If using Windows, skip to section 2.2. 2.1 Linux and MAC OSX The configuration is built using the path where the OpenCASCADE runtime distribution can be found. This path can be located in an OpenCASCADE distribution by looking for a subdirectory that includes an "inc" or "include" directory and either a "lib" or "$ARCH/lib" (where $ARCH is the name of your architecture) directory. Once that is found, execute the commands: % cd $DISROOT/config % ./makeEnv **name_of_OpenCASCADE_directory_containing_inc_and_lib** An optional second argument to makeEnv is required if the distribution of OpenCASCADE has multiple architectures. In this case it is the subdirectory name that contains the libraries for the build of interest (CASARCH). This procedure produces 2 files at the top level: ESPenv.sh and ESPenv.csh. These are the environments for both sh (bash) and csh (tcsh) respectively. The appropriate file can be "source"d or included in the user's startup scripts. This must be done before either building and/or running the software. For example, if using the csh or tcsh: % cd $DISROOT % source ESPenv.csh or if using bash: $ cd $DISROOT $ source ESPenv.sh Skip to section 2.3. 2.2 Windows Configuration IMPORTANT: The ESP distribution and OpenCASCADE MUST be unpackaged into a location ($DISROOT) that has NO spaces in the path! The configuration is built from the path where the OpenCASCADE runtime distribution can be found. MS Visual Studio is required and a command shell where the 64bit C/C++ compiler should be opened and the following executed in that window (note that MS VS 2012, 2013, 2015 and 2017 are all supported). The Windows environment is built simply by going to the config subdirectory and executing the script "winEnv" in a bash shell (run from the command window): C:\> cd $DISROOT\config C:\> bash winEnv D:\OpenCASCADE6.8.1 winEnv (like makeEnv) has an optional second argument that is only required if the distribution of OpenCASCADE has multiple architectures. In this case it is the subdirectory name that contains the libraries for the build of interest (CASARCH). This procedure produces a single file at the top level: ESPenv.bat. This file needs to be executed before either building and/or running the software. This is done with: C:\> cd $DISROOT C:\> ESPenv Check that the method that you used to unzip the distribution created directories named $DISTROOT\bin and $DISTROOT\lib. If it did not, create them using the commands: C:\> cd $DISTROOT C:\> mkdir bin C:\> mkdir lib 2.3 CAPS Options CAPS is now "officially" part of ESP and gets constructed automatically as part of the ESP build procedure. There have been some API changes at this release that should be noted by previous users/developers. These can be see in the CAPSapi/AIMdevel documents marked in the color red. From this point forward we will refrain from making these kinds of disruptive changes. CAPS requires the use of the Open Source Project UDUNITS2 for all unit conversions. Since there are no prebuilt package distributions for the MAC and Windows, the CAPS build procedure copies prebuilt DLL/DyLibs to the lib directory of ESP. Because most Linux distributions contain a UDUNITS2 package, another procedure is used. If the UDUNITS2 development package is loaded in the OS then nothing is done. If not loaded, then a static library is moved to the ESP lib directory. The use of a static library is to avoid having two differing versions of a shared object on the same system if installed later (which would only cause problems). 2.3.1 Python with CAPS (pyCAPS) Python may be used with CAPS to provide testing, general scripting and demonstration capabilities. The Python development package is required under Linux. The building of pyCAPS is turned on by 2 environment variables: PYTHONINC is the include path to find the Python includes for building PYTHONLIB is a description of the location of the Python libraries and the library to use The execution of pyCAPS requires a single environment variable: PYTHONPATH is a Python environment variable that needs to have the path $DISROOT/lib included. For MACs and LINUX the configuration procedure inserts these environment variables with the locations it finds by executing the version of Python available in the shell performing the build. If makeEnv emits any errors related to Python, the resultant environment file(s) will need to be updated in order to use Python (the automatic procedure has failed). For Windows ESPenv.bat must be edited, the "rem" removed and the appropriate information set (if Python exists on the machine). Also note that the bit size (32 or 64) of Python that gets used on Windows must be consistent with the build of ESP, which is now only 64bit. For Example on Windows (after downloading and installing Python on D:): set PYTHONINC=D:\Python27\include set PYTHONLIB=D:\Python27\Libs\python27.lib Also, in order to run the examples in the CAPS training it is necessary to have a Python installation that includes numpy and matplotlib. 2.3.2 3rd Party Environment Variables CAPS is driven by a plugin technology using AIMs (Analysis Interface Modules). These AIMs allow direct coupling between CAPS and the external meshers and solvers. Many are built by default (where there are no licensing problems or other dependencies). The CAPS build subsystem will respond to the following (if these are not set, then the AIMs for these systems will not be built): AFLR (See Section 4.1): AFLR is the path where the AFLR distribution has been deposited AFLR_ARCH is the architecture flag to use (MacOSX-x86-64, Linux-x86-64, WIN64) -- note that this is set by the config procedure AWAVE AWAVE is the location to find the FORTRAN source for AWAVE TETGEN TETGEN is the path where the TetGen distribution has been unpacked 2.3.3 The Cart3D Design Framework The application ESPxddm is the ESP connection to the Cart3D Design Framework. On LINUX this requires that the libxml2 development package be installed. If it is, then ESPxddm is built, otherwise it is not. 2.3.4 CAPS AIM Documentation The CAPS documentation can be seen in PDF form from within the directory $DISROOT/doc/CAPSdoc. Or in html by $DISROOT/doc/CAPSdoc/html/index.html. 2.4 The Build For any of the operating systems, after properly setting the environment in the command window (or shell), follow this simple procedure: % cd $DISROOT/src % make or C:\> cd $DISROOT\src C:\> make You can use "make clean" which will clean up all object modules or "make cleanall" to remove all objects, executables, libraries, shared objects and dynamic libraries. 3.0 Running 3.1 serveCSM and ESP To start ESP there are two steps: (1) start the "server" and (2) start the "browser". This can be done in a variety of ways, but the two most common follow. 3.1.1 Procedure 1: have ESP automatically started from serveCSM If it exists, the ESP_START environment variable contains the command that should be executed to start the browser once the server has created its scene graph. On a MAC, you can set this variable with commands such as % setenv ESP_START "open -a /Applications/Firefox.app $ESP_ROOT/ESP/ESP.html" or % export ESP_START="open -a /Applications/Firefox.app $ESP_ROOT/ESP/ESP.html" depending on the shell in use. The commands in other operating systems will differ slightly, depending on how the browser can be started from the command line, for example for Windows it may be: % set ESP_START=""C:\Program Files (x86)\Mozilla Firefox\firefox.exe" %ESP_ROOT%\ESP\ESP.html" To run the program, use: % cd $DISROOT/bin % ./serveCSM ../data/tutorial1 3.1.2 Procedure 2: start the browser manually If the ESP_START environment variable does not exist, issuing the commands: % cd $DISROOT/bin % ./serveCSM ../data/tutorial1 will start the server. The last lines of output from serveCSM tells the user that the server is waiting for a browser to attach to it. This can be done by starting a browser (FireFox and GoogleChrome have been tested) and loading the file: $DISROOT/ESP/ESP.html Whether you used procedure 1 or 2, as long as the browser stays connected to serveCSM, serveCSM will stay alive and handle requests sent to it from the browser. Once the last browser that is connected to serveCSM exits, serveCSM will shut down. Note that the default "port" used by serveCSM is 7681. One can change the port in the call to serveCSM with a command such as: % cd $DISROOT/bin % ./serveCSM ../data/tutorial1 -port 7788 Once the browser starts, you will be prompted for a "hostname:port". Make the appropriate response depending on the network situation. Once the ESP GUI is functional, press the "help" button in the upper left if you want to execute the tutorial. 3.2 egads2cart This example takes an input geometry file and generates a Cart3D "tri" file. The acceptable input is STEP, EGADS or OpenCASCADE BRep files (which can all be generated from an OpenCSM "dump" command). % cd $DISROOT/bin % ./egads2cart geomFilePath [angle relSide relSag] 3.3 vTess and wvClient vTess allows for the examination of geometry through its discrete representation. Like egads2cart, the acceptable geometric input is STEP, EGADS or OpenCASCADE BRep files. vTess acts like serveCSM and wvClient should be used like ESP in the discussion in Section 3.1 above. % cd $DISROOT/bin % ./vTess geomFilePath [angle maxlen sag] 3.4 Executing CAPS through Python % python pyCAPSscript.py (Note: many example Python scripts can be found in $DISROOT/CAPSexamples/pyCAPS) 3.5 CAPS Training The examples and exercises in the $DISROOT/training/CAPS/data rely on 3rd party software. Specifically, the sansLIP examples require the sansLIPAIM which is not distributed with this source, but is available in the PreBuilt distributions. Other cases function with this source distribution with one caveat. For Linux, the training examples only function on 'newer' operating systems such as RHEL7 or Ubuntu 14.04. Older Linux operating systems may error with a message similar to: libstdc++.so.6: version `GLIBCXX_3.4.19' not found 4.0 Notes on 3rd Party Analyses 4.1 The AFLR suite Building the AFLR AIMs (AFLR2, AFLR3 and AFLR4) requires AFLR_LIB at 16.27.6,290.1894.743 or higher. Note that built versions of the so/DLLs can be found in the PreBuilt distributions and should be able to be used with ESP that you build by placing them in the $DISROOT/lib directory. 4.2 Athena Vortex Lattice The interface to AVL is designed for V3.36, and the avl executable is provided in $DISROOT/bin. 4.3 Astros and mAstros Both Astros and a limited version (microAstros or more simply) mAstros can be run with the Astros AIM. A mAstros executable is part of this distribution and is used with the CAPS training material. The pyCAPS Astros examples use the environment variable ASTROS_ROOT (set to the path where Astros can be found) to locate Astros and it's runtime files. If not set it defaults to mAstros execution. 4.4 Cart3D The interfaces to Cart3D will only work with V1.5.5. 4.5 Fun3D The Fun3D AIM supports Fun3D V12.4 or higher. 4.6 Mystran On Windows, follow the install instructions MYSTRAN-Install-Manual.pdf carefully. The CAPS examples function only if MYSTRAN.ini in the Mystran bin directory is an empty file and the MYSTRAN_directory environment variable points to the Mystran bin directory. Mystran currently only functions on Windows if CAPS is compiled with MSVC 2015 or higher. This may be addressed in future releases. 4.7 NASTRAN Nastran bdf files are only correct on Windows if CAPS is compiled with MSVC 2015 or higher. This may be addressed in future releases. 4.8 Pointwise The current connections to Pointwise are through the EGADS app egads2nmb and requires Pointwise V18.2. The next official release of Pointwise will be able to import EGADS files directly. Also, there is an automation effort associated with CAPS that will have a Pointwise AIM that will be able to generate meshes "hands-off" as part of the release of ESP after the next official release of Pointwise. 4.9 SU2 Supported versions are: 4.1.1 (Cardinal), 5.0.0 (Raven), 6.1.0 (Falcon). SU2 version 6.0 will work except for the use of displacements in a Fluid/Structure Interaction setting. 4.10 xfoil The interface to xfoil is designed for V6.99, and the xfoil executable is provided in $DISROOT/bin. Note that multiple 'versions' of xfoil 6.99 have been released with differing output file formats.