*************** OpenSeesQt *************** Stevan Gavrilovic PhD Candidate University of British Columbia A Qt build environment for OpenSees -- Open System For Earthquake Engineering Simulation Pacific Earthquake Engineering Research Center(http://opensees.berkeley.edu). Qt is an open source, cross-platform development environment that is free for many uses. Please see the license here: https://www.qt.io/licensing/ The purpose of this project is to create a package that will allow aspiring developers to get started on writing code without having to worry about the compilation environment. A program as large as OpenSees relies on many third-party libraries, often referred to as dependencies. It can be a daunting task assembling, compiling, and linking these libraries. Many times, these libraries depend on other libraries, and so on. The current list of OpenSees dependencies includes: MUMPS UMFPACK contained in Suite-Sparse SUPERLU SUPERLUMT SUPERLUDIST Scalapack ARPACK Parmetis GCC PetSc Python ** When compiling OpenSeesPy Tcl ** When compiling with Tcl interpreter Please ensure that your project complies with each library's licensing requirements. Another feature of this build platform is modularity. Developers can select from a list of build options that can be turned on and off as required. The basic configuration builds the structural analysis core. Other build options include parallel processing, reliability, and the particle finite element method (PFEM) modules. Python and Tcl interpreters are additional build options. These options are located in single configuration file called qmake.conf. By default, the environment is configured to build the core along with the parallel processing module. Other options can be turned on by deleting the '#'symbol that precedes the option; this includes the option into the build environment. Note: This project uses qmake and Qt Creator. qmake is a build tool for compiling and linking applications. Qt Creator is a free IDE (interactive development environment) that bundles code writing/editing and application building within one program. Qt Creator uses project (.pro) files. The project files contain the information required by qmake to build an application. *************** Getting Started *************** 1) Download and install Qt open source from https://www.qt.io/download The version of the Qt library is not important in this case since the library is not used in the OpenSees project (although I use Qt in other projects and recommend it) 2) Download the OpenSeesQt source code into a folder of your choice (https://github.com/steva44/OpenSees/archive/master.zip) 3) Installing the dependencies. /////MacOS///// The compiling and installing of third-party libraries is handled through a system package manager. In this case we are using the package-manager Homebrew. It is very likely that the libraries OpenSees depends on have their own dependencies, and so forth. The system package manager conveniently knows what dependencies are required and automatically installs them. Homebrew is installed by running: /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" in the macOS terminal prompt. From herein, the the word 'run' will be used to represent copying and pasting a command into the macOS terminal prompt. Homebrew maintains its own folder within '/usr/local/' directory aptly named the 'Cellar' /usr/local/Cellar/ Each dependency installed through Homebrew will have its own subfolder within the Cellar directory. Each subfolder contains that dependencies 'include' and 'lib' folders. Now that Homebew is installed, to install the required OpenSees dependencies run the following commands: brew install petsc superlu_mt superlu_dist openblas GCC arpack superlu parmetis brew uninstall --ignore-dependencies scalapack brew install mumps If compiling OpenSeesPy, Python is needed as well: brew install python Similarly for tcl: brew install tcl You can now run: brew list to get a list of all packages installed by Homebrew on your system. \!/ IMPORTANT: This project depends on many libraries. Homebrew will automatically install the newest libraries. Also, if you run the upgrade command in Homebrew, it will upgrade every library to its newest version. The library versions may have changed since the last time this project was updated. If the library versions have changed, this will cause 'file not found' errors during compilation or linking issues at runtime. The solution is to update the file paths in the 'OpenSeesLibs.pri' file. The compiler needs to know where to find the library header files as well as the locations of the libraries that are necessary for linking. For example, if the library version has changed from X.X to Y.Y, then the paths should be updated to match: usr/local/Cellar/SomeLibrary/SomeLibrary.X.X/include/ should be changed to: usr/local/Cellar/SomeLibrary/SomeLibrary.Y.Y/include/ \!/ 4) In the directory containing the code, double click on the 'OpenSees.pro' file. If compiling OpenSeesPy, open the 'OpenSeesPy.pro' file. The .pro files are project files that will automatically open the project in Qt Creator. 5) Select a build configuration, for example 'Desktop Qt 5.13.3 clang 64bit'. The project will automatically configure itself. You only have to do this once. 6) The left-hand pane should now display the project directory structure. In the left-hand pane, under the heading qmake, open the 'qmake.conf' file. Review and select additional build options, if any. Note that this is still a work in progress and not all build options are supported. 7) Click on the 'start' button in the bottom lefthand corner of Qt Creator to compile. Clicking on the 'computer' symbol above the start button allows for switching between the debug and release configurations. The release deployment results in faster program execution but it does not allow for debugging, i.e., stepping through the code. The start button with the 'bug' symbol opens the debugger. 8) Go and have a coffee, it will take a few minutes to finish compiling! *************** Building OpenSeesPy: *************** OpenSeesPy builds OpenSees as a library object that can be used within Python. Steps: Follow steps 1-4 under the heading getting started above. 5) The left-hand pane should now display the project directory structure. In the left-hand pane, under the heading qmake, open the 'qmake.conf' file. Under the heading #INTERPRETERS, uncomment the _PYTHON option by removing the '#' symbol. Everything else should be configured automatically going forward. Python automatically compiles with the reliability, parallel, and PFEM modules. 6) The last few lines at the end of the 'OpenSeesPy.pro' file contains the location of the Python framework. Update this so that it matches the location of Python on your build system. 7) Click on the 'start' button in the bottom lefthand corner of Qt Creator to start compiling. Build in release mode if using OpenSees as a plugin in a Python project. Release mode results in faster program execution. 8) Go and have a coffee, it will take a few minutes to finish compiling! 9) After successful compilation, the library will be in the 'bin' folder. The bin folder is located in the 'build' folder which is created, by default, one directory higher than the OpenSeesQt source code. The name of the build folder should look something like this: build-OpenSeesPy-Desktop_Qt_5_12_1_clang_64bit-Debug 10) OS X only OS X automatically prepends a 'lib' to the library file. Remove this 'lib' and rename the file to be 'opensees.dylib' Next, a symbolic link is required for a Python project to import the library. To create a symbolic link, cd the directory containing the OpenSees library in terminal and run the following command to create a symbolic link: ln -s opensees.dylib opensees.so There should now be a .so (shared object) library file in addition to the .dylib file. Finally, copy both the .dylib and the .so files into your Python project folder so that it can be imported into your project. Directions for using OpenSeesPy can be found at the project website: https://openseespydoc.readthedocs.io/en/latest/index.html. Note that the opensees.so library will only work on your system. As-is, the libraries that opensees.so depends on are linked with system-specific directory paths. For distribution to other systems, the opensees.so library and its dependent libraries must be bundled together into a common project folder and the linker paths converted to relative paths. In other words, the opensees.so library needs to know where to find the libraries it depends on. If it cannot, a linker error is given at runtime. *************** Supported Build Environments *************** Build Environment: OSX 10.14.4 (Mojave) Qt 5.13.3 Qt Creator 4.10.0 Compiler: OSX SDK:10.14 Apple clang version 11.0.0 (clang-1100.0.33.8) Target: x86_64-apple-darwin18.7.0 Thread model: posix 64-BIT architecture To find the version of clang on your computer, type the following in terminal: clang --version *************** Notes on OpenSees Dependencies *************** *MUMPS* MUltifrontal Massively Parallel sparse direct Solver, or MUMPS, is a sparse direct solver used for parallel solving of a system of equations Installing MUMPS via brew: brew install mumps Mumps requires the following dependencies that will automatically be installed: -Scalapack *OpenMPI* OpenMPI is a high performance message passing library (https://www.open-mpi.org/) Installing OpenMPI via brew: brew install open-mpi OpenMPI requires the following dependencies that will automatically be installed: -GCC (GNU compiler collection) -libevent (Asynchronous event library: https://libevent.org/) *UMFPACK* UMFPACK is a set of routines for solving unsymmetric sparse linear systems of the form Ax=b, using the Unsymmetric MultiFrontal method (Matrix A is not required to be symmetric). UMFPACK is part of suite-sparse library in homebrew/science Installing UMFPACK via brew: brew install suite-sparse UMFPACK requires the following dependencies that will automatically be installed: -Metis ('METIS' is a type of GraphPartitioner and numberer - An Unstructured Graph Partitioning And Sparse Matrix Ordering System', developed by G. Karypis and V. Kumar at the University of Minnesota. *SUPERLU* SUPERLU is a general purpose library for the direct solution of large, sparse, nonsymmetric systems of linear equations. The library is written in C and is callable from either C or Fortran program. It uses MPI, OpenMP and CUDA to support various forms of parallelism. Installing SUPERLU via brew: brew install superlu Should install by default with option --with-openmp enabled. Open MP is needed for parallel analysis. SUPERLU requires the following dependencies that will automatically be installed: -GCC (GNU compiler collection) -openblas (In scientific computing, OpenBLAS is an open source implementation of the BLAS API with many hand-crafted optimizations for specific processor types) *SUPERLUMT* SUPERLU but for for shared memory parallel machines. Provides Pthreads and OpenMP interfaces. Installing SUPERLUMT via brew: brew install superlu_mt SUPERLUMT requires the following dependencies that will automatically be installed: -openblas *SUPERLUDIST* SUPERLU but for for for distributed memory parallel machines. Supports manycore heterogeous node architecture: MPI is used for interprocess communication, OpenMP is used for on-node threading, CUDA is used for computing on GPUs. Installing SUPERLUDIST via brew: brew install superlu_dist SUPERLUDIST requires the following dependencies that will automatically be installed: -GCC (GNU compiler collection) -openblas (In scientific computing, OpenBLAS is an open source implementation of the BLAS API with many hand-crafted optimizations for specific processor types) -OpenMPI (a high performance message passing library (https://www.open-mpi.org/)) -Parmetis (MPI library for graph/mesh partitioning and fill-reducing orderings) *LAPACK (SCALAPACK)* The Linear Algebra PACKage, or LAPACK, is written in Fortran 90 and provides routines for solving systems of simultaneous linear equations, least-squares solutions of linear systems of equations, eigenvalue problems, and singular value problems.The associated matrix factorizations (LU, Cholesky, QR, SVD, Schur, generalized Schur) are also provided, as are related computations such as reordering of the Schur factorizations and estimating condition numbers. Dense and banded matrices are handled, but not general sparse matrices. In all areas, similar functionality is provided for real and complex matrices, in both single and double precision. LAPACK is given as a system library in OSX, you may have to update the locations of your system library in 'OpenSeesLibs.pri' *BLAS* The BLAS (Basic Linear Algebra Subprograms) are routines that provide standard building blocks for performing basic vector and matrix operations. BLAS is given as a system library in OSX, you may have to update the locations of your system library in 'OpenSeesLibs.pri' *ARPACK* ARPACK contains routines to solve large scale eigenvalue problems Installing ARPACK via brew: brew install arpack ARPACK requires the following dependencies that will automatically be installed: -GCC (GNU compiler collection) -openblas (In scientific computing, OpenBLAS is an open source implementation of the BLAS API with many hand-crafted optimizations for specific processor types) *GCC* Many of the dependencies require fortran (there is still a lot of legacy fortran code floating around in the engineering world). On OSX, I found the best solution is to use the pre-bundled fortran capabilities in GCC. In addition to its fortran capabilities, GCC is a dependency for many other libraries. Installing GCC via brew: brew install GCC *PYTHON* Python is an interpreted, high-level, general-purpose programming language. It is used in OpenSees as an interpreter in the OpenSeesPy version. In OpenSeesPy, Python version 3 is used. Installing PYTHON via brew: brew install python ***MISC. NOTES*** For the SUPERLU library. The file supermatrix.h may throw an undefined error for the type int_t. It is actually defined in the file slu_ddefs.h, however the compiler is not linking the two. Add the following line, copied from slu_ddefs.h to supermatrix.h around line 17 typedef int int_t; /* default */