Source Code

Dependencies (Prev)         Installation Overview (Next)

The source code for the C++/CUDA version of PSCF is hosted on github.com, as project dmorse/pscfpp. The source code may be obtained by using a git version control manager to clone the public git repository. The following instructions assume that a "git" client has been installed on your computer. The instructions given below should allow you to clone the source code whether or not you have any experience with git or github. If you are unfamiliar with git or need to look up some details, we heartily recommend the online Pro Git book as a tutorial and reference.

Cloning the repository

To obtain a working copy of the pscfpp git repository, you should first change directory (cd) to the directory you would like to contain a newly created pscfpp directory. From there, enter the command

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

This should create a complete copy of the PSCF source code in a new subdirectory named "pscfpp/" of the working directory from which you invoked this command. See the discussion of the reason for use of the "--recursive" option below.

The above instructions are intended for users who simply want to get a copy of PSCF their own use, but who are not (or not yet) interested in contributing to its development. Users that want to be able to contribute to the project or share their extensions or improvements of PSCF with others should go through a slightly more complicated procedure. Such user/developers should instead:

• Create a user account on github.com, if they do not already have one.
• Create a fork (i.e., a personal version) of the pscfpp repository in their github user account
• Clone their personal fork of the pscfpp repository to a computer on which they can compile and edit the code, using the "--recursive" option as described above.

The URL for dmorse/pscfpp used in the command to clone user's github fork to a local computer may use a prefix that selects either the https (prefix https://github.com/) or ssh (prefix git@g.nosp@m.ithu.nosp@m.b.com: ) communication protocol. Cloning with either of these protocols creates a connection with the github server that will allow the user write access to their personal fork of pscfpp on github. The https protocol was used in the above instructions for general users who clone the main pscfpp directory directly, in which the repository URL starts with "https://github.com/..." The command to use ssh to clone a fork of pscfpp created by a user with a github username JaneDoe would generally look like

git clone --recursive git@github.com:JaneDoe/pscfpp.git

The https protocol does not require any initial set up, but requires password authentication every time a user pushes locally committed changes to github. The ssh protocol instead uses public-key authentication, which requires the user to add a public key to their github account that identifies their local computer. This takes a few minutes to set up, but thereafter avoids the need to use password authentication for every push command. See the github documentation on authentication for further details about how to set up public keys for use with ssh, among other issues related to github account security.

Herefafter, we assume that the root directory of the pscfpp working copy is named pscfpp/. References to paths that do not start explicitly with a prefix "pscfpp/" should be understood to be relative paths, relative to this directory. The directory structure of the pscfpp repository is explained here.

Use of git submodules

Some subdirectories of the pscfpp/src directory are maintained in separate github repositories and are imported into the pscfpp repository as git "submodules". (See chapter 7.11 of the Pro Git online book). Specifically, the src/util and src/tests directories are submodules that contain clones of the dmorse/util and dmorse/test repositories on github, respectively.

The use of the "--recursive" option of the git clone command given above should automatically create clones of these submodules in the appropriate locations within the pscfpp source directory tree, thus creating a complete functional copy of the source code. Cloning a copy of pscfpp without using the "--recursive" option, however, would create a version of the pscfpp directory tree in which the src/util and src/tests directories are empty. If you find yourself with a repository clone in which one or both of these repositories is empty, you can either clone pscfpp again with the recursive option, or initialize and update the submodules by calling

git submodule update --init

Also note that git does not update submodules automatically when you switch to a different version or branch of the main software. Because of this, you may need to manually update the submodules if you switch to a different version of PSCF, since different versions of this software are associated with different versions of the submodules. An error will likely occur during compilation of the software if any submodule is not properly updated.

You can check if you have the correct version of the submodules by running "git status" from your pscfpp directory. If, for example, your util submodule is the wrong version, you will see the following output:

# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#  modified:   src/util (new commits)

This indicates that your submodule is different ("modified") from the version that is associated with your current version of PSCF. To update the submodule to the appropriate version, run

git submodule update

Dependencies (Prev)         Installation (Up)         Installation Overview (Next)