ALPSS: A program for the automated analysis of photonic Doppler velocimetry spall signals

v1.1

Jacob M. Diamond^1,2, Samuel Salander³, K. T. Ramesh^1,2

¹ Department of Mechanical Engineering, Johns Hopkins University, Baltimore, MD, USA

² Hopkins Extreme Materials Institute (HEMI), Johns Hopkins University, Baltimore, MD, USA

³ Department of Physics and Astronomy, Johns Hopkins University, Baltimore, MD, USA

Copyright

GNU General Public License v3.0

Overview

ALPSS (A naL ysis of P hotonic Doppler velocimetry S pall S ignals) was developed to automate the processing of PDV spall signals. This readme is a simple quick-start guide. For comprehensive documentation please refer to the repository wiki. Any suggestions or bugs can be reported to jdiamo15@jhu.edu.

Citing ALPSS

For use in published works, ALPSS can be cited from its original paper ALPSS: A program for automated analysis of photonic Doppler velocimetry spall signals, in prep.

The repository itself can be cited using its DOI 10.5281/zenodo.7603823 (v1.1 only) or with the bibtex

@software{Diamond_ALPSS_2023,
  author = {Diamond, Jacob M. and Salander, Samuel and Ramesh, K.T.},
  doi = {10.5281/zenodo.7603823},
  month = {02},
  title = {{ALPSS}},
  url = {https://github.com/Jake-Diamond-9/ALPSS},
  version = {1.1},
  year = {2023}
}

Installation

It is recommended for users new to python to use Anaconda.

Downloading ALPSS Code

The ALPSS program files can be downloaded from the main page of the repository. Go to the green Code dropdown menu and select Download ZIP to download all files from the main branch of the repository. Then move the files to your desired directory.

Installing Required Packages

ALPSS requires the following packages:

The simplest way to install these packages is to use the prepared Anaconda environment in the file ALPSS_env.yml. To do this:

Open Anaconda and navigate to the Environments tab on the left-hand side underneath Home.
Towards the bottom of the window click Import.
From your local drive, select the file ALPSS_env.yml. Then click the green Import button. Note this process may take a few minutes as all the required packages are being imported.

Alternatively, if the ALPSS_env.yml install does not work, the packages can be installed individually via the Anaconda Navigator interface.

Open Anaconda and navigate to the Environments tab on the left hand side underneath Home.
Towards the bottom of the window click Create to create a new environment.
Name your new environment ("ALPSS_env" is recommended) and use the dropdown menu to install the latest version of Python.
In the ALPSS environment click the dropdown menu that says Installed and change it to All.
In the Search Packages bar type "matplotlib". Select the box next to the package with the name matplotlib and click the green Apply button in the bottom right. In the new package install window click the green Apply button.
In the Search Packages bar type "numpy". Select the box next to the package with the name numpy and click the green Apply button in the bottom right. In the new package install window click the green Apply button.
In the Search Packages bar type "scipy". Select the box next to the package with the name scipy and click the green Apply button in the bottom right. In the new package install window click the green Apply button.
In the Search Packages bar type "pandas". Select the box next to the package with the name pandas and click the green Apply button in the bottom right. In the new package install window click the green Apply button.
In the Search Packages bar type "opencv". Select the 3 boxes next to the packages with the names libopencv, opencv, and, py-opencv and click the green Apply button in the bottom right. In the new package install window click the green Apply button.
In the Search Packages bar type "watchdog". Select the box next to the package with the name watchdog and click the green Apply button in the bottom right. In the new package install window click the green Apply button.

Running ALPSS

With your ALPSS environment selected, return to the Anaconda home screen and launch the Spyder application. Once Spyder opens, click File -> Open, navigate to the directory with the ALPSS program files, and open the file alpss_run.py to run a single signal or alpss_auto_run.py to use automatic file detection.

A sample file is available for download from the Johns Hopkins OneDrive here. ALPSS has only been tested with input files in the form of a two column .txt file containing the time in column 1 and voltage in column 2 as seen in the sample file. I expect that the import would work fine for a .csv, but again, this has not been tested.

Additional data files are available through the paper by DiMarco et al. and can be accessed here.

Running a Single Signal

Open the file alpss_run.py. In the file there is a docstring that describes the input variables followed by the function alpss_main. If using the sample file provided above, only two input parameters need to be changed from the original repository file.

exp_data_dir should be changed to the directory where you have stored the sample file.
out_files_dir should be changed to the directory where you would like to save the output files.

In the toolbar click Run -> Run and ALPSS will run the sample file. At the conclusion of the run, a figure that shows the sub processes will be displayed in the Plots window and a results table will be displayed in the Console window. Output files will be saved in the directory specified in out_files_dir.

Running a Signal with Automatic File Detection

Open the file alpss_auto_run.py. If using the sample file provided above, only three changes need to be changed from the original repository file.

In the Watcher class, the variable DIRECTORY_TO_WATCH should be changed to the directory you would like to monitor for the file.
exp_data_dir should be changed to match the directory specified in DIRECTORY_TO_WATCH.
out_files_dir should be changed to the directory where you would like to save the output files.

To begin, the file you wish to run should not be located in DIRECTORY_TO_WATCH, but instead stored in another temporary location. Then in the toolbar click Run -> Run and ALPSS will begin to monitor DIRECTORY_TO_WATCH for changes. Next, click and drag your file from the temporary storage location in to DIRECTORY_TO_WATCH. The creation of the file will be automatically detected and the analysis will be run. At the conclusion of the run, a figure that shows the sub processes will be displayed in the Plots window and a results table will be displayed in the Console window. Output files will be saved in the directory specified in out_files_dir. Note, the process is the same for running multiple files. All files can be moved in to the monitored directory at the same time.

Acknowledgements and Funding

The authors would like to acknowledge the following people for their many helpful conversations and advice:

Dr. Chris DiMarco
Dr. Velat Killic
Dr. Debjoy Mallcik
Dr. Maggie Eminizer
Dr. David Elbert

Research was sponsored by the Army Research Laboratory and was accomplished under Cooperative Agreement Number W911NF-22-2-0014. The views and conclusions contained in this document are those of the authors and should not be interpreted as representing the official policies, either expressed or implied, of the Army Research Office or the U.S. Government. The U.S. Government is authorized to reproduce and distribute reprints for Government purposes notwithstanding any copyright notation herein.

arachid1/ALPSS