Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Separate build install readme #105

Merged
merged 11 commits into from
Aug 9, 2021
Merged

Separate build install readme #105

Show file tree
Hide file tree
Changes from 9 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
2bd4745
split up readmes
shimwell Jul 22, 2021
8aab8e4
changed intro
shimwell Jul 22, 2021
3e4eb75
typos fixed
shimwell Jul 22, 2021
30e8006
review suggestions
shimwell Jul 22, 2021
b4e961f
typo fix from review
shimwell Jul 22, 2021
5efd6f9
Merge branch 'separate_build_install_readme' of github.com:svalinn/Cu…
shimwell Jul 22, 2021
311ef92
relative url instead of absolute
shimwell Jul 23, 2021
5eded8a
made readme match build scripts
shimwell Jul 23, 2021
711607a
corrected readme file link
shimwell Jul 23, 2021
8802519
review fix from bam and gonuke
shimwell Jul 26, 2021
50f501e
correct testing text to use help dagmc
shimwell Jul 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
285 changes: 48 additions & 237 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,235 +1,56 @@
Svalinn plugins and command extensions for Cubit
=================================================

**Beta:** This software is currently under early development. It has been
demonstrated to work on a wide range of problems, but the build system is not
finalized.

The plugin has been tested and is confirmed to work with various Cubit versions 17.1 up to 2020.2.

Prerequisites
=============

In order to build the plugin, you must have access to Cubit and the Cubit SDK.
Additionally, the following system packages must be present on
your computer:

* EIGEN3
* HDF5

On Ubuntu, these packages can be obtained by running

```
sudo apt install libeigen3-dev libhdf5-dev
```

The following packages are not available from the package manager and must be
built yourself:

* MOAB 5.1.0
* DAGMC
The plugin has been tested and is confirmed to work with versions of Coreform
Cubit up to 2021.5 and versions of Cubit up to 15.8.

Install Cubit
==============

Cubit can be installed by obtaining the Cubit `.deb` package and installing it
with the package manager; i.e.

```
sudo dpkg -i Cubit_DEB.deb
```

This installs Cubit to `/opt/Coreform-Cubit-VERSION` or `/opt/Trelis-VERSION` for older versions.

For Cubit versions older than 2021, one needs to manually install the provided SDK

### Note
There is also a bug (or some other unknown issue) in come Cubit SDK which requires a
file in the Cubit SDK to be modified. The following commands show how to make
this change. (This issue is not present in Cubit 17, so these commands do not
need to be run for Cubit 17.)

```
cd PATH_TO_CUBIT/bin
sudo cp -pv CubitExport.cmake CubitExport.cmake.orig
sudo sed -i "s/\"cubit_util\" \"showviz_base\"/\"cubit_util\"/" CubitExport.cmake
```

Notes on Build Instructions
===========================

A non-source directory build is recommended. These build instructions assume
that the plugin build will take place in the `${HOME}/plugin-build` directory,
and they assume that the Cubit-plugin repo has been cloned into
`${HOME}/plugin-build/Cubit-plugin`.

**Before building anything, ensure that the `LD_LIBRARY_PATH` environment
variable is empty**.

```bash
unset LD_LIBRARY_PATH
plugin, and if it is not empty it can only cause problems. Ensure that it
remains empty when running Cubit as well.
```

Build MOAB
==========

MOAB must be built with HDF5 enabled. On Ubuntu 18.04, HDF5 is located in the
`/usr/lib/x86_64-linux-gnu/hdf5/serial` directory, but it may be located
somewhere else on other flavors or versions of Linux. MOAB should be built with
the Eigen matrix algebra library instead of LAPACK. The
`_GLIBCXX_USE_CXX11_ABI=0` flag is required for compatibility with Cubit.

The following commands show how to correctly build the MOAB dependency. If HDF5
is located somewhere other than `/usr/lib/x86_64-linux-gnu/hdf5/serial`, then
replace the directory with the correct one.

```
cd ${HOME}/plugin-build
mkdir -pv moab/bld
cd moab
git clone https://bitbucket.org/fathomteam/moab -b Version5.1.0
cd moab
autoreconf -fi
cd ../bld
../moab/configure CXXFLAGS=-D_GLIBCXX_USE_CXX11_ABI=0 \
--enable-shared \
--enable-optimize \
--disable-debug \
--disable-blaslapack \
--with-eigen3=/usr/include/eigen3 \
--with-hdf5=/usr/lib/x86_64-linux-gnu/hdf5/serial \
--prefix=${HOME}/plugin-build/moab
make -j`grep -c processor /proc/cpuinfo`
make install
```

Build DAGMC
===========
Cubit or Corefoam Cubit can be installed by following the instructions on the
relevant website. Cubit is available for Sandia and US National labs users
while Coreform Cubit is available via comerical licenses or freeley available
for students and hobbyists as Cubit Learn.

The following commands show how to build the DAGMC dependency. The `uwuw` and
`make_watertight` features should be turned on, while other features should be
turned off. The `MOAB_DIR` variable should point to the location of the
previously-built MOAB library. The `_GLIBCXX_USE_CXX11_ABI=0` flag is once again
required.
- [Download Cubit](https://cubit.sandia.gov/downloads.html) from Sandia
- [Download Corefoam Cubit](https://coreform.com/products/downloads/) from Corefoam

The following commands show how to correctly build the DAGMC dependency.
<details>
<summary><b>Expand</b> - Ubuntu terminal commands for Corefoam Cubit</summary>
<pre><code class="language-html">
sudo apt update
sudo apt-get install wget
wget -O coreform-cubit-2021.5.deb https://f002.backblazeb2.com/file/cubit-downloads/Coreform-Cubit/Releases/Linux/Coreform-Cubit-2021.5%2B15962_5043ef39-Lin64.deb
sudo dpkg -i coreform-cubit-2021.5.deb
</code></pre>
</details>

```
cd ${HOME}/plugin-build
mkdir -pv DAGMC/bld
cd DAGMC
git clone https://github.com/svalinn/DAGMC -b develop
cd bld
cmake ../DAGMC -DCMAKE_CXX_FLAGS=-D_GLIBCXX_USE_CXX11_ABI=0 \
-DMOAB_DIR=${HOME}/plugin-build/moab \
-DBUILD_UWUW=ON \
-DBUILD_TALLY=OFF \
-DBUILD_BUILD_OBB=OFF \
-DBUILD_MAKE_WATERTIGHT=ON \
-DBUILD_SHARED_LIBS=ON \
-DBUILD_STATIC_LIBS=OFF \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=${HOME}/plugin-build/DAGMC
make -j`grep -c processor /proc/cpuinfo`
make install
```

Build the Plugin
================

The following commands show how to build the plugin itself. The `CUBIT_ROOT`
variable should point to the location of Cubit. The `DAGMC_DIR` variable should
point to the location of the previously-built DAGMC library.

```
cd ${HOME}/plugin-build
mkdir -pv bld
cd bld
cmake ../Cubit-plugin -DCUBIT_ROOT=PATH_TO_CUBIT \
-DDAGMC_DIR=${HOME}/plugin-build/DAGMC \
-DCMAKE_BUILD_TYPE=Release \
-DCMAKE_INSTALL_PREFIX=${HOME}/plugin-build
make -j`grep -c processor /proc/cpuinfo`
make install
```

### Submodules

The plugin depends on another external repository called mcnp2cad. mcnp2cad is
available in this repo as a git submodule. It is pulled by default during the
`cmake` configuration step above.

If a custom version of mcnp2cad is needed, this behavior pulling can be disabled
by adding `-DUPDATE_SUBMODULES=OFF` to the `cmake` configuration. mcnp2cad can
then be manually updated with the following commands:

```
cd ${HOME}/plugin-build/Cubit-plugin
git submodule update --init
```

Create the Tarball
==================

The following commands show how to create the tarall for the plugin. Once again,
the location of HDF5 might be different than what is presented here depending on
what flavor or version of Linux is being used.

```
# Set up the directory which will contain the libraries
cd ${HOME}/plugin-build
mkdir -p pack/bin/plugins/svalinn
cd pack/bin/plugins/svalinn

# Copy all needed libraries into current directory
cp -pPv /usr/lib/x86_64-linux-gnu/libhdf5_serial.so.100* .
cp -pPv ${HOME}/plugin-build/moab/lib/libMOAB.so* .
cp -pPv ${HOME}/plugin-build/DAGMC/lib/libdagmc.so* .
cp -pPv ${HOME}/plugin-build/DAGMC/lib/libmakeWatertight.so* .
cp -pPv ${HOME}/plugin-build/DAGMC/lib/libpyne_dagmc.so* .
cp -pPv ${HOME}/plugin-build/DAGMC/lib/libuwuw.so* .
cp -pPv ${HOME}/plugin-build/lib/* .
chmod 644 *

# The resulting shared library objects require an update to their RPATH (runtime path)
# attribute to ensure that the correct set of libraries is discovered when starting
# Cubit and loading the plugin library.
patchelf --set-rpath PATH_TO_CUBIT/bin/plugins/svalinn libMOAB.so
patchelf --set-rpath PATH_TO_CUBIT/bin/plugins/svalinn libdagmc.so
patchelf --set-rpath PATH_TO_CUBIT/bin/plugins/svalinn libmakeWatertight.so
patchelf --set-rpath PATH_TO_CUBIT/bin/plugins/svalinn libpyne_dagmc.so
patchelf --set-rpath PATH_TO_CUBIT/bin/plugins/svalinn libuwuw.so

# Create the Svalinn plugin tarball
cd ..
ln -sv svalinn/libsvalinn_plugin.so .
cd ../..
tar --sort=name -czvf svalinn-plugin-17.1.tgz bin
mv -v svalinn-plugin-17.1.tgz ..
cd ..
rm -rf pack
```
Install Plugin
==============

The Svalinn plugin tarball should now be located at
`${HOME}/plugin-build/svalinn-plugin-17.1.tgz`.
The Plugin can be downloaded from the [Release](https://github.com/svalinn/Cubit-plugin/releases)
section of this repository. Operating system specific assets are created with
each release and can be download for various Operating systems (Ubuntu 18, 20
and MacOS 10.15).

Install the Plugin
==================
After downloading the compressed tgz file the contents should be uncompress to
your Cubit folder.
<details>
<summary><b>Expand</b> - Terminal commands for Ubuntu 20.04</summary>
<pre><code class="language-html">
wget https://github.com/svalinn/Cubit-plugin/releases/download/0.1.0/svalinn-plugin_ubuntu-20.04_cubit_2021.5.tgz
sudo tar -xzvf svalinn-plugin_ubuntu-20.04_cubit_2021.5.tgz -C /opt/Coreform-Cubit-2021.5
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is only valid for Ubuntu, I think.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep I think so also, it mentions Ubuntu usage in the Expansion tab.

I did this via an expand tabs as I think we could have expand tabs for every OS once they are all working.

</code></pre>
</details>

To install the plugin, simply run

```
cd PATH_TO_CUBIT
sudo tar -xzvf ${HOME}/plugin-build/svalinn-plugin.tgz
```

Test the Plugin
===============

Run `coreform_cubit`. If the plugin was installed correctly, after the Cubit GUI
finishes loading, the following output should appear in the Cubit command line:
Run ```coreform_cubit``` from the command line. If the plugin was installed
correctly, after the Cubit GUI finishes loading, the following output should
appear in the Cubit command line:

```
Loaded Svalinn plugin.
Expand All @@ -243,32 +64,22 @@ Cubit>

If this output does not appear, then the plugin was not installed correctly.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is not true on MacOS with Cubit 2021.5

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

here is my command input:

Finished Command: undo on

Cubit>help dagmc

Help for words: dagmc.

export dagmc <filename> [faceting_tolerance <faceting tolerance>] [length_tolerance <length tolerance>]
     [normal_tolerance <normal tolerance>] [make_watertight] [verbose]
     [fatal_on_curves]


Help for words: dagmc.

export dagmc <filename> [faceting_tolerance <faceting tolerance>] [length_tolerance <length tolerance>]
     [normal_tolerance <normal tolerance>] [make_watertight] [verbose]
     [fatal_on_curves]

Cubit>

not Loaded Svalinn plugin input but help dagmc worked just fine

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ok I can perhaps change it to something like ...

Run coreform_cubit from the command line. After the Cubit GUI finishes loading, run the following command in the Cubit command line:

help dagmc

If the plugin was installed correctly you should see the following text appear.

Help for words: dagmc.

export dagmc <filename> [faceting_tolerance <faceting tolerance>] [length_tolerance <length tolerance>]
     [normal_tolerance <normal tolerance>] [make_watertight] [verbose]
     [fatal_on_curves]

If this output does not appear, then the plugin was not installed correctly.


To view the available command line options for the MCNP importer, type
`help mcnp` in the Cubit command line. Similarly for the DAGMC exporter, type
`help dagmc` in the Cubit command line.

Some sample files have been included in the `test_plugin` directory of this
repository. Navigate to that directory, then run `coreform_cubit`. In the Cubit command
line, type `import mcnp test.i`. This should result in the MCNP geometry and
material mapping contained within the MCNP input file `test.i` being imported
into Cubit.
Usage within Cubit
==================

The DAGMC plugin commands should now be accessable via the Cubit command line.

To view the available command line options for the MCNP importer, type
```help mcnp``` in the Cubit command line.

Next, run `export acis test.sat overwrite attributes_on`. This will save the
geometry in ACIS format to `test.sat`.
Similarly for the DAGMC exporter, type ```help dagmc``` in the Cubit command line.

Lastly, run
`export dagmc "test.h5m" faceting_tolerance 1e-3 make_watertight verbose`. This
will facet the geometry and save it in a format that can be used by DAGMC.
Some sample files have been included in the [test_plugin](test_plugin)
directory of this repository for testing the command line usage.

Test the Plugin (Command Line Mode)
===================================

The plugin can also be run in command line mode, without needing to load the
Cubit GUI. The file `test.jou` in the `test_plugin` directory contains the five
commands mentioned in the previous section of this readme. To execute these
commands in command line mode, run
`coreform_cubit -batch -nographics -nojournal test.jou` from the regular command line.
Building the plugin
===================

It is through this command line interface that one would replicate the workflows
of years past which involved the now-defunct `mcnp2cad` and `dagmc_preproc`
executables.
Building the plugin from source is also [possible](README_dev.md) but only recommended for developers.
Loading