pysica 0.4.3

PYthon tools for SImulation and CAlculus

Contents

• Introduction

• Installing and importing pysica

  • Distribution method

  • Dependencies

  • How to install in the global Python environment

  • How to install in a virtual Python environment

  • How to install in a local directory

  • How to import

• Documentation

• Package structure

  • constants (module)

  • parameters (module)

  • analysis (package)

  • functions (package)

  • managers (package)

  • plasma (package)

Introduction

This package contains a collection of tools developed for some specific simulation and calculus tasks in some fields of physics, including nonthermal plasma discharges, as well as surface modification and analysis. The package was developed to fit my own needs, and it is released under the GNU GPL licence in the hope it can be helpful to someone else. Of course, there are no warranties of any kind, as stated in the licence.

Installing and importing pysica

Distribution method

Creating a specific package of pysica for each of the main Linux distributions (e.g. Debian, Red Hat, SUSE, and so on) would be too difficult and time consuming, so I have decided to distribute it using the Python wheel system, that is distribution-independent. Unfortunately, this installation method is concurrent with the specific one used by the Linux distribution (e.g. apt for Debian), so many distributions allow to use it only inside a Python virtual environment, to prevent the possibility of conflicts between packages installed by the different methods. The procedure to create a virtual environment and install pyisica inside is described in the section How to install in a virtual Python environment of this document. However, if you find uncomfortable to use a virtual environment, you can also install the pysica package in a local directory of your choice, as described in the section How to install in a local directory.

Note

The package has been developed and tested in a Linux-based operative system. Some subpackages could probably be used under other systems also, but they have not been tested on them and there is no guarantee that they would work. The modules have been compiled from Fortran as Linux executables: if you want to use them in another operating system you need to recompile them using the f2py program and a Fortran compiler. The directories named fortran contain the Fortran source files, the compiled modules and the scripts used for the compilation (the name of which always start with ‘f2py’), but the options used in the scripts to call f2py are specific for linux and the gnu95 Fortran compiler.

Dependencies

This package depends heavily on numpy , while some specific modules and packages depend on scipy and matplotlib also. Some packages make use of tkinter and of the gnuplot progam, but they should work also without them, although without some features.

How to install in the global Python environment

pysica is distribuited as a Python wheel so, if you have the program pip installed on your system and the Linux distribution you are using allows you to do so, you can type at the teminal:

$ pip install pysica

in this way the Python interpreter will be able to use the pysica package regardless of the location from where it is invoked. If pip is not installed on your system, you will have to install it following the specific method of the distribution you are using, e.g. for Debian-related distibutions (including Ubuntu):

$ sudo apt-get install pip

Note

In several Linux distributions (including Debian-related ones, like Ubuntu) the operative system does not allow pip to install software in the main file hierarchy and you will get an error message saying “externally managed environment” or something similar. In this situation, you can install the package in a virtual Python environment, as described in the section How to install in a virtual Python environment, or in a local directory, as described in the How to install in a local directory section.

How to install in a virtual Python environment

Creating a Python virtual environment allows you to install pysica in distributions that do not allow pip to install Python packages in the main filesystem. You can find detailed instructions on how to create and use a virtual environment in this page of the Python documentation. In the following, a step-by-step description is provided of the procedure I would recommend to create a virtual environment for a specific project and install pysica inside it.

• Open the terminal and move to the directory you want to use for your project, let’s assume the directory name is myproject

• Decide a name for the virtual environment you are going to create, since you can create several environments in parallel. Let’s assume you have chosen the name envpysica.

• Create the environment using the following command at the Linux console:

  $ python3 -m venv envpysica

  this will create a new directory inside the myproject directory, named envpysica, inside which a copy of the Python system will be created.

• Now you have to activate the envpysica virtual environment by the following command:

  $ source ./envpysica/bin/activate

  or equivalently:

  $ . ./envpysica/bin/activate

  where the first dot is a short for the command source.

  After the activation, the shell prompt should change in this way:

  (envpysica) $

  showing that you are using the envpysica environment. While envpysica is activated, if you call the Python interpreter it will use the packages that are inside the envpysica directory instead of the ones stored in the global filesystem. Moreover, if you install a Python package using the pip program, it will be installed in that directory.

• You can now install the pysica package inside the envpysica environment, and its files will be stored in the envpysica directory instead of in the global Linux file structure. To do this, type the following command at the terminal:

  (envpysica) $ pip install pysica

  the installation process should start and a progress bar should be showed in the terminal. After the installation is completed, you can run the Python interpreter and import the pysica module as described in the section How to import.

• When you have finished working with pysica, you can exit from the envpysica environment by typing at the console the command:

  (envpysica) $ deactivate

  and the shell prompt should return the normal one.

Now, each time you want to use pysica, you have to enter the envpysica environment by moving to the myproject directory and running the command:

$ . ./envpysica/bin/activate

and then run the Python interpreter.

How to install in a local directory

If your Linux distribution does not allow you to install the package in the global file structure, and you do not want to use a virtual environment, you can install pysica in any directory of your system by dowloading the most recent zip or tar.gz archive from the pysica GitHub page and unzipping it in a directory of your choice.

A new directory will be created, named pysica-x.y.z, where x.y.z identifies the version number. In order to use pysica, you will have to and call the Python interpreter from this pysica-x.y.z directory, so that it will be able to find the package files.

You can also use the package calling the Python intepreter from another directory, but you have to create in that directory a symbolic link to the directory named pysica, which is inside the pysica-x.y.z directory created during the zip archive extraction.

How to import

Once you have installed pysica, you can run the Python interpreter from the console:

$ python3

and then import pysica using the import directive as usual:

>>> import pysica

Or you can import a single mudule or package that you need, such as:

>>> from pysica.managers import gnuplot_manager

or

>>> from pysica.analysis import spectra

Documentation

Documentation about the modules and packages is available in the docstrings, which can be accessed inside the Python interpreter using the help function, after you have imported them. As an example, to read the docstring of the subpackage named analysis you can type:

>>> import pysica.analysis
>>> help(pysica.analysis)

or:

>>> from pysica import analysis
>>> help(analysis)

Note that, due to the Python importing mechanism, in order for the help function to work you must import the specific subpackage on which you want help: e.g. if you import the main package pysica, the help fucntion will not work on the subpackage pysica.analysis.

For some packages, additional documentation can be found in the doc directory of the GitHub repository. In this case, a direct link to the documentation is given in the corresponding paragraph of the section Package structure.

Package structure

In the following, the main modules and subpackages are listed.

constants (module)

Contains some physical constants used in various modules and packages.

parameters (module)

Contains some parameters used in various modules and packages.

analysis (package)

Contains some modules to manage distribution functions and data histograms.

univariate (module)

tools for the statistical analysis of univariate samples;

bivariate (module)

tools for the statistical analysis of bivariate samples;

spectra (module)

tools for the analysis of different types of spectra, whith a special focus on

• optical data (e.g. transmission spectra) of thin films;

• surface morphology data (e.g. surface roughness analysis).

functions (package)

Contains some general purpose functions.

fortran (package)

some general purpose functions, compiled from Fortran using f2py, they are collected in the fmathematics module;

mathematics (module)

some general purpose mathematical funtions;

statistics (module)

some generic statistics functions;

pdf (module)

some probabilty distribution functions (pdf);

random_pdf (module)

functions useful to generate random numbers following specific pdfs;

physics (module)

some general purpose funcions used in generic physics applications;

optics (module)

some functions useful for optical applications.

managers (package)

Contains some modules and packages used to manage input/output of data from/to ascii files, to print physical quantities managing the unit prefixes, and to plot data by means of the gnuplot program.

io (package)

some modules used for generic input-output management;

data_manager (module)

tools to manage data reading and writing from files;

unit_manager (module)

tools to manage the output of numerical data with automatic managment of unit prefixies;

gnuplot_manager (package)

a package to facilitate the use of gnuplot inside Python [1].

[1]

This package is also available as a standalone package (without the rest of pysica) on its own GitHub page, where you can find extensive documentation about it.

plasma (package)

A package containing tools for the simulation of plasma discharges.

ccpla (package)

a package containing scripts, modules, and subpackages used to simulate low pressure capacitively coupled discharges. Documentation about this package is given here.