Skip to content

Home

Jump to bottom Edit New page
Jack Sankey edited this page Mar 21, 2025 · 92 revisions

Welcome to the spinmob wiki!

Spinmob is designed as a high-level, easy-to-navigate library for acquiring, saving, loading, visualizing, and analyzing data. For example, the following nonlinear fit:

Example fit

is produced with the following commands:

# Import the library
import spinmob

# Create a fitter object
f = spinmob.data.fitter()

# Set the functions
f.set_functions('a*x*cos(b*x)+c', 'a=-0.2, b, c=3')

# Supply the data
f.set_data([1, 2, 3, 4, 5], [1.7, 2, 3, 4, 3], 0.115, xlabel='Time (s)', ylabel='Pants (mV)')

# Fit!
f.fit()

Check out the "chapters" on the right-hand side of this page to get a feel for what it can do (and learn a bit about python itself if you're new). By far the most popular features for new users are the fitting object (Chapter 4), the databox object (Chapter 2), and the GUI builder (Chapter 6). There are also a bunch of plotting shortcuts (Chapter 3) and a mess of random / potentially useful functions in spinmob.fun. All the code's documentation is readily accessible inside Spyder or your favorite IDE.

Recommended method for installing everything

Below is the standard installation method that works most reliably. Note many people already have a conda python installation and either do not want to mess with it or cannot make the following installation work due to library conflicts; in these cases, we recommend creating a new conda environment as discussed below.

1. Install Miniconda or the full Anaconda Python.

Anaconda Python comes with a lot of packages. Miniconda comes with the bare bones, allowing you select only those packages you want.

2. Install Spinmob

The easiest way to install Spinmob is via pip, but we need to install pip first (note this may be installed already on newer Miniconda / Anaconda distributions). It's also good to install spyder via conda at the same time since they do a better job packaging that (and this will set up a few other things automatically that are helpful!). From your Anaconda prompt (or system terminal), run:

conda install pip spyder

Then install Spinmob with pip:

pip install spinmob

Note you can leave spyder out, but if you do, you will then need to make sure you have some version of PyQt installed as well, e.g., by running pip install pyqt5.

3. Import spinmob and play

If you're new to python, check the Python Bootcamp section. Once you have a python console (ideally IPython, e.g., in Spyder), import spinmob with

import spinmob as s

The module is designed so that there are fewer high-level objects organized in a hierarchy, to facilitate learning by exploration on the command line and integrated help functionality. After importing, type s. and press the tab key to see what options are available. To access data-related functionality, type s.data. and see what options appear. For plotting, s.plot., and so on.

Like all python, Spinmob's documentation is built in. Much of this is visible via code-completion or Spyder's Help window, which can be accessed by typing <ctrl>-i with your cursor positioned after the last character of an object. Or, you can use python's help() command, e.g. help(s.plot.xy.data).

When I have just finished a new install, my first test is always this command:

In []: s.plot.magphase.function()

This should pop up a magnitude and phase plot for the supplied (default) complex function 1/(1+1j*x). If it popped up, spinmob & all its dependencies are correctly installed.

Creating and Activating a New Environment

If you wish to create a completely "clean" conda environment, you can do so with the following commands. Once a new environment is activated, you can then install packages as discussed above.

  1. To create a clean environment named pants, use the command below (following the resulting instructions):

    conda create --name pants

  2. To activate the environment:

    conda activate pants

  3. To see which environments exist and which is activated (has a * next to it):

    conda env list

Non-conda installation (under construction)

1. Install Python

Windows: Download the Python 3 installer and run it. During the install, make sure to check the boxes for installing the package manager "pip", and for adding python to environment variables so you have easy access to everything from the command prompt. I also like to choose a path that is easier to remember, e.g., a "Python3" folder in your user directory, so it's out of the way but easy to find. You may want to find this often.

Linux: Linux usually comes with at least one Python3 environment installed. You can see which version you have with the command python3 --version. If you want to use a different version, you'll have to read about how to do this for your specific Linux distribution. You will also want to make sure the Python packages venv and pip are installed, so you can create virtual environments and install python packages. In Debian/Ubuntu variants, e.g., this is achieved with sudo apt-get install python3-venv python3-pip.

At this point, it is a very good idea to create a new virtual environment, so that anything you do beyond this point will not affect the default Python installation. To create a virtual environment, open a command prompt and type something like

python -m venv my_new_environment

where my_new_environment can be replaced with whatever you like, e.g., Python3_Spinmob. This will create a directory of the same name. To interact with this environment on the command prompt, you need to then "activate" it:

  • Windows: From the command prompt, run the activate script with my_new_environment\Scripts\activate (appropriately editing the path). If you get a security error about running scripts being disabled, you may have to first unlock this with the command Set-ExecutionPolicy Unrestricted -Scope Process.

  • Linux: From the terminal, use the command source my_new_environment/bin/activate (appropriately editing the path). If you always want to use this Python environment in the terminal, you can add a similar command to your .bashrc script (or equivalent for non-Ubuntu-like distributions).

If it works, you will see the name of your activated environment in parenthesis before your prompt. Sometimes an old version of pip is installed, and this can cause problems. It's a good idea to run python -m pip install --upgrade pip to make sure it's at the latest version. It is also a good idea to make sure the Python package wheel is installed with pip install wheel.

2. Install spinmob

You can then install packages with pip. To get spinmob running, use

pip install spinmob

This will download and install spinmob and all its dependencies except the finicky "PyQt", which is responsible for creating graphical interfaces. We intentionally left this choice up to you, because you cannot have more than one installed at a time, and many people have their own preferred version. If you do not have a PyQt variant installed, you can install one as follows:

pip install PyQt5

Configuring VSCode (under construction)

I have found VSCode to be the best development environment for all things Python. It is a general-purpose tool, however, so it takes a little initial effort to get it configured for Python.

Upgrading Spinmob

To upgrade Spinmob:

pip install spinmob --upgrade --no-cache-dir

or, if you're Thomas:

python -m pip install --upgrade --no-cache-dir

Direct download or git clone

If pip doesn't work for some reason, this is a sure-fire method: Create a "spinmob" folder in python's site-packages directory and either clone the spinmob repository there or download / unzip. We highly recommend using a git client as described on the contributing page. Spinmob is designed to work when cloned directly into site-packages.

Add a custom sidebar
Clone this wiki locally