Phys 521 - Classical Mechanics

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 will generate an environment you can use to work with the project. Once this is done you can make the documentation, tests, etc. with commands like:

Preliminaries#

The latter will host the documentation on https://localhost:8000 and auto-update when you make changes. If you want to manually interact with the environment, then you can run:

make shell

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.

CoCalc#

To build the documentation on CoCalc, open the following file:

This will build the documentation, and serve it on https://cocalc.com/c5a0bdae-e17c-46a1-ada4-78c6556d9429/raw/.repositories/phys-521-classical-mechanics/Docs/_build/html/index.html.

Developer Notes#

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:

See Docs/index.md for more details.

To use this repository:

  1. (Optional)

  2. Clone this repo and initialize it:

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

  3. 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.

Funding#

https://nsf.widen.net/content/txvhzmsofh/png/

Some of the material presented here is based upon work supported by the National Science Foundation under Grant Number 2012190. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

Phys 521 - Classical Mechanics#

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

This website, hosted on Read The Docs, will be used to collect and display additional information about the course, including:

and various class notes. These should also be available through the navigation menu (which might hidden if your display is not sufficiently wide).

These documents are built using JupyterBook (see JupyterBook Demonstration) and include all of the source code needed to generate the figure, plots etc. For example, to see how a figure was made, look in the preceding code cell. The complete source code for this documentation is available at wsu-courses/physics-521-classical-mechanics.

Funding Statement#

https://nsf.widen.net/content/txvhzmsofh/png/

Some of the material presented here is based upon work supported by the National Science Foundation under Grant Number 2012190. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.

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
```