********************************************
Installing ChemShell on Windows (WSL/Ubuntu)
********************************************

For Windows users, the Windows Subsystem for Linux (WSL) is a 
convenient way to run scientific programs like ChemShell.

To install WSL, you can open a terminal (run as administrator)
and use the following command, ::

  wsl --install

By default, this will install Ubuntu into the WSL environment, and the
rest of these instructions assume that you are using Ubuntu as your
Linux distro (so the rest of the instructions should work for a pure
Ubuntu build too)

  .. note:: If you run into any problems with these instructions,
            you can ask for help on the
            `ChemShell user forum <https://discourse.chemshell.org/>`_

Once WSL is setup, you can try either a ``GNU`` or ``Intel`` build.
Also, the code can be compiled either as a serial code that will run
on one CPU, or as a parallel code that will run on many CPUs (using
MPI).

The following commands should all be run in the WSL shell, not in
the native Windows terminal. 


GNU Serial
==========

A GNU serial build will require the following packages to be installed
before ChemShell is built: ::

  sudo apt install build-essential
  sudo apt install cmake
  sudo apt install gfortran
  sudo apt install libblas-dev
  sudo apt install liblapack-dev
  sudo apt install python3-dev
  sudo apt install python3-numpy

Then, ChemShell can be built from the ChemShell root directory: ::

  ./setup --fc gfortran --cc gcc

GNU Parallel
============

The required packages for a GNU parallel build are similar, with a couple of
additional requirements: ::

  sudo apt install build-essential
  sudo apt install cmake
  sudo apt install gfortran
  sudo apt install libblas-dev
  sudo apt install liblapack-dev
  sudo apt install python3-dev
  sudo apt install python3-numpy
  sudo apt install libopenmpi-dev
  sudo apt install libscalapack-openmpi-dev

Then, ChemShell can be compiled with the command: ::

  ./setup --mpi --fc mpifort --cc mpicc

  
Intel Serial
============
  
.. warning:: The following instructions are for Intel OneAPI 2025.1.3. Different versions might require different
             commands and some Intel versions will not work correctly.

Firstly, an Intel build still requires a number of Ubuntu packages: ::
  
  sudo apt install build-essential
  sudo apt install cmake
  sudo apt install python3-dev
  sudo apt install python3-numpy

But unlike most dependencies, Intel compilers cannot be directly installed
using the package manager. Instead the following commands will install the
Intel compilers: ::

  wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/4a5320d1-0b48-458d-9668-fd0e4501208c/intel-oneapi-base-toolkit-2025.1.3.7_offline.sh
  sudo sh intel-oneapi-base-toolkit-2025.1.3.7_offline.sh
  wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/0ed71121-bd80-4ba7-ab54-805138bf06a7/intel-oneapi-hpc-toolkit-2025.1.3.10_offline.sh
  sudo sh intel-oneapi-hpc-toolkit-2025.1.3.10_offline.sh

.. warning:: To use the Intel compilers you must source them first (by default, ``source /opt/intel/oneapi/setvars.sh``).
             You must do this to either build or run ChemShell.

The two individual installers will run in an interactive mode. Please choose the recommended install.

Finally, ChemShell can be compiled with the following command: ::

  ./setup --fc ifx --cc icx


Intel Parallel
==============

   .. warning:: The following instructions are for Intel OneAPI 2025.1.3. Different versions might require different
                commands and some Intel versions will not work correctly.

Firstly, an Intel build still requires a number of Ubuntu packages ::
  
  sudo apt install build-essential
  sudo apt install cmake
  sudo apt install python3-dev
  sudo apt install python3-numpy

But unlike most dependencies, Intel compilers cannot be directly installed
using the package manager. Instead the following commands will install the
Intel compilers: ::

  wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/4a5320d1-0b48-458d-9668-fd0e4501208c/intel-oneapi-base-toolkit-2025.1.3.7_offline.sh
  sudo sh intel-oneapi-base-toolkit-2025.1.3.7_offline.sh
  wget https://registrationcenter-download.intel.com/akdlm/IRC_NAS/0ed71121-bd80-4ba7-ab54-805138bf06a7/intel-oneapi-hpc-toolkit-2025.1.3.10_offline.sh
  sudo sh intel-oneapi-hpc-toolkit-2025.1.3.10_offline.sh

.. warning:: To use the Intel compilers you must source them first (by default, ``source /opt/intel/oneapi/setvars.sh``).                  You must do this to either build or run ChemShell.

The two individual installers will run in an interactive mode. Please choose the recommended install.

Finally, ChemShell can be compiled with the following command: ::

  ./setup --mpi --fc mpiifx --cc mpiicx

Testing
=======

To test your build of ChemShell, issue the following commands: ::

  cd test/
  ./test

This will start the ChemShell test suite.


Building the Documentation
==========================

If you want to build the documentation locally, the following additional packages are
required ::

  sudo apt install python3-sphinx
  sudo apt install python3-numpydoc
  sudo apt install python3-sphinx-rtd-theme

Then navigate to the docs directory and issue the command ::

   make

When the documents are finished, you should find the files
``manual.html`` and ``tutorial.html`` in the directory.