ESP: The Engineering Sketch Pad
                             Rev 1.25 -- June 2024

                          https://acdl.mit.edu/ESP/


0. Warning!

    You CANNOT download the distributions using a browser. For instructions on 
    how to get ESP see MACdownloads.txt on the web site.


1. Prerequisites

    The major prerequisite is a WebGL/Websocket capable Browser. In general 
    these include Safari, Mozilla's FireFox and Google Chrome. Also, note that 
    there are some problems with Intel Graphics and some WebGL Browsers. The 
    setup scripts set the browser to Safari. XQuartz at a minimum revision 
    of 2.8.1 is required for some of the CAPS applications. 

    Intel x86_64 based machines are currently supported with a native 
    PreBuilt distribution: ESP125-macos-x86_64.tgz.

       Note: this was built on a macOS 13.3.1 machine / Xcode 14.0.3 and developed 
       with the target machine set to OSX 10.13 so any version of OSX should work
       from 10.13 on.

    Apple arm64 (M1/M2) based machines are currently supported with a native 
    PreBuilt distribution: ESP125-macos-arm64.tgz.

       Note: this was built on a macOS 13.3.1 machine / Xcode 14.0.3 and developed 
       with the target machine set to macOS 11.0 so any version of macOS should work
       from 11.0 on. Rosetta2 are required for some of the CAPS applications. 
       Rosetta2 can be installed by executing the following command:
       "softwareupdate --install-rosetta".

1.1 Distribution Layout

    README.txt        - this file
    EngSketchPad      - the source and built ESP components
    OpenCASCADE-7.8.0 - the version of OpenCASCADE used
    Python-3.11.9     - a prebuilt version of Python
    setup.command     - the ESP setup script
    FileIcon          - a command that sets the Icon for a file


2.0 Installation

    If you have not set the Terminal shell "close the window if cleanly exits", 
    you may want to do so. Open the Terminal Preferences and in the Settings 
    group/Profiles and the Shell tab select the appropriate option in "When the 
    shell exits:".

    Place "ESP125-macOS-x86_64.tgz" or "ESP125-macOS-arm64.tgz" in the desired 
    location (that has no spaces in the path). Extract ESP by double-clicking 
    on the tgz file (note the Warning above).

    Double click on "setup.command" in the extracted location. If OSX puts
    up a message saying that this cannot be opened because it is from an
    unidentified developer, then try control-clicking and select "open". If
    this fails or asks you for a password where you do not have privileges
    then open a Terminal and "cd" to the location with "setup.command", then
    type: xattr -d com.apple.quarantine setup.command
    You now should be able to double-click "setup.command".

    Executing "setup.command"  will create 2 desktop shortcuts to a command 
    prompt that should be used for all ESP execution. Double clicking on
    either shortcut will execute either a shell or ESP itself which has all
    of the proper paths and environment variables set.

    The desktop command prompt (labeled "ESP 1.25") when double-clicked starts 
    up the appropriate shell and sets the environment, then leaves the shell
    open so that you can freely execute (at the command line) any ESP/CAPS
    application.

    The command prompt labeled "run ESP 1.25" starts up "serveESP" directly
    and terminates when the ESP browser session completes.

    Note: you may see the extension ".command" on the icons. This can be 
    rectified by unsetting "Show all filename extensions" in the Finder
    preferences Advanced tab.


3.0 Running ESP

3.1 serveESP

    To run the program, either just double click on the "runESP1.25" shortcut 
    or double click on the Desktop ShortCut "ESP1.25" and use:

         % serveESP ../data/tutorial1

    Once the browser starts, you may 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).

        % 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 serveESP.

        % vTess geomFilePath [angle maxlen sag]


4.0 CAPS (Computational Aircraft Prototype Syntheses)

    Note that CAPS has been built with the version of Python that comes with
    this distribution. If you wish to use ESP in a larger Python environment 
    it is strongly suggested that you build ESP.

4.1 Documentation

    The CAPS documentation can be seen in PDF form from within the directory
    $ESP_ROOT/doc/CAPSdoc. Or in html by $ESP_ROOT/doc/CAPSdoc/html/index.html.

4.2 Executing CAPS through Python

    % python pyCAPSscript.py  (Note: many example Python scripts can be 
                                     found in $ESP_ROOT/CAPSexamples/pyCAPS)

4.4 MPI for Toolkit for the Analysis of Composite Structures (TACS)

    TACS is provided with pre-compiled versions of MPI. Please use mpiexec_esp    
    to execut python TACS scripts in parallel.