Phys 521 - Classical Mechanics#

Documentation Status gitlab pipeline status gitlab coverage report

This is the main project for the WSU Physics course Phys 521: Classical Mechanics first offered in Fall 2023.

Physics has a successful track record of providing effective solutions to complex problems outside its specific domain. This course will focus on using efficient numerical techniques inspired by physics to solve challenging problems in a wide variety of applications. Techniques will be chosen from physics applications, but also applied to problems outside of the physics domain including economics, biology, sociology, etc. Students will be introduced to powerful numerical toolkits based on the SciPy and NumFocus ecosystem. Using the CoCalc platform will enable rapid development and prototyping with an explicit path to stable, tested, and performant codes capable of supporting research, or industry applications.

Documentation Status

Main project for the WSU Physics course Physics 521: Classical Mechanics I.

Installation#

This project is intended to be installed on CoCalc, but should work on other computers.

Preliminaries#

Before performing the main install, you should complete the following preliminaries, which will ensure that you can access the repository with SSH etc. These may vary by platform, but after you are done

  1. Create a CoCalc project in which to work. (We will use the class Shared CoCalc Project for this example.)

  2. (Optional) Create a GitLab account and inform your instructor of your username so that they can add you to the class private repository.

  3. On your computer, create an SSH key, authenticate to this, and optionally, add this to your keychain manager (e.g. Keychain Access.app on Mac OS X).

  4. Copy the associated public key to your GitLab account and to your CoCalc account.

  5. Add the appropriate entry to your ~/.ssh/config file so you can ssh to the CoCalc project, forwarding your keys. For example, with the class Shared CoCalc Project, I do this with the following configuration:

    # ~/.ssh/config
...
Host cc521shared
  User 31c120c9295644209d6f374a6ee32df3
Host cc*
  HostName ssh.cocalc.com
  ForwardAgent yes
  SetEnv LC_HG_USERNAME=Michael McNeil Forbes <michael.forbes+python@gmail.com>
  SetEnv LC_GIT_USERNAME=Michael McNeil Forbes
  SetEnv LC_GIT_USEREMAIL=michael.forbes+github@gmail.com
  SetEnv LC_EDITOR=vi
Host *
  IgnoreUnknown UseKeychain
  UseKeychain yes
  AddKeysToAgent yes
  AddressFamily inet
  # Force IPv4
  # https://www.electricmonk.nl/log/2014/09/24/
  #         ssh-port-forwarding-bind-cannot-assign-requested-address/

Once these are done, you should be able to ssh directly to the CoCalc project after first starting the project via the web*:

ssh smc521shared

Note: the LC_* environment variables set above allow us to customize the environment later so that multiple users can share the same environment. This deals with a quirk of CoCalc in that one connects to a project with a specialized username. This means that everyone has the same username, making it difficult for different users to commit changes to version control. To remedy this, my mmf-setup packages modifies the ~/.bash_alises file to use the variables sent above.

The remainder of the instructions should be performed after connecting to your CoCalc project in this way.

CoCalc Installation#

To install everything on CoCalc, do the following after connecting to your project with SSH as described above:

  1. Make a repositories directory and clone the project:

    mkdir repositories
cd repositories
git clone git@gitlab.com:wsu-courses/physics-521-classical-mechanics.git

  2. Run make init:

    cd ~/repositories/physics-521-classical-mechanics
git pull   # Make sure repo is up to date.
make init

    This will create a Conda environment you can activate conda activate envs/phys-521, and a Jupyter kernel called phys-521 that you can select from notebooks.

    python3 -m pip install --user --upgrade mmf-setup
mmf_setup cocalc

    The last step installs some useful files including ~/.inputrc (arrows for command completion), ~/.bash_aliases (defines some useful commands like findpy, and finda, uses the LC_* variables defined above, etc.)

    • Depending on the state of the USE_ANACONDA2020 flag, one of the following is done. If USE_ANACONDA2020 is true, then the anaconda2020 environment on CoCalc is activated, otherwise Miniconda is installed in ~/.miniconda3 and the base environment is updated with conda, anaconda-project, and mamba. This is roughly equivalent to the following (but also checking hashes, using proper paths, using /tmp, disabling prompts, etc.)

      wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh
conda update conda
conda install anaconda-project
conda install --override-channels --channel conda-forge mamba
conda clean --all

    • Once Conda is installed, [Anaconda Project] is used to setup the specific project environment:

      cd ~/repositories/physics-521-classical-mechanics
anaconda-project prepare
anaconda-project run init

      This installs all of the dependencies listed in anaconda-project.yaml into an environment in envs/phys-521, and then creates a Jupyter kernel called phys-521 that the CoCalc notebooks can find. The latter step is roughly equivalent to running the following with the appropriate python installed in envs/phys-521:

      python3 -m ipykernel install --user --name "phys-521" --display-name "Python 3 (phys-521)"

    • Finally, a line is added to the end of ~/.bash_aliases to activate the environment when you ssh to the CoCalc project. If you logout and log back in, you should now see the following prompt:

      $ ssh cc521shared
(phys-521) ~$

You should now be able to use the phys-521 kernel in notebooks.

This will run sphinx-autobuild which will launch a webserver on http://127.0.0.1:8000 and rebuild the docs whenever you save a change.

Here is the play-by-play for setting up the documentation.

cd Docs
sphinx-quickstart
wget https://brand.wsu.edu/wp-content/themes/brand/images/pages/logos/wsu-signature-vertical.svg -O _static/wsu-logo.svg 
cp -r ../envs/default/lib/python3.9/site-packages/sphinx_book_theme/_templates/* _templates

I then edited the conf.py

hg add local.bib _static/ _templates/

CoCalc Setup#

  • Purchase a license with 2 projects to allow the course and WSU Courses CoCalc project and Shared CoCalc Project to run. This approach requires the students to pay $14 for access four the term (4 months). They can optionally use any license they already have instead.

    Optionally, one might opt to purchase a license for \(n+2\) projects where \(n\) is the number of students, if there is central funding available. See Course Upgrading Students for more details.

  • Next, create a course. I do this in my WSU Courses CoCalc project.

  • Create a Shared CoCalc Project and activate the license for this project so that it can run. I then add the SSH key to may .ssh/config files so I can quickly login.

  • Clone the repos into the shared project and initialize the project. Optional, but highly recommend – use my mmf-setup project to provide some useful features

    ssh smc<project name>       # My alias in .ssh/config
python3 -m pip install mmf_setup
mmf_setup cocalc

    This provides some instructions on how to use the CoCalc configuration. The most important is to forward your user agent and set your hg and git usernames:

    ~$ mmf_setup cocalc
...
If you use version control, then to get the most of the configuration,
please make sure that you set the following variables on your personal
computer, and forward them when you ssh to the project:

    # ~/.bashrc or similar
    LC_HG_USERNAME=Your Full Name <your.email.address+hg@gmail.com>
    LC_GIT_USEREMAIL=your.email.address+git@gmail.com
    LC_GIT_USERNAME=Your Full Name

To forward these, your SSH config file (~/.ssh/config) might look like:

    # ~/.ssh/config
    Host cc_phys-521-classical-mechanics
      User c5a0bdaee17c46a1ada478c6556d9429
  
    Host cc_phys-521-classical-mechanics
      HostName ssh.cocalc.com
      ForwardAgent yes
      SendEnv LC_HG_USERNAME
      SendEnv LC_GIT_USERNAME
      SendEnv LC_GIT_USEREMAIL
      SetEnv LC_EDITOR=vi

    Logout and log back in so we have the forwarded credentials, and now clone the repos.

    git clone https://gitlab.com/wsu-courses/physics-521-classical-mechanics.git phys-521-classical-mechanics
cd phys-521-classical-mechanics
make

    The last step runs git clone git@gitlab.com:wsu-courses/physics-521-classical-mechanics_resources.git _ext/Resources which puts the resources folder in _ext/Resources.

  • Create an environment:

    ssh cc_phys-521-classical-mechanics
cd phys-521-classical-mechanics
anaconda2021
anaconda-project prepare
conda activate envs/phys-521
python -m ipykernel install --user --name "phys-521" --display-name "Python 3 (phys-521)"

    This will create a Conda environment as specified in anaconda-project.yml in envs/phys-521.

Welcome to Phys 521 - Classical Mechanics! This is the main documentation page for the course. For more class information, please see the Syllabus.

Instructors: the information presented here at the start of the course documentation is contained in the Docs/index.md file, which you should edit to provide an overview of the course.

One reasonable option might be to replace this by a literal include of the top-level README.md file with the following code:

```{include} ../README.md
```