# Langmuir Trough
This software is a custom controller and GUI for the research Langmuir trough
in the Gutow Lab at UW Oshkosh. It is written in Python and expects to run in a
Jupyter notebook environment. However, all of the parts that are not elements
of the user interface should work in a vanilla Python environment.
Hardware requirements:
Raspberry Pi compatible system with a [Pi-Plates
DAQC2](https://pi-plates.com/daqc2r1/) data acquisition plate
and a trough controlled by the DAQC2 plate. This software could be used with
a trough controlled some other way by rewriting the routines in `trough_util.
py`. The GUI front end would need no rewriting to use with a different
trough if a custom backend controlling the barriers, reading the temperature
and Whilhelmy balance is written. The backend needs to continually monitor
the trough and respond to the following commands: `Stop, Send, Start,
Direction, Speed, MoveTo, MotorCal, ConstPi, DataLabels, ShutDown`.
**If you do not have compatible hardware the GUI will run with a simulated
trough, allowing you to see how it works.**
## Usage
Once installed:
1. Turn on the power supply for the trough.
2. In a terminal navigate to the directory containing the trough software.
3. Start the virtual environment `pipenv shell`.
4. Launch Jupyter `jupyter notebook` (`jupyter lab` also works and is now
more stable).
5. Create a folder for the new day using the **New** menu near the top right
of the Jupyter browser page. Give it an appropriate name.
6. Switch to that folder by clicking on it.
7. Start a new ipython notebook using the **New** menu. Give it a
name that describes the experiment.
8. In the first cell initialize the trough by running the command `from
Trough import Trough_GUI`. This will take a while to run the first time
it is run each day because it needs to check the movement of the barriers.
9. To control and monitor the trough or do calibrations run the command
`Trough_GUI.Controls(Trough_GUI.calibrations)`
10. Do not do any real runs without making sure the calibrations are correct.
11. To start data collection (a run) run the command
`Trough_GUI.Collect_data.Run("name_for_run")`,
where you replace name_for_run with the text for the name of the run (no
spaces).
12. Set the run conditions.
13. You can start data collection by clicking the green "Run" button.
14. If you set the speed to zero the data collection will be displayed
versus time and will not stop until you click the red "Stop" button.
## Installation
### *OS setup - Ubuntu on Pi*
By default in Ubuntu 20.04 for Pis the gpio and spi groups do not exist.
The i2c group does (not always).
1. Make sure that the following packages are installed `rpi.gpio-common
python3-pigpio python3-gpiozero python3-rpi.gpio`.
2. You can avoid having to create a gpio group, by assigning users who need
gpio access to the dialout group. Check that /dev/gpiomem is part of that
group and that the dialout group has rw access. If not you will need to set
it.
3. Users also need to be members of the i2c group. If it does not exist create
it and then make that the group for /dev/i2c-1 with group rw permissions.
THIS MAY NOT BE NECESSARY.
4. The spi group needs to be created (addgroup?).
5. Additionally the spi group needs to be given rw access to the spi devices
at each boot. To do this create a one line rule in a file named
`/etc/udev/rules.d/50-spidev.rules` containing `SUBSYSTEM=="spidev",
GROUP="spi", MODE="0660"`. The file should have rw permission for root
and read permission for everyone else.
6. Make sure you have [pip](https://pip.pypa.io/en/stable/) installed for
python 3: `python3 -m pip --version` or `pip3 --version`. If you do not,
install using `apt
install python3-pip`.
### *Trough Software Installation*
To avoid library conflicts the software should be installed into a [virtual environment](https://docs.python.org/3/tutorial/venv.html?highlight=virtual%20environments).
Instructions for doing this using [pipenv](https://pipenv.pypa.io/en/latest/)
follow.
Log into your chosen user account:
1. Install [pipenv](https://pipenv.pypa.io/en/latest/): `pip3 install
--user pipenv`. You may
need to add `~/.local/bin` to your `PATH` to make `pipenv`
available in your command shell. More discussion:
[The Hitchhiker's Guide to
Python](https://docs.python-guide.org/dev/virtualenvs/).
2. Create a directory for the virtual environment you will be installing
into (example: `$ mkdir Trough`).
3. Navigate into the directory `$ cd Trough`.
4. Create the virtual environment and enter it `$ pipenv shell`. To get out of
the environment you can issue the `$ exit` command on the command line.
5. While still in the shell install the latest trough software and all its
requirements
`$ pip install -U langmuir_trough`.
6. Still within the environment shell test
this by starting jupyter `$ jupyter notebook`. Jupyter should launch in your
browser.
1. Open a new notebook using the default (Python 3) kernel.
2. In the first cell import the Trough_GUI:
`from Trough import Trough_GUI`.
When run this cell sets things up and tries to talk to the trough.
7. If you wish, you can make this environment available to an alternate Jupyter
install as a special kernel when you are the user.
1. Make sure you are running in your virtual environment `$ pipenv shell`
in the directory for virtual environment will do that.
2. Issue the command to add this as a kernel to your personal space:
`$ python -m ipykernel install --user --name=<name-you-want-for-kernel>`.
3. More information is available in the Jupyter/Ipython documentation.
A simple tutorial from Nikolai Jankiev (_Parametric Thoughts_) can be
found [here](https://janakiev.com/til/jupyter-virtual-envs/).
## Change Log
* 0.8.0 (May 12, 2023)
* Added capability to do very slow compressions (< 1 cm/min) by moving the
barriers intermittently at near their lowest continuous speed.
* Now record datapoint time_stamps as actual_time_stamp - run_time_stamp.
This avoids round off errors in the html based data storage file.
* BUG_FIXES:
* Errors in conversion of speeds between units.
* Make start boost voltage direction dependent.
* Fix inconsistent sign on skimmer corrections.
* Correct hanging of GUI updates during barrier calibrations.
* Fix wrong target value when units were cm**2.
* 0.7.0 (Apr. 28, 2023)
* Added Access to [pandas_GUI](https://jupyterphysscilab.github.io/jupyter_Pandas_GUI)
tools as `Trough_GUI.newPlot()`, `Trough_GUI.newFit()` and
`Trough_GUI.newCalculatedColumn()`.
* BUG_FIX: Opening a new notebook and importing Trough_GUI no longer
clobbers an already running notebook that is talking to the trough
A-to-D hardware.
* BUG_FIX: Stopping a data collection run now makes sure the barriers are
stopped.
* 0.6.0 (Mar. 29, 2023)
* Documentation updates including Gutow Lab Standard Operating Procedures
(SOPs).
* Refactored everything to inside the module `Trough`.
* 0.5.2 (Mar. 16, 2023) Now works in Jupyter Lab.
* Adjusted widget updating/clearing to work in Jupyter lab.
* Added JupyterLab >= 3.6.1 to requirements.
* 0.5.1 (Mar. 9, 2023)
* Include `spidev` package in requirements.
* More details reported when unable to "find trough".
* 0.5.0 (Mar. 4, 2023) First version with working GUI
* 0.1.0 First pypi compatible package version.
## Known issues
* 0.5.0 - 0.8.0 The estimated error on values converted to metric units
based on calibration fits appears to be too pessimistic.
* Inconsistent rendering of Latex ipywidget labels with ipywidgets >= 8.0.
Until figured out requiring ipywidgets < 8.0.
* Runs don't label graph axes reliably for x-axis units other than cm. This
appears to be associated with Latex in ipywidgets as well.
## Development
### [CodeRepository](https://github.com/gutow/Langmuir_Trough.git) | [Docs](https://gutow.github.io/Langmuir_Trough)
1. For development purposes clone the GIT repository.
2. Create the virtual environment to run it in within the development
directory `pipenv shell`.
3. Within the shell pip install for development `pip install -e .`.
### Constructing the Documentation
1. Make sure pdoc is installed and updated in the virtual environment `pip
install -U pdoc`.
2. Update any `.md` files included in `_init_.py`.
* Generally URLs should be absolute, not relative.
3. At the root level run pdoc `pdoc --logo-link
https://gutow.github.io/Langmuir_Trough/ --footer-text "Langmuir_Trough vX.X.X"
--math -html -o docs Trough` where `X.X.X` is the version number.
4. Because of the way the document building process works the background tasks
will be started. **You will have to stop the document build after the
documentation is done building (watch the `doc` folder) with a `^C` to
terminate it.**
### Releasing on PyPi
Proceed only if testing of the build is successful.
1. Update packaging software `pip install -U setuptools wheel twine`
2. Double check the version number in `setup.py`.
3. Rebuild the release: `python -m setup sdist bdist_wheel`.
4. Upload it: `python -m twine upload dist/*`
5. Make sure it works by installing it in a clean virtual environment. `pip
install -U ...`. **Copy the actual link from pypi.org.**
`. If it does not work, pull the release.
### Ideas/Things to do
* Make more robust by wrapping data collection in `try ...` so that it can
exit more gracefully and give up barrier monitoring?
* Add explanation of how to use the barrier watch deamon to prevent barrier
crashing if software fails.
Raw data
{
"_id": null,
"home_page": "https://github.com/gutow/Langmuir_Trough.git",
"name": "langmuir-trough",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Jonathan Gutow",
"author_email": "gutow@uwosh.edu",
"download_url": "https://files.pythonhosted.org/packages/23/62/fcf521fc9db5079205fc4132228fd9dcc2c86ee43f104031e0d164c31468/langmuir_trough-0.8.0.tar.gz",
"platform": null,
"description": "# Langmuir Trough\nThis software is a custom controller and GUI for the research Langmuir trough \nin the Gutow Lab at UW Oshkosh. It is written in Python and expects to run in a\nJupyter notebook environment. However, all of the parts that are not elements\nof the user interface should work in a vanilla Python environment.\n\nHardware requirements:\nRaspberry Pi compatible system with a [Pi-Plates \nDAQC2](https://pi-plates.com/daqc2r1/) data acquisition plate \nand a trough controlled by the DAQC2 plate. This software could be used with \na trough controlled some other way by rewriting the routines in `trough_util.\npy`. The GUI front end would need no rewriting to use with a different \ntrough if a custom backend controlling the barriers, reading the temperature \nand Whilhelmy balance is written. The backend needs to continually monitor \nthe trough and respond to the following commands: `Stop, Send, Start, \nDirection, Speed, MoveTo, MotorCal, ConstPi, DataLabels, ShutDown`.\n\n**If you do not have compatible hardware the GUI will run with a simulated \ntrough, allowing you to see how it works.**\n\n## Usage\n\nOnce installed:\n\n1. Turn on the power supply for the trough.\n2. In a terminal navigate to the directory containing the trough software.\n3. Start the virtual environment `pipenv shell`.\n4. Launch Jupyter `jupyter notebook` (`jupyter lab` also works and is now \n more stable).\n5. Create a folder for the new day using the **New** menu near the top right \n of the Jupyter browser page. Give it an appropriate name.\n6. Switch to that folder by clicking on it.\n7. Start a new ipython notebook using the **New** menu. Give it a\n name that describes the experiment.\n8. In the first cell initialize the trough by running the command `from \n Trough import Trough_GUI`. This will take a while to run the first time \n it is run each day because it needs to check the movement of the barriers.\n9. To control and monitor the trough or do calibrations run the command \n `Trough_GUI.Controls(Trough_GUI.calibrations)`\n10. Do not do any real runs without making sure the calibrations are correct.\n11. To start data collection (a run) run the command \n `Trough_GUI.Collect_data.Run(\"name_for_run\")`, \n where you replace name_for_run with the text for the name of the run (no \n spaces).\n12. Set the run conditions.\n13. You can start data collection by clicking the green \"Run\" button.\n14. If you set the speed to zero the data collection will be displayed \n versus time and will not stop until you click the red \"Stop\" button.\n\n## Installation\n### *OS setup - Ubuntu on Pi*\n\nBy default in Ubuntu 20.04 for Pis the gpio and spi groups do not exist.\nThe i2c group does (not always).\n\n1. Make sure that the following packages are installed `rpi.gpio-common \npython3-pigpio python3-gpiozero python3-rpi.gpio`.\n2. You can avoid having to create a gpio group, by assigning users who need\n gpio access to the dialout group. Check that /dev/gpiomem is part of that \n group and that the dialout group has rw access. If not you will need to set\n it.\n3. Users also need to be members of the i2c group. If it does not exist create \n it and then make that the group for /dev/i2c-1 with group rw permissions. \n THIS MAY NOT BE NECESSARY. \n4. The spi group needs to be created (addgroup?).\n5. Additionally the spi group needs to be given rw access to the spi devices\n at each boot. To do this create a one line rule in a file named \n `/etc/udev/rules.d/50-spidev.rules` containing `SUBSYSTEM==\"spidev\", \n GROUP=\"spi\", MODE=\"0660\"`. The file should have rw permission for root \n and read permission for everyone else.\n6. Make sure you have [pip](https://pip.pypa.io/en/stable/) installed for \n python 3: `python3 -m pip --version` or `pip3 --version`. If you do not, \n install using `apt \n install python3-pip`.\n\n### *Trough Software Installation*\n\nTo avoid library conflicts the software should be installed into a [virtual environment](https://docs.python.org/3/tutorial/venv.html?highlight=virtual%20environments).\nInstructions for doing this using [pipenv](https://pipenv.pypa.io/en/latest/)\nfollow.\n\nLog into your chosen user account:\n1. Install [pipenv](https://pipenv.pypa.io/en/latest/): `pip3 install \n --user pipenv`. You may\nneed to add `~/.local/bin` to your `PATH` to make `pipenv`\navailable in your command shell. More discussion: \n[The Hitchhiker's Guide to\nPython](https://docs.python-guide.org/dev/virtualenvs/).\n2. Create a directory for the virtual environment you will be installing\n into (example: `$ mkdir Trough`).\n3. Navigate into the directory `$ cd Trough`.\n4. Create the virtual environment and enter it `$ pipenv shell`. To get out of\n the environment you can issue the `$ exit` command on the command line.\n5. While still in the shell install the latest trough software and all its\n requirements\n `$ pip install -U langmuir_trough`.\n6. Still within the environment shell test\n this by starting jupyter `$ jupyter notebook`. Jupyter should launch in your \n browser.\n 1. Open a new notebook using the default (Python 3) kernel.\n 2. In the first cell import the Trough_GUI: \n `from Trough import Trough_GUI`.\n When run this cell sets things up and tries to talk to the trough.\n7. If you wish, you can make this environment available to an alternate Jupyter\ninstall as a special kernel when you are the user.\n 1. Make sure you are running in your virtual environment `$ pipenv shell` \n in the directory for virtual environment will do that.\n 2. Issue the command to add this as a kernel to your personal space: \n `$ python -m ipykernel install --user --name=<name-you-want-for-kernel>`.\n 3. More information is available in the Jupyter/Ipython documentation. \n A simple tutorial from Nikolai Jankiev (_Parametric Thoughts_) can be\n found [here](https://janakiev.com/til/jupyter-virtual-envs/). \n\n## Change Log\n* 0.8.0 (May 12, 2023)\n * Added capability to do very slow compressions (< 1 cm/min) by moving the \n barriers intermittently at near their lowest continuous speed.\n * Now record datapoint time_stamps as actual_time_stamp - run_time_stamp. \n This avoids round off errors in the html based data storage file.\n * BUG_FIXES:\n * Errors in conversion of speeds between units.\n * Make start boost voltage direction dependent.\n * Fix inconsistent sign on skimmer corrections.\n * Correct hanging of GUI updates during barrier calibrations.\n * Fix wrong target value when units were cm**2.\n* 0.7.0 (Apr. 28, 2023)\n * Added Access to [pandas_GUI](https://jupyterphysscilab.github.io/jupyter_Pandas_GUI)\n tools as `Trough_GUI.newPlot()`, `Trough_GUI.newFit()` and \n `Trough_GUI.newCalculatedColumn()`.\n * BUG_FIX: Opening a new notebook and importing Trough_GUI no longer \n clobbers an already running notebook that is talking to the trough \n A-to-D hardware.\n * BUG_FIX: Stopping a data collection run now makes sure the barriers are \n stopped.\n* 0.6.0 (Mar. 29, 2023)\n * Documentation updates including Gutow Lab Standard Operating Procedures \n (SOPs).\n * Refactored everything to inside the module `Trough`.\n* 0.5.2 (Mar. 16, 2023) Now works in Jupyter Lab.\n * Adjusted widget updating/clearing to work in Jupyter lab.\n * Added JupyterLab >= 3.6.1 to requirements.\n* 0.5.1 (Mar. 9, 2023) \n * Include `spidev` package in requirements. \n * More details reported when unable to \"find trough\".\n* 0.5.0 (Mar. 4, 2023) First version with working GUI\n* 0.1.0 First pypi compatible package version.\n\n## Known issues\n* 0.5.0 - 0.8.0 The estimated error on values converted to metric units \n based on calibration fits appears to be too pessimistic.\n* Inconsistent rendering of Latex ipywidget labels with ipywidgets >= 8.0. \n Until figured out requiring ipywidgets < 8.0.\n* Runs don't label graph axes reliably for x-axis units other than cm. This \n appears to be associated with Latex in ipywidgets as well.\n\n## Development\n\n### [CodeRepository](https://github.com/gutow/Langmuir_Trough.git) | [Docs](https://gutow.github.io/Langmuir_Trough)\n\n1. For development purposes clone the GIT repository.\n2. Create the virtual environment to run it in within the development \n directory `pipenv shell`.\n3. Within the shell pip install for development `pip install -e .`.\n\n### Constructing the Documentation\n\n1. Make sure pdoc is installed and updated in the virtual environment `pip \n install -U pdoc`.\n2. Update any `.md` files included in `_init_.py`.\n * Generally URLs should be absolute, not relative.\n3. At the root level run pdoc `pdoc --logo-link\nhttps://gutow.github.io/Langmuir_Trough/ --footer-text \"Langmuir_Trough vX.X.X\" \n--math -html -o docs Trough` where `X.X.X` is the version number.\n4. Because of the way the document building process works the background tasks \n will be started. **You will have to stop the document build after the \n documentation is done building (watch the `doc` folder) with a `^C` to \n terminate it.**\n\n### Releasing on PyPi\n\nProceed only if testing of the build is successful.\n\n1. Update packaging software `pip install -U setuptools wheel twine`\n2. Double check the version number in `setup.py`.\n3. Rebuild the release: `python -m setup sdist bdist_wheel`.\n4. Upload it: `python -m twine upload dist/*`\n5. Make sure it works by installing it in a clean virtual environment. `pip \n install -U ...`. **Copy the actual link from pypi.org.**\n `. If it does not work, pull the release.\n\n### Ideas/Things to do\n* Make more robust by wrapping data collection in `try ...` so that it can \n exit more gracefully and give up barrier monitoring?\n* Add explanation of how to use the barrier watch deamon to prevent barrier \n crashing if software fails.\n",
"bugtrack_url": null,
"license": "GPL-3.0+",
"summary": "Controls and collects data from Gutow Lab Langmuir Trough.",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/gutow/Langmuir_Trough.git"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c4974d0355be7b55d0ad4af868a7bb1b9c818517a8dd2b4b02edf9008ae4f242",
"md5": "27ec1b202184d8b08201ae37692489cf",
"sha256": "8d69dbe1c48d3be08c51a232e77a51e6deec037c7c450828ffc026231b743813"
},
"downloads": -1,
"filename": "langmuir_trough-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "27ec1b202184d8b08201ae37692489cf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 79033,
"upload_time": "2023-05-12T20:45:17",
"upload_time_iso_8601": "2023-05-12T20:45:17.812046Z",
"url": "https://files.pythonhosted.org/packages/c4/97/4d0355be7b55d0ad4af868a7bb1b9c818517a8dd2b4b02edf9008ae4f242/langmuir_trough-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2362fcf521fc9db5079205fc4132228fd9dcc2c86ee43f104031e0d164c31468",
"md5": "b5c21b48bada97eac3686c4bb315d1da",
"sha256": "5267de0c7e9e060cc2dd97208179c87f037f3e515684f27762db77e71f250a36"
},
"downloads": -1,
"filename": "langmuir_trough-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "b5c21b48bada97eac3686c4bb315d1da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 39126,
"upload_time": "2023-05-12T20:45:19",
"upload_time_iso_8601": "2023-05-12T20:45:19.779027Z",
"url": "https://files.pythonhosted.org/packages/23/62/fcf521fc9db5079205fc4132228fd9dcc2c86ee43f104031e0d164c31468/langmuir_trough-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-05-12 20:45:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "gutow",
"github_project": "Langmuir_Trough",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "langmuir-trough"
}
JSON
