Content on how to run Python

foundations/how-to-run-python.md

@@ -1,10 +1,42 @@
 # How to run Python
 
-```{note}
-This content is under construction!
-```
+This section provides an overview of different ways to run Python code, and quickstart guides for
 
-This section will give an overview of different ways to run Python code, and quickstart guides for
-
-- Installing Python on a laptop with the conda package manager
+- Choosing a Python platform
+- Installing and running Python on various local platforms
 - Running Python in the cloud
+
+## Choosing a Python Platform
+
+There is no single official platform for the Python language. Here we provide a brief rundown of 3 popular platforms:
+
+1. The terminal,
+2. Jupyter notebooks, and
+3. IDEs (integrated development environment).
+
+Here we hope to provide you with enough information to understand the differences and similarities between each platform so that you can make the best chose for your work environment and learn along effectively, regardless of your Python platform preference.
+
+In general, it is always best to test your programs in the same environment in which they will be run. The biggest factors to consider when choosing your platform are:
+
+- What are you already comfortable with?
+- What are the people around you using (peers, coworkers, instructors, etc)?
+
+### Terminal
+
+For learners who are familiar with basic [Linux commands](https://cheatography.com/davechild/cheat-sheets/linux-command-line/) and text editors, running Python in the terminal is the quickest route straight to learning Python syntax without the covering the bells and whistles of a new platform. If you are running Python on a super computer, through an HTTP request, or ssh tunneling you might want to consider learning in the terminal.
+
+[How to Run Python in the Terminal](terminal.md)
+
+### Jupyter Notebooks
+
+We highly encourage the use of Jupyter notebooks; a free, open-source, interactive tool running inside a web browser that allows you to run Python code in "cells." This means that your workflow can alternate between code, output, and even Markdown-formatted explanatory sections that create an easy to follow analysis or "computational narrative" from start to finish. Jupyter notebooks are a great option for presentations or learning tools. For these reasons Jupyter is very popular among scientists. Most lessons in this book will be taught via Jupyter notebooks.
+
+[How to Run Python in a Jupyter Session](jupyter.md)
+
+### Other IDEs
+
+If you code in other languages you might already have a favorite IDE that will work just as well in Python. [Spyder](https://www.spyder-ide.org) is a Python specific IDE that comes with the [Anaconda download](https://www.anaconda.com/products/individual). It is perhaps the most familiar IDE if you are coming from languages such as [Matlab](https://www.mathworks.com/products/matlab.html) that have a language specific platform and display a list of variables. [PyCharm](https://www.jetbrains.com/pycharm/) and [Visual Studio Code](https://code.visualstudio.com) are also popular IDEs. Many IDEs offer support for terminal execution, scripts, and Jupyter display. To learn about your specific IDE visit its official documentation.
+
+---
+
+We recommend eventually learning how to develop and run Python code in each of these platforms.

foundations/jupyter.md

@@ -0,0 +1,80 @@
+# Python in Jupyter
+
+You'd like to learn to run Python in a Jupyter session. Here we will cover:
+
+- Installing Python in Jupyter
+- Running Python code in Jupyter
+- Saving your notebook and exiting
+
+## Installing Python in Jupyter
+
+To run a Jupyter session you will need to install some necessary packages into your Conda environment.
+You can install `miniconda`. You can do that by following the [instructions for you machine](https://docs.conda.io/en/latest/miniconda.html).
+
+Then create a Conda environment with Jupyter Lab installed. In the terminal type:
+
+```
+$ conda create --name pythia_foundations_env jupyterlab
+```
+
+Test that you have installed everything correctly by first activating your environment and then launching a Jupyter Lab session:
+
+```
+$ conda activate pythia_foundations_env
+$ jupyter lab
+```
+
+Or you can install the full [Anaconda](https://www.anaconda.com/products/individual), and select **LAUNCH** under the Jupyter panel in the GUI.
+
+![Anaconda Navigaror](../images/Anaconda.png)
+
+In both methods, a new window should open automatically in your default browser. You can change the browser when launching from the terminal with (for example):
+
+```
+jupyter lab —browser=chrome
+```
+
+## Running Python in Jupyter
+
+1. With your Conda environment activated and Jupyter session launched (see above), create a directory to store our work. Let's call it `pythia-foundations`.
+
+   ![Jupyter GUI](../images/jupyter_gui.png)
+
+   You can do this in the GUI left side bar by clicking the new-folder icon. If you prefer to use the command line you can access a terminal by clicking the icon under the "Other" heading in the Launcher.
+
+2. Create a new `mysci.ipynb` file within the `pythia-foundations` folder:
+
+   Do this in the GUI on the left side bar by clicking the "+" icon.
+
+   This will open a new launcher window where you can select a Python kernel under the "Notebooks" heading for your project. _You should see "Python 3" as in the screenshot above._ Depending on the details of your system, you might see some additional buttons with different kernels.
+
+   Selecting a kernel will open a Jupyter notebook instance and add an untitled file to the left side bar navigator, which you can then rename to `mysci.ipynb`.
+
+   Select "Python 3" to use the Python version you just installed in the `pythia_foundations_env` conda environment.
+
+3. Change the first notebook cell to include the classic first command - printing, "Hello, world!".
+
+   ```python
+   print("Hello, world!")
+   ```
+
+4. Run your cell with **SHIFT ENTER** and see that the results are printed below the cell.
+
+   ![Jupyter - Hello World](../images/mysci.png)
+
+**Congratulations!** You have just set up your first Python environment and run your first Python code in a Jupyter notebook.
+
+## Saving your notebook and exiting
+
+When you are done with your work, it is time to save and exit.
+
+To save your file, you can click the disc icon in the upper left Jupyter toolbar or use keyboard shortcuts.
+
+Jupyter allows you to close the browser tab without shutting down the server. When you're done working on your notebook, _it's important to **click the "Shutdown" button** on the dashboard_ to free up memory, especially on a shared system.
+
+Then you can quit Jupyter by:
+
+- clicking the "Quit" button on the top right, or
+- typing `exit` into the terminal
+
+Alternatively you can simultaneously shutdown and exit the Jupyter session by typing `Ctrl-C` in the terminal and confirming that you do want to "shutdown this notebook server."

foundations/terminal.md

@@ -0,0 +1,66 @@
+# Python in the Terminal
+
+You'd like to learn to run Python in the terminal. Here we will cover:
+
+- Installing Python in the terminal
+- Running Python code in the terminal
+
+## Installing Python in the Terminal
+
+If running Python in the terminal, it is best to install Miniconda. You can do that by following the [instructions for you machine](https://docs.conda.io/en/latest/miniconda.html).
+
+Then create a Conda environment with Python installed by typing the following into your terminal:
+
+```
+$ conda create --name pythia_foundations_env python
+```
+
+You can test this by running `python` in the command line.
+
+## Running Python in the Terminal
+
+On Windows, open **Anaconda Prompt**. On a Mac or Linux machine, simply open **Terminal**.
+
+1. Activate your Conda environment:
+
+   ```
+   $ conda activate pythia_foundations_env
+   ```
+
+2. Create a directory to store our work. Let's call it `pythia-foundations`.
+
+   ```
+   $ mkdir pythia-foundations
+   ```
+
+3. Go into the directory:
+
+   ```
+   $ cd pythia-foundations
+   ```
+
+4. Create a new Python file:
+
+   ```
+   $ touch mysci.py
+   ```
+
+5. And now that you've set up our workspace, edit the `mysci.py` script using your favorite text editor (nano, e.g.):
+
+   ```
+   $ nano mysci.py
+   ```
+
+6. Change the script to include the classic first command - printing, "Hello, world!".
+
+   ```python
+   print("Hello, world!")
+   ```
+
+7. In the terminal, execute your script:
+
+   ```
+   $ python mysci.py
+   ```
+
+**Congratulations!** You have just set up your first Python environment and run your first Python script in the terminal.