Home - Spinmob/spinmob GitHub Wiki

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:

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.

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.

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

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.

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.

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
   

Windows: Install Python 3 from the built-in Microsoft store. You can get it from python.org but then you have to mess with environment variables.

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

python3 -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 "activate" it, every time:

• Windows: From the command prompt, run the activate script with path\to\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 -ExecutionPolicy RemoteSigned -Scope CurrentUser.

• 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

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 for the finicky "PyQt", which is responsible for creating graphics. 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

On some (linux) systems importing spinmob will still fail, despite PyQt5 being present, complaining about libg or something. To rectify this, you may have to install glib2-devel or equivalent using apt or zypper or your distribution's package manager. Or dump your console's output into claude and ask it what happened. :)

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.

Tricks to explain eventually:

• Install the Python and Jupyter Extensions from Microsoft
• Windows: install ipykernel with pip install ipykernel
• EITHER: Preferences -> Settings -> Extensions -> Python -> Default interpreter (enter the path to python executable)
• OR: ctrl-shift-p "Python: Select Interpreter" "Enter interpreter path" "Find..." to browse.
• Bind shortcuts to Jupyter: Run current file in interactive terminal
• On first run, it may ask you to install libraries, e.g., ipykernel

To upgrade Spinmob:

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

or, if you're Thomas:

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

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.