Commit b346682e authored by Henderson, Shane's avatar Henderson, Shane
Browse files

Merge branch 'improveDocumentation' into 'master' 

Improve documentation

See merge request neams/saline!23
parents 49bba0d3 0614a5aa

README.md

+60 −22
Original line number Diff line number Diff line
@@ -30,48 +30,75 @@ The Data_Store has a convenience class `View` to insulate Data_Store access. 


>Note:: Current data integrated is incorporated via the [`Default_Data_Store`](./src/default_data_store.hh)



## Basic Usage

```



    std::string file_path = "path/to/Molten_Salt_Thermophysical_Properties.csv";

    saline::Default_Data_Store ds = saline::Default_Data_Store();

    ds.load(file_path);

    if(ds.size() <= 0)

    {

        std::runtime_error("Failed to load data");

    }

    saline::Thermophysical_Properties tp = saline::Thermophysical_Properties();

    if(!tp.initialize(&ds))

    {

        std::runtime_error("Failed to initialize Thermophysical_Properties");

    }

    if(!tp.setComposition({"LiF","NaF","KF"},{0.465,0.115,0.42}))

    {

        std::runtime_error("Failed to load required salt");

    }

    double temperature = 900 // kelvin

    // Density demonstrated check thermophysical_properties.hh for other interfaces

    std::cout << tp.rho(900) << std::endl;



    return 0;

```



# Getting Started

For individuals wanting to compile the code from source, below are the tested requirements and configurations.



## Requirements

* C/C++ compiler C++11 compliant/capable

* CMake 3.16 or newer

* CMake 3.23 or newer

* Git 2.15+ (Recommended)



## Configuration and Compilation

The Paths used below, `~/saline` and `~/build/saline`, are totally arbitrary. Feel free to chose paths that work for your workflow.

The Paths used below, `$HOME/saline` and `$HOME/saline/build`, are totally arbitrary. Feel free to chose paths that work for your workflow.



* Obtain local copy of source code

  * Via ssh (Requires [XCAMS](https://xcams.ornl.gov/xcams/) account)

  * Decide on an appropriate source location, e.g. `export saline_src=$HOME/saline`

  * Decide on an appropriate build location, e.g. `export saline_bld=${saline_src}/build`

  * Via https:

    * Clone saline `https://code.ornl.gov/neams/saline.git ${saline_src}`

  * Via ssh (Requires a user account on code.ornl.gov)

    * [Setup ssh access](https://docs.gitlab.com/ee/user/ssh.html) (if not already completed)

      * Generate ssh key

      * Save ssh key to Gitlab profile [code.ornl.gov](https://code.ornl.gov/-/profile/keys)

    * Clone saline `git clone git@code.ornl.gov:NEAMS/saline.git ~/saline`

  * Via https:

    * Clone saline `https://code.ornl.gov/neams/saline.git ~/saline`

* Change directory into saline `cd ~/saline`

* Create a build directory `mkdir -p ~/build/saline`

* Change into the build directory `cd ~/build/saline`

* Configure the build:

    * Clone saline `git clone git@code.ornl.gov:NEAMS/saline.git ${saline_src}`

* Configure and build:

  * Linux/Macos:

  ```

    cmake \

      -DBUILD_SHARED_LIBS:BOOL=ON \

      -DCMAKE_BUILD_TYPE:STRING=RELEASE \

      -Dsaline_ENABLE_TESTS:BOOL=ON \

      ~/saline

    make

      -S ${saline_src} \

      -B ${saline_bld}

    cmake --build ${saline_bld}

  ```

  * Windows

  ```

    cmake \

      -DBUILD_SHARED_LIBS:BOOL=ON \

      -DCMAKE_WINDOWS_EXPORT_ALL_SYMBOLS=BOOL=ON \

      ~\saline

    cmake --build .\ --target ALL_BUILD --config Release

      -DCMAKE_WINDOWS_EXPORT_ALL_SYMBOLS=BOOL=TRUE \

      -S ${saline_src} \

      -B ${saline_bld}

    cmake --build ${saline_bld} --target ALL_BUILD --config RELEASE

  ```

  * Additional Saline specific configuration options will be covered as they are added.

* Run tests using `ctest`

* Run tests using `ctest --test-dir ${saline_bld}`

  * A satisfactory build should yield test results like this (total number of tests may change at any time)

  ```

  100% tests passed, 0 tests failed out of 18
@@ -102,12 +129,19 @@ To enable Fortran, pass the option `-Dsaline_ENABLE_Fortran:BOOL=ON` as in: 
      -DCMAKE_BUILD_TYPE:STRING=RELEASE \

      -Dsaline_ENABLE_TESTS:BOOL=ON \

      -Dsaline_ENABLE_Fortran:BOOL=ON \

      ~/saline

      -S ${saline_src} \

      -B ${saline_bld}

```



#### Enabling Python Support



Python Wrappers are generated using [SWIG-4.0.2](https://www.swig.org/download.html).

Python Wrappers are generated using [SWIG-4.2.1](https://www.swig.org/download.html).



In principal earlier versions of SWIG may be used with a few constraints. Python versions 3.9 and later require SWIG version greater than 4.1.0.



Additionally, the python packages 'build' and 'setuptools' must be installed. This may be done via pip or conda/mamba.



For convenience, user's can utilize conda and this [environment yaml](./ci/build_env.yml) to get started. Not all packages listed therein are required simply for building.



To enable Python, pass the option `-Dsaline_ENABLE_Python:BOOL=ON` as in:

```
@@ -116,15 +150,19 @@ To enable Python, pass the option `-Dsaline_ENABLE_Python:BOOL=ON` as in: 
      -DCMAKE_BUILD_TYPE:STRING=RELEASE \

      -Dsaline_ENABLE_TESTS:BOOL=ON \

      -Dsaline_ENABLE_Python:BOOL=ON \

      ~/saline

      -S ${saline_src} \

      -B ${saline_bld}

    cmake --build ${saline_bld}

```



This should result in having a python wheel file created at `${saline_bld}/src/python/dist/SalinePy*.whl`. It should be noted that this process only is only sufficient for sharing a wheel among local users of a given machine, or optimistically a substantially similar machine. Building a wheel for general consumption is beyond the scope and questions on the process should be directed to mstdb@ornl.gov.



See [Python package](./src/python/README.md) for a simple usage pattern.



#### Additional Languages



Wrappers are added on an as needed basis. Thanks to [SWIG](https://www.swig.org) this process is relatively painless. Different languages have different requirements though, so mileage varies.



# Contributions



At this time the main development repository is protected. Users with [XCAMS](https://xcams.ornl.gov/xcams/) accounts are welcome to join this project and submit issues/branches to this repository for consideration.

Contributors with UCAMS accounts may be invited to join the development repository directly.

Users without UCAMS or [XCAMS](https://xcams.ornl.gov/xcams/) access should contact mstdb@ornl.gov for guidance on comment submission.
 
At this time the main development repository is protected. External users should direct comments, questions, and suggestions to mstdb@ornl.gov.

ci/build_env.yml

+1 −1
Original line number Diff line number Diff line
@@ -7,6 +7,6 @@ dependencies: 
  - fortran-compiler

  - python=3.8

  - build

  - swig

  - swig=4.2.1

  - setuptools

  - twine

src/python/README.md

+4 −13
Original line number Diff line number Diff line
@@ -8,26 +8,17 @@ Saline is striving to implement test driven design so the unit tests will be the 


Nevertheless a basic use is provided below. NOTE: the data file must be supplied by user.





```

import tempfile

from SalinePy import Default_Data_Store, Thermophysical_Properties



#Temporarily add necessary test data. For illustration only, the interface takes

#a path to a data file.

tst_data = b"\n\

//Pure Salts\n\

//System      , id , Mol Mass , Mol Frac             , Melt(K) , Var(%) , Reference   , Boil(K) , Var(%) , Reference      , rho_a     , rho_b     , range(K)      , Var(%) , Reference     , mu1_a     , mu2_b     , mu2_a      , mu2_b      , mu2_c     , range(K)      , Var(%) , Reference    , k_a        , k_b        , range(K)     , Var(%) , Reference   , cp_a      , cp_b       , cp_c       , cp_d      , Var(%) , Reference\n\

LiF           , 1  , 25.9390  , 1.0                  , 1121.20 , 1.00   , Douglas1954 , 1943.00 , 0.00   , Ruff1922       , 2.371E+00 , 5.000E-04 , 1123.6-1367.5 , 1.00   , Hill1967      , 1.149E-01 , 2.699E+04 , 0.000E+00  , 0.000E+00  , 0.000E+00 , 1133-1772     , 1.00   , Abe1981      , 1.882E+00  , -3.990E-04 , 1118.5-1900  , 20.00  , Gheribi2014 , 6.489E+01 , 0.000E+00  , 0.000E+00  , 0.000E+00 , 1.50   , Douglas1954\n\

NaF           , 2  , 41.9882  , 1.0                  , 1268.00 , 0.50   , Cantor1961  , 1978.00 , 0.00   , Ruff1922       , 2.755E+00 , 6.360E-04 , 1273-1373     , 0.20   , Paucirova1970 , 1.196E-01 , 2.649E+04 , 0.000E+00  , 0.000E+00  , 0.000E+00 , 1273-1373     , 1.00   , Brockner1979 , 1.259E+00  , -2.800E-04 , 1268.15-1800 , 20.00  , Gheribi2014 , 6.862E+01 , 0.000E+00  , 0.000E+00  , 0.000E+00 , 0.10   , O'Brien1957\n\

KF            , 3  , 58.0967  , 1.0                  , 1131.20 , 0.50   , Johnson1958 , 1771.00 , 0.00   , Ruff1922       , 2.646E+00 , 6.515E-04 , 1154.2-1310.2 , 1.00   , Yaffe1956     , 1.068E-01 , 2.378E+04 , 0.000E+00  , 0.000E+00  , 0.000E+00 , 1141.2-1327.6 , 2.00   , Janz1988     , 8.552E-01  , -2.540E-04 , 1129.15-1800 , 20.00  , Gheribi2014 , 7.060E+01 , 0.000E+00  , 0.000E+00  , 0.000E+00 , 18.00  , Beilmann2013\n\

LiF-NaF-KF    , 8  , 41.2909  , 0.465-0.115-0.42     , 735.00  , 2.00   , Rogers1982  , 1843.15 , 0.0    , Williams 2006b , 2.579E+00 , 6.240E-04 , 933-1163      , 1.00   , Cibulkova2006 , 0.000E+00 , 0.000E+00 , 2.130E-01  , -1.200E+03 , 1.350E+06 , 770-970       , 2.00   , Toerklep1980 , -3.500E-01 , 1.300E-03  , 773-973      , 3.50   , An2015      , 4.032E+01 , 4.388E-02  , 0.000E+00  , 0.000E+00 , 2.00   , Rogers1982\n"

## This should be the path to the mstdb-tp csv.

file_path = "my_path_to_the_data.csv" #TODO change for local conditions



# Initialize

tstDat = tempfile.NamedTemporaryFile(delete=False)

tstDat.write(tst_data)

tstDat.close()

d = Default_Data_Store()

d.load(tstDat.name)

d.load()

tp = Thermophysical_Properties()

tp.initialize(d)