Introduction to PyCollisionDB

PyCollisionDB is a Python package for interacting with CollisionDB or ALADDIN2, databases of plasma collisional cross sections and rate coefficients.

Datasets in these collisional databases can be retrieved in a standardized way and compared, aggregated, and assessed using a set of predefined Python methods.

Installation

The PyCollisionDB package can be installed either from PYPI using pip

python3 -m pip install pycollisiondb

or from the source by running (one of the two) from the project source directory.

# either
python setup.py install

# or
python3 -m pip install .

PyCollision

The PyCollision object represents the main instance of the PyCollisionDB package for interacting with collisional databases, and datasets may be compared, output in various formats, and manipulated using the methods object as described below:

>>> from pycollisiondb.pycollisiondb import PyCollision

Dataset(s) Search

Collisional datasets can be retrieved using PyCollision class method get_datasets for a given query. The value of each query can be passed as a Python dictionary with valid metadata keys, and values can be specified either as a string or a list of comma-separated strings.

>>> # Fetch datasets from the server over the API.
>>> query = {'reactants': ['W+61', 'H']}
>>> pycoll = PyCollision.get_datasets(query=query)

or datasets can be acessed from a locally-cached archive

>>> # Specify the data directory for accessing the archive
>>> DATA_DIR = '/Users/tmp/results'
>>> # archive UUID
>>> archive_uuid = '026a7abd-5ed7-4e30-827d-f3f606f3fa98'
>>> pycoll = PyCollision.get_datasets(archive_uuid=archive_uuid, DATA_DIR=DATA_DIR)

Valid Query Keywords

>>> pycoll.VALID_QUERY_KEYWORDS
(ˈpkˈ,
 ˈpksˈ,
 ˈreaction_textˈ,
 ˈreaction_textsˈ,
 ˈreactant1ˈ,
 ˈreactant2ˈ,
 ˈproduct1ˈ,
 ˈproduct2ˈ,
 ˈprocess_typesˈ,
 ˈmethodˈ,
 ˈdata_typeˈ,
 ˈreactantsˈ,
 ˈproductsˈ,
 ˈdoiˈ)

>>> # Example
>>> pycoll = PyCollision.get_datasets(query={'rxns': ['H']})
---------------------------------------------------------------------------
PyCollisionDBKeywordError                 Traceback (most recent call last)
...
PyCollisionDBKeywordError: Invalid query keyword in dict_keys(['rxns'])

Please see the documentation for currently available choices or formats (if any) for query key values.

>>> # reaction_text is a string consisting of a single reaction,
>>> # while a comma-separated list of reactions can be searched with the reaction_texts key.
>>> # data_type can be specified as one of "cross section", "differential cross section" or "rate coefficient".
>>> query = {'reaction_text': "H+ + H 1s -> H+ + H+ + e-",
             'data_type': 'sigma'}
>>> pycoll = PyCollision.get_datasets(query=query)
---------------------------------------------------------------------------
PyCollisionDBConnectionError              Traceback (most recent call last)
...
PyCollisionDBConnectionError: Could not retrieve data: HTTP 400 (Bad Request) returned from https://db-amdis.org/collisiondb/api/

Accessing data from the datasets

>>> # Proton-impact ionization of H.
>>> query = {'reactants': ['H+', 'H 1s'],
              'process_types': ['HIN'],
              'data_type': 'cross section'}
>>> pycoll = PyCollision.get_datasets(query=query)

>>> # Datasets retrieved from the server as a dict keyed by pk ID.
>>> pycoll.datasets
{102737: D102737: H+ + H 1s → H+ + H+ + e-,
 107356: D107356: H+ + H 1s → H+ + H+ + e-,
 103103: D103103: H 1s + H+ → H+ + H+ + e-,
 103104: D103104: H 1s + H+ → H+ + H+ + e-} 

>>> # A list of datasets pks identified by each distinct reaction text.
>>> pycoll.pks
defaultdict(list,
        {'H+ + H 1s → H+ + H+ + e-': [102737, 107356],
         'H 1s + H+ → H+ + H+ + e-': [103103, 103104]}) 

>>> # Summarize datasets for each distint reaction text.
>>> pycoll.summarize_datasets()
H+ + H 1s → H+ + H+ + e-
========================================================================
 qid: D102737
 process_types: ['HIN']
 data_type: cross section
 refs: {'B32': {'doi': '10.1016/j.adt.2019.05.002'}}
 qid: D107356
 process_types: ['HIN']
 data_type: cross section
 refs: {'B45': {'doi': '10.1140/epjd/e2019-100380-x'}} 

H 1s + H+ → H+ + H+ + e-
========================================================================
 qid: D103103
 process_types: ['HIN']
 data_type: cross section
 refs: {'B33': {'doi': '10.1088/0022-3700/14/14/009'}}
 qid: D103104
 process_types: ['HIN']
 data_type: cross section
 refs: {'B34': {'doi': '10.1088/0022-3700/20/11/016'}}

>>> # Contents of the manifest.json file available in archive
>>> pycoll.manifest 
 {'timestamp': '2022-12-08 16:00:32.768200+00:00',
  'uuid': '4d3bf0d4-c786-4712-b7a6-e5c04e67c89c',
  'GET_string': '',
  'ndatasets': 4,
  'datasets': {'D102737': 'H+ + H 1s → H+ + H+ + e-',
  'D107356': 'H+ + H 1s → H+ + H+ + e-',
  'D103103': 'H 1s + H+ → H+ + H+ + e-',
  'D103104': 'H 1s + H+ → H+ + H+ + e-'}}  

>>> # Resolve the references for all the datasets into proper, citeable format.
>>> # this accesses the django-pyref API through the Server.
>>> pycoll.REFS_API_URL 
'https://db-amdis.org/collisiondb/refs/api/'

>>> pycoll.resolve_refs()
>>> # a dict with bibliographic data identified by pk ID
>>> pycoll.refs
{
'B32': {'authors': 'H. Agueny, J. Petter Hansen, A. Dubois, A. Makhoute, A. Taoutioui, N. Sisourat',
 'title': 'Electron capture, ionization and excitation cross sections for keV collisions between fully stripped ions and atomic hydrogen in ground and excited states',
 'journal': 'Atomic Data and Nuclear Data Tables',
 'volume': '129-130',
 'page_start': '101281',
 'page_end': '',
 'article_number': '101281',
 'year': 2019,
 'note': '',
 'doi': '10.1016/j.adt.2019.05.002',
 'bibcode': '2019ADNDT.12901281A',
 'url': 'https://dx.doi.org/10.1016/j.adt.2019.05.002'},
'B33': {...},
'B34': {...},
'B45': {...}
}

More details

>>> # List of all datasets pks 
>>> pycoll.all_pks
[102737, 107356, 103103, 103104]

>>> # Access to individual dataset via pk
>>> pycoll.datasets[102737].metadata
{'qid': 'D102737',
 'reaction': 'H+ + H 1s → H+ + H+ + e-',
 'process_types': {'HIN': 'Ionization'},
 'data_type': 'cross section',
 'refs': {'B32': {'doi': '10.1016/j.adt.2019.05.002'}},
 'json_comment': {'comment': 'Ionization cross sections in H+ + H collisions using a semiclassical close-coupling approach. Cross sections represent the average values of the results obtained with two basis sets and the uncertainties provide the estimate of convergence of the cross sections'},
 'json_data': {'method': 'CC',
 'columns': [{'name': 'E', 'units': 'eV.u-1'},
 {'name': 'sigma', 'units': 'cm2'}]}}

>>> # Prints the numerical values of datasets along with units.
>>> pycoll.datasets[102737].print_values()
E / eV.u-1 sigma / cm2
1000.0 5.471e-19
4000.0 1.96e-18
9000.0 1.235e-17
16000.0 4.05e-17
25000.0 9.192e-17
36000.0 1.405e-16
49000.0 1.628e-16
64000.0 1.605e-16
81000.0 1.45e-16
100000.0 1.248e-16

>>> # Metadata for all datasets can be accessed with a for loop.
>>> for ds in pycoll.datasets.values():
>>>     print(ds.metadata)

Convert Units

The PyCollision method convert_units can be used to change the units of datasets.

>>> pycoll.datasets[102737].x
array([  1000.,   4000.,   9000.,  16000.,  25000.,  36000.,  49000.,
     64000.,  81000., 100000.])
>>> # The units of all datasets are changed,
>>> # Energy is changed from eV.u-1 (default) to keV.u-1 and sigma from cm2 (default) to a02 (atomic units).
>>> # This accesses the pyqn library.
 >>> pycoll.convert_units({'E': 'keV.u-1', 'sigma': 'a02'})
 >>> pycoll.datasets[102737].x
 array([  1.,   4.,   9.,  16.,  25.,  36.,  49.,  64.,  81., 100.])

>>> # Change the units of a single dataset,
>>> # provide the column name followed by units as arguments.
>>> pycoll.datasets[102737].convert_units('sigma', 'm2')

Visualization tools

The PyCollision method plot_all_datasets can be used to create plots using the pyplot submodule of the Matplotlib library as the visualization utility.

>>> import matplotlib.pyplot as plt
>>> %matplotlib notebook
>>> # Make a plot, indicating how the data should be labelled.
>>> fig, ax = plt.subplots()
>>> # The default legend consists of qid/pk and reaction labels,
>>> # it can be customized to include refs and process_types or either of these lables.
>>> pycoll.plot_all_datasets(ax, label=('reaction', 'qid', 'refs', 'process_types'))
>>> plt.legend()

Connection to the ALADDIN2 API

>>> #By default, PyCollisionDB interacts with the API to the CollisionDB server
>>> pycoll.API_URL
'https://db-amdis.org/collisiondb/api/'

>>> #API_URL can be directed to ALADDIN2 server by passing argument DB_URL 
>>> DB_URL = 'https://db-amdis.org/aladdin2'
>>> pycoll = PyCollision.get_datasets(query=query,DB_URL=DB_URL)
>>> pycoll.API_URL
'https://db-amdis.org/aladdin2/api/'