About

Installation (Next)

About PSCF

PSCF is a package of software for solving the Edwards-Helfand self-consistent theory (SCFT) for polymer liquids. PSCF stands for "polymer self-consistent field". The version presented here is written primarily in C++, with some CUDA code for programs that make use of NVIDIA graphics processing units (GPUs). The source code for PSCF is maintained in the github repository https://github.com/dmorse/pscfpp.

History

The current C++ version of PSCF is intended to supersede an older Fortran program of the same name. This older Fortran version of PSCF is maintained in a separate github.com repository at https://github.com/dmorse/pscf . The current C++ version provides almost all of the capabilities of the older Fortran program, and some significant new capabilities, as discussed below.

Differences between the current C++ version of PSCF and the older Fortran program and some expected advantages of the new code include:

• The current version is written as an extensible package that contains several different programs designed for use with different geometries, boundary conditions, algorithms or hardware, implemented within a common framework.
• The current version enables simulations of mixtures containing acyclic branched block polymers, in addition to the linear block polymers and linear homopolymers allowed by the Fortran PSCF code.
• The current version uses graphics processing units (GPUs) to dramatically accelerate some programs.

Programs

PSCF contains the following executable programs and sets of programs:

• pscf_fd : The pscf_fd program is a simple finite difference program that is designed to treat one-dimensional problems in Cartesian, cylindrical or spherical coordinates. It is useful for treating problems involving flat and curved interfaces, as well as cylindrical or spherical copolymer micelles. The suffix "fd" in the name pscf_fd stands for "finite difference".
• pscf_pc : The pscf_pc programs use a pseudo-spectral algorithm to treat periodic microstructures on conventional CPU hardware. These programs are closely analogous to the older PSCF Fortran program, and provide similar capabilties and performance. Different executable files named pscf_pc1, pscf_pc2 and pscf_pc3 are used to solve 1, 2 and 3 dimensionally periodic structures, respectively. The suffix "pc" in these names stands for "periodic CPU".
  
• pscf_pg : The pscf_pg programs are GPU-accelerated programs for periodic structures. They are based on algorithms similar to those used in the pscf_pc CPU programs, and provide almost identical capabilities at higher performance. The GPU-accelerated programs for solving 1, 2 and 3 dimensionally periodic structures are named pscf_pg1, pscf_pg2 and pscf_pg3, respectively, where "pg" stands for "periodic GPU".

Features

All PSCF programs are designed to treat an incompressible mixture of one or more block polymers or homopolymer species with zero or more small molecule (point-particle) solvent species. All polymeric species are treated using the standard Gaussian model of each polymer block as a continuous random walk.

Features that are common to all of the PSCF programs include:

• Mixtures may contain any number of block polymers, homopolymers, and solvent species
• Polymers may be arbitrarily complex acyclic branched block polymers, as well as linear polymers
• Users may specify either a volume fraction or a chemical potential for each species, allowing use of canonical, grand-canonical or or mixed statistical mechanical ensembles
• Efficient simulation of sequences of states along paths in parameter space ("sweeps")
• Efficient Anderson-mixing iteration algorithms
• A variety of examples, with complete input files
• Python tools for data analysis
• Thorough user and developer documentation
• Open source code written in object oriented C++

Features specific to pscf_pc and pscf_pg programs for periodic structures include:

• Accurate pseudo-spectral solution of the modified diffusion equation
• Ordered phases with 1, 2 or 3 dimensional periodicity
• All 2D and 3D lattice systems (i.e., orthorhombic, monoclinic, etc.).
• Automatic optimization of unit parameters to minimize free energy
• Imposition of any user-selected space-group symmetry
• Built-in "database" of all 230 3D space groups and 17 2D plane groups
• Availability of a companion package Polymer Visual for visualization of periodic fields and structures.

Features specific to the pscf_pc CPU programs for periodic structures are:

• Inhomogeneous density constraints (a "mask")
• External fields
• Thin polymer films

The mask and external field features are used in the pscf_pc programs to implement simulations of thin films. A mask is used to constrain a polymer material to a slit within a periodic supercell, and external fields are used represent selective interactions of different monomer types with the top and bottom surfaces.

Cloning the Source Code

The PSCF C++ package is currently only provided in source code form. The source code may be obtained by using a git version control system client to clone the github source code repository. To do so on a machine with a git client installed, enter the command:

git clone --recursive https://github.com/dmorse/pscfpp.git

Note the use of the –recursive option to the git clone command. This is necessary to clone two git submodules that are maintained in separate github repositories. This command will create a new directory called pscfpp/ that contains all of the source code and associated documentation, including all required git submodules.

We do not recommend that users obtain the source code by instead downloading a zip or tar file from the PSCF github repository. A repository that is created by unpacking such a file will not contain source code for the other git repositories that are automatically downloaded and installed as submodules by use of the git clone command with the "recursive" option.

Documentation

Documentation is provided as an html web manual that contains both user and developer documentation. An online copy of the documentation of a recent major release is available online at

https://dmorse.github.io/pscfpp-man .

The PSCF source code repository contains all of the files from which the web manual is generated. This makes it possible for users to generate a local copy of the manual on their own computer. The web manual is created using the doxygen documentation utility. In order to generate a local copy of the documentation, doxygen must be installed on your computer, and the directory containing the doxygen executable must be in your unix command search PATH.

To generate documentation, change directory (cd) to the pscfpp/ root directory and then enter

> make html

This should create many html files in the docs/html directory of the pscfpp/ root directory. To begin reading the documentation, point a browser at the file docs/html/index.html, which contains the main page of this web manual.

Formatting of some mathematical expressions within this web manual relies on the use of a MathJax interpreter that is provided by a remote server, and which thus requires an internet connection to function. Mathematical expressions in local copies of this manual may thus not be formatted correctly if the computer is not connected to the internet.

Dependencies

The PSCF source code is written using C++ as the primary language, with CUDA used in some programs for GPU kernels. The C++ version of PSCF was developed on linux and and Mac OS X operating systems using standard unix utilities, and is designed to be compiled and run in these or other unix-like environments.

The CPU-based programs within the PSCF package depend on the following external libraries:

• GSL - GNU Scientific Library
• FFTW - Fast Fourier Transform library

The one-dimensional finite difference program pscf_fd requires only GSL, and not FFTW. The pscf_pc CPU-based programs for spatially periodic structures require both GSL and FFTW.

The GPU-accelerated pscf_pg programs can only run on a computer with an appropriate NVIDIA GPU. To compile or run these programs, the system must also have an NVIDIA CUDA development environment that provides the cuFFT gpu-accelerated fast Fourier transform library.

Complete directions for compiling and installing PSCF are provided in section 2 of this manual. These include instructions for installing the dependencies listed above in several operating system environments using several common package managers.

License

The C++/CUDA version of PSCF is free, open source software. It is distributed under the terms of the GNU General Public License as (GPL) published by the Free Software Foundation, either version 3 of the License or (at your option) any later version. PSCF is distributed without any warranty, without even the implied warranty of merchantability or fitness for a particular purpose. See the LICENSE file or the gnu web page for details.

Support

Development of PSCF is supported by the National Science Foundation program for Cyberinfrastructure for Sustained Scientific Development (CSSI) under Grant No. 2103627.

Contributors

• David Morse
• Guo Kang Cheong
• Anshul Chawla
• Ryan Collanton
• Ben Magruder
• Kexin Chen
• Ying Zheng

Main Page (Up)         Installation (Next)