|
PSCF v1.1
|
Installation (Up/ Prev) Source Code (Next)
PSCF is designed to be compiled and run in a unix-like environment. The package has been tested and used on systems running either linux or recent versions of the Mac OS X operating systems. Compilation is controlled by a system of unix makefiles.
PSCF is distributed only as source code, and must be compiled by the user. All source code that is designed to run on a conventional CPU is written in ANSI 2011 C++ language standard. Code that is run on an NVIDIA graphics processing unit (GPU) is written in CUDA.
The PSCF package provides several programs that are designed to run on a conventional CPU, and others that are designed to also use an NVIDIA GPU. We distinguish these in what follows by referring to CPU programs and GPU-enabled programs
In order to compile all of the CPU programs in the PSCF package, the system on which the code is compiled and run must have:
A git client is needed to obtain the source code, by cloning the git repository in which PSCF is maintained on the github.com site. A python interpreter is needed during compilation because the build system that compiles PSCF uses several python scripts that are provided within the PSCF repository. A git client, C++ compiler and python interpreter will normally come pre-installed in either the most common linux distributions or in a Mac OS operating system in which command line tools have been installed. The GNU scientific library is used by several programs within the package for linear algebra operations. The FFTW Fast Fourier transform library is used extensively by the pscf_pc programs for periodic microstructures.
In order to compile GPU-enabled programs, the user's system must also have:
The cuFFT library is provided with the CUDA development environment.
Users who wish to generate a local copy of this html documentation, as web pages that reside on their own computer, will also need to install the "doxygen" documentation utility.
In order to compile the PSCF CPU programs in Mac OS X, the computer must first be configured to provide a unix command-line development environment by installing the Command Line Tools package for XCode. In recent versions of Mac OS X, it is not necessary to install the rather large XCode integrated development environment (IDE) to obtain just the command line tools. The command line tools package is all that is needed to compile and use PSCF.
To install just the command line tools, follow the instructions given here. Briefly, the instructions are to:
This will a cause a software update window that contains the following text: "The xcode-select command requires the command line developer tools. Would you like to install the tools now?" Confirm by clicking the "Install" button on this window. When prompted, also agree to the Terms of Service. The package will then download and install.
If you choose to install the full XCode package from the Apple App store, installation of the Command Line Tools is offered as an option during the installation process.
The source code for the C++/CUDA version of PSCF described here is hosted on the github server, at github.com, as project dmorse/pscfpp. The older fortran PSCF program is maintained in a separate github repository, as project dmorse/pscf.
The source code of this current version of PSCF may be obtained by using a git version control manager to clone the public git repository. To do this, a git client must be installed on your computer.
One can check whether a git client is already installed by entering
from the unix command line. If git is installed and functional, this should return a git version number, such as "git version 2.30.1".
One can also perform a simpler check that the shell can find an exectuable named "git" by entering the command
If the git executable is found, this should return a valid path, such as /usr/bin/git . If this command does not return a valid path, you probably need to install git before proceeding.
Instructions for installing git on different platforms are given in the documentation on the git web page, and in chapter 1.5 of the Pro Git book by Scott Chacon, which is available to be read for free online. If you are using linux, and git is not already installed, you should use the preferred package manager on your linux distribution to install a git client. If you are using Mac OS X, a git client should be installed as a component of the XCode Command Line Tools package, which is needed for many other purposes.
Similarly, one can check if a python 3 interpreter is accessible by issuing the command
and confirming that the command works, and returns a version number 3.0 or greater. Alternatively, one can issue the command
and confirm that it returns a non-empty path such as /user/bin/python3. We recommend using of the command "python3" rather than "python" to make sure that you access a python 3 interpreter on any system in which python 2.* interpreter may still also are installed. A python 3 interpreter should be available from the command line in any common linux distribution (e.g., Fedora or Ubuntu), and should be available in Mac OS X after installation of the command line tools package.
By default, the PSCF build system invokes a C++ compiler using the compiler commnd name "g++". On linux systems, this command normally invokes the gnu compiler collection (GCC) C++ compiler. On a MacIntosh running Mac OS X that is set up for C++ developent (see above), the "g++" command is normally a link to the Clang compiler, which is the default compiler for C++ development on Mac OS X. The Clang compiler accepts almost all the same command line options as the gnu compiler, and so functions as a compatible replacement for the gnu C++ compiler.
It is possible to configure the build system during the initial setup process so as to instead use a different C++ compiler, as discussed here. Even when a different compiler command is used to compile source code, however, the PSCF build system will still invoke the "g++" command with appropriate options to analyse dependencies among source files. The PSCF makefile system thus always requires that the "g++" command be available on the build system.
One can check if the command "g++" exists by entering
from a terminal command line. If the "which" utility returns a valid nonempty path, such as /usr/bin/g++, then the command g++ exists and can be located by the operating system.
The name of the command used to invoke the compiler when compiling C++ files and the choices of options passed to the compiler can be changed by modifying a compiler setup file that is read during initial setup of the build system. The setup process is described in more detail here.
To compile the GPU-accelerated program, the system must also have an appropriate NVIDIA GPU and a CUDA development package installed. The NVIDIA nvcc C++/CUDA compiler is designed to integrate with the GNU g++ compiler, so we recommend using the GNU compiler to compile C++ source files if you are planning to compile CUDA code for use on the same machine.
The CPU-based programs in PSCF require access to development versions of the Gnu Scientific Library (GSL) and FFTW packages. These may be installed on Ubuntu or other Debian based linux distribution later on version 16.0 or later using the commands:
To also install the doxygen documentation generator utility, use the command
Installing doxygen is not necessary to compile PSCF, but allows you to generate a local copy of this web documentation.
On older Debian-based systems, or as a lower level alternative, one may use the "apt-get" command rather than "apt" with the same arguments.
We recommend using a package manager to install GSL and FFTW on Mac OS X. If you are not already using a package manager for managing unix programs on Max OS X, we recommend that you install the Homebrew package manager, following instructions given on the Homebrew web site. Possible alternatives include the older MacPorts or Fink package managers, or compiling the required packages directly from source files obtained from package home pages.
Using Homebrew, you may install the GSL and FFTW packages with the commands
To also install doxygen, issue the command
Mac users should be aware that homebrew installs files in different locations on newer Macs that use Apple silicon (e.g., an M1 or M2 chip) than the file locations used by homebrew on older Macs that use Intel cpus:
On Macs with Intel cpus, homebrew installed links to required header and library files in subdirectories of the /usr/local directory. Because /usr/local is one of the standard directories in which a unix shell normally looks for such files, PSCF can be installed on such machines using a default configuration for the makefile system that is the same as the default used on linux machines.
On Macs with Apple silicon, homebrew instead installs all files in /opt/homebrew. This requires users to add paths to this directory and/or some of its subdirectories to the search paths used by the compiler to find header and library files. A compiler configuration file that modifies these search paths is provided as part of PSCF, as discussed here.
At the University of Minnesota, PSCF is often run on a cluster provided by the Minnesota Supercomputer Institute (MSI). The computer clusters at MSI, like many similar multi-user facilities, use the linux "module" command to allow users to load particular software packages, including particular choices of compiler. The module command is the user interface to the "Modules" package, which is a system for automating changes in a users unix shell environment that are required in order to use particular software packages.
On a unix system that uses modules, the command
should give a listing of all software modules available for use on a particular system. The syntax for the command to load a particular module is
where module-name represents the name of a particular software module, as listed by the "module avail" command.
On the computer cluster at MSI, we currently normally set up the compilation environment by invoking
before compiling PSCF. We use a version of fftw that was compiled with GCC version 7.2.0, rather than the most recent version, because the current version of CUDA (v10.0) isn't compatible with GCC versions with primary version numbers greater than 7.
These module load commands can be either be entered manually from the command line by the user after logging in, or they can be configured to be entered automatically on login by adding them to the users .profile or .bash_profile script.
Installation (Up / Prev) Source Code (Next)
1.9.5