Skip to content

Getting Started

Jump to bottom
Stanley A. Baronett edited this page Jul 3, 2024 · 3 revisions

Beginners should start here and follow the topics below in order, skipping familiar or completed steps as needed.

GitHub

  1. Create a GitHub account if you haven't already.
  2. Once logged in, you can fork this repository, or "repo", by clicking the Fork button in the header (usually upper-right) of this repo. Your fork is where you can make and upload changes that you can later propose to our main repo by making a pull request. For more information, see GitHub Docs on Contributing to projects.
  3. For those new to the Git version-control system, we recommend using GitHub Desktop (macOS and Windows only) to clone your forked repo to your local PC. For more information, see Installing and configuring GitHub Desktop, our Cloning subsection below, and GitHub Docs on Cloning a repository.
  4. Learn the GitHub flow to see how and why GitHub is used to develop code and online OpenCourseWare.
  5. For additional introductory topics, see

Cloning

When you clone using Git (e.g., this repo, or your own fork), you create a local, asynchronous copy of a GitHub repo on your PC that you can modify (e.g., add, edit, or remove files). These local modifications can then be staged as individual commits, and later pushed (i.e., uploaded and/or written) to the remote ("upstream") source from which the clone was made, provided you have the necessary write permissions (this is always the case for your own forks and repos). As recommended in Step 3 above, GitHub Desktop provides an easy-to-use, graphical interface for the vast majority of common Git commands and tasks, including cloning (git clone); see Cloning and forking repositories from GitHub Desktop for more information. Alternatively, if you have git installed, you can clone your fork of this repo to your current local directory (see pwd) via the command line interface (CLI) or terminal using,

git clone https://github.com/$USER/pfitsplus.github.io.git

where $USER is your GitHub username.

Syncing your branch

Whenever new commits (e.g., scripts or other content) are added to this repo (i.e., the upstream/main relative to your fork), you can re-sync your fork using GitHub Desktop as follows:

  1. Below the top menu bar, click the Fetch origin button; this will check for any recent changes made to this upstream repo.
  2. From the top menu bar, click Branch>Merge into current branch... (Ctrl+Shift+M)
  3. Under the section Other branches, select "upstream/master" and click the button at the bottom "Merge upstream/main into master".
  4. For more information, or if you run into any issues (e.g., there are "merge conflicts"), see Merging another branch into your project branch.

Pull Requests (PRs)

Reviewing

Miniconda

We recommend using Miniconda (a lightweight version of Anaconda) to manage your Python environments and to install JupyterLab. Anaconda is one of the most widely used package-management solutions for Python with 1,500+ popular packages out of the box, including the most common ones used in the computational sciences. Below are instructions and external resources for setting up Miniconda depending on your operating system.

Windows

The first step is to get Linux running inside your Windows machine using the Windows Subsystem for Linux (WSL). Follow the first three (3) sections of the Get started with the Windows Subsystem for Linux guide (i.e., "Introduction" through "Integration between Windows and Linux file systems"). We recommend installing Ubuntu as your Linux distribution, for easibility and widespread support.

With WSL installed and access to the terminal, install Miniconda as follows:

  1. Open your WSL terminal (e.g., Ubuntu) and enter the following download command (copy with Ctrl+V but paste by right-clicking, then press the Enter or Return key):
wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
  1. To install, run:
bash Miniconda3-latest-Linux-x86_64.sh
  1. Follow the prompts on the installer screens; if you are unsure about any setting, accept the default (you can change them later).
  2. When the installer finishes, close then re-open your terminal window for the changes to take effect.
  3. Test your installation: in the terminal, run the command conda list. If installed correctly, a list of installed packages appears

Source: Installing on Linux — conda documentation.

macOS

See Installing on macOS.

Linux

See Installing on Linux.

JupyterLab

If you do not already have Jupyter Notebook or JupyterLab installed, we recommend setting up Miniconda first (see above). Below are resources and instructions for setting up JupyterLab on your local PC as well as usage guides and tutorials.

Setup

  1. Open your terminal.
  2. Install JupyterLab with:
conda install -c conda-forge jupyterlab
  1. Start JupyterLab.

Tutorials

Python

Once everything's set up and working, you can open a new Jupyter notebook file (e.g., Untitled.ipynb) to begin writing and executing Python code. Python is a mature, interpreted high-level general-purpose programming language and consistently ranks as one of the most popular and easy to learn. With hundreds of thousands of packages available at the Python Package Index (PyPI) alone, there's no shortage of free learning resources available on the web, but we list a few:

Additional resources

Clone this wiki locally