<commit_before>Quickstart and Basic Usage
==============================================

.. testsetup:: *

   import basis_set_exchange


Installation
-------------------

The BSE can be installed with `pip`.

To install from PyPI: `pip install basis_set_exchange`

To install from the local directory, you can use `pip install -e .` inside
the cloned git repository.


Importing
-------------------

All end-user functionality is available by importing the `basis_set_exchange` module.


Getting a basis set
-------------------

The main function for getting a basis set is :func:`basis_set_exchange.get_basis`.
Output format is controlled by the `fmt` parameter. By default, a python
dictionary is returned. If a format is specified, a string is returned
instread.

.. doctest::

   >>> # Get a basis set as a python dictionary
   >>> bs_dict = basis_set_exchange.get_basis('6-31G*')
   >>> bs_dict['basis_set_name']  
   '6-31G*'

   >>> # Basis set names are case insensitive
   >>> bs_dict = basis_set_exchange.get_basis('6-31g*')
   >>> bs_dict['basis_set_name']  
   '6-31G*'

   >>> # Same as above, but in gaussian format (as a string)
   >>> # header=False disables printing an information block
   >>> bs_str = basis_set_exchange.get_basis('6-31G*', fmt='gaussian94', header=False)
   >>> print(bs_str)
   H     0
   S   3   1.00
        18.731137               0.0334946
         2.8253944              0.2347269
   ...


   >>> # Available formats are available via get_formats
   >>> basis_set_exchange.get_formats()
   {'json': 'JSON', 'nwchem': 'NWChem', 'gaussian94': 'Gaussian94', 'gamess_us': 'GAMESS US', 'psi4': 'Psi4'} 


By default, all elements for which the basis set is defined are included - this
can be overridden with the `elements` parameter

.. doctest::

   >>> # Get only carbon and oxygen
   >>> bs_str = basis_set_exchange.get_basis('aug-cc-pvtz', elements=[6,8], fmt='nwchem', header=False)
   >>> print(bs_str)
   BASIS "ao basis" PRINT
   #BASIS SET: (11s,6p,3d,2f) -> [5s,4p,3d,2f]
   C    S
      8236.0000000              0.0005310             -0.0001130              0.0000000              0.0000000
   ...

   >>> # Can also use strings with the element symbols (and be mixed with integers)
   >>> # and integers as strings
   >>> bs_str = basis_set_exchange.get_basis('aug-cc-pvtz', elements=['C', 8, 'Ne', '16'], fmt='nwchem', header=False)
   >>> print(bs_str)
   BASIS "ao basis" PRINT
   #BASIS SET: (11s,6p,3d,2f) -> [5s,4p,3d,2f]
   C    S
      8236.0000000              0.0005310             -0.0001130              0.0000000              0.0000000
   ...


Getting references
------------------

Reference/citations can be obtained via :func:`basis_set_exchange.get_references`. The `elements`
parameter is similar to that in :func:`basis_set_exchange.get_basis`.

The `fmt` parameter controls the output format. By default, the output
is a dictionary. If `fmt` is specified, the output is a string.

.. doctest::
   >>> # Get references for 6-31G*, all elements, as a list of dictionaries
   >>> refs = basis_set_exchange.get_references('6-31G*')
   >>> print(refs[0])
   {'reference_info': [{'reference_description': ...
 
   >>> # As bibtex, restricting to H and F
   >>> bib = basis_set_exchange.get_references('6-31G*', fmt='bib', elements=[1,9])
   >>> print(bib)
   % H
   %     31G valence double-zeta
   %         ditchfield1971a
   %
   % F
   %     6-31G valence double-zeta
   %         hehre1972a
   %
   %     Polarization functions associated with 6-31G
   %         hariharan1973a
   %
   <BLANKLINE> 
   <BLANKLINE> 
   @article{ditchfield1971a,
       author = {<NAME> <NAME> <NAME>.}, 
       title = {Self-Consistent Molecular-Orbital Methods. IX. An Extended Gaussian-Type Basis for Molecular-Orbital Studies of Organic Molecules},
       journal = {J. Chem. Phys.},
       volume = {54},
       page = {724-728},
       year = {1971},
       doi = {10.1063/1.1674902}
   }
   ...


   >>> # Available formats are available via get_reference_formats
   >>> basis_set_exchange.get_reference_formats()
   {'json': 'JSON', 'bib': 'BibTeX', 'txt': 'Plain Text'}


Versioning
-------------------

Basis sets within the package are versioned. This allows for changes to be made to a
basis set, while keeping the old data accessible for historical purposes.
Versions are specified by integers. By default,
v0 will match the original BSE data.

Versions are meant to be increased only when there is a material change to the data.
If data is simply being added (new elements), the version will not be incremented.

Both `basis_set_exchange.get_basis` and :func:`basis_set_exchange.get_references` accept a `version` parameter,
which is a string. If `version` is not specified, the latest version is used.

.. doctest::

   >>> # Get latest version
   >>> bs_str = basis_set_exchange.get_basis('6-31G*', fmt='gaussian94')

   >>> # Get the original BSE data
   >>> bs_str = basis_set_exchange.get_basis('6-31G*', version='0', fmt='gaussian94')

   >>> # Versions can also be passed as integers
   >>> bs_str = basis_set_exchange.get_basis('6-31G*', version=0, fmt='gaussian94')
<commit_msg>Update documentation with OrderedDict stuff<commit_after>Quickstart and Basic Usage
==============================================

.. testsetup:: *

   import basis_set_exchange


Installation
-------------------

The BSE can be installed with `pip`.

To install from PyPI: `pip install basis_set_exchange`

To install from the local directory, you can use `pip install -e .` inside
the cloned git repository.


Importing
-------------------

All end-user functionality is available by importing the `basis_set_exchange` module.


Getting a basis set
-------------------

The main function for getting a basis set is :func:`basis_set_exchange.get_basis`.
Output format is controlled by the `fmt` parameter. By default, a python
dictionary is returned. If a format is specified, a string is returned
instread.

.. doctest::

   >>> # Get a basis set as a python dictionary
   >>> bs_dict = basis_set_exchange.get_basis('6-31G*')
   >>> bs_dict['basis_set_name']  
   '6-31G*'

   >>> # Basis set names are case insensitive
   >>> bs_dict = basis_set_exchange.get_basis('6-31g*')
   >>> bs_dict['basis_set_name']  
   '6-31G*'

   >>> # Same as above, but in gaussian format (as a string)
   >>> # header=False disables printing an information block
   >>> bs_str = basis_set_exchange.get_basis('6-31G*', fmt='gaussian94', header=False)
   >>> print(bs_str)
   H     0
   S   3   1.00
        18.731137               0.0334946
         2.8253944              0.2347269
   ...


   >>> # Available formats are available via get_formats
   >>> # (returned as an OrderedDict)
   >>> basis_set_exchange.get_formats()
   OrderedDict([('nwchem', 'NWChem'), ('gaussian94', 'Gaussian94'), ('psi4', 'Psi4'), ('gamess_us', 'GAMESS US'), ('turbomole', 'Turbomole'), ('json', 'JSON')])


By default, all elements for which the basis set is defined are included - this
can be overridden with the `elements` parameter

.. doctest::

   >>> # Get only carbon and oxygen
   >>> bs_str = basis_set_exchange.get_basis('aug-cc-pvtz', elements=[6,8], fmt='nwchem', header=False)
   >>> print(bs_str)
   BASIS "ao basis" PRINT
   #BASIS SET: (11s,6p,3d,2f) -> [5s,4p,3d,2f]
   C    S
      8236.0000000              0.0005310             -0.0001130              0.0000000              0.0000000
   ...

   >>> # Can also use strings with the element symbols (and be mixed with integers)
   >>> # and integers as strings
   >>> bs_str = basis_set_exchange.get_basis('aug-cc-pvtz', elements=['C', 8, 'Ne', '16'], fmt='nwchem', header=False)
   >>> print(bs_str)
   BASIS "ao basis" PRINT
   #BASIS SET: (11s,6p,3d,2f) -> [5s,4p,3d,2f]
   C    S
      8236.0000000              0.0005310             -0.0001130              0.0000000              0.0000000
   ...


Getting references
------------------

Reference/citations can be obtained via :func:`basis_set_exchange.get_references`. The `elements`
parameter is similar to that in :func:`basis_set_exchange.get_basis`.

The `fmt` parameter controls the output format. By default, the output
is a dictionary. If `fmt` is specified, the output is a string.

.. doctest::
   >>> # Get references for 6-31G*, all elements, as a list of dictionaries
   >>> refs = basis_set_exchange.get_references('6-31G*')
   >>> print(refs[0])
   {'reference_info': [{'reference_description': ...
 
   >>> # As bibtex, restricting to H and F
   >>> bib = basis_set_exchange.get_references('6-31G*', fmt='bib', elements=[1,9])
   >>> print(bib)
   % H
   %     31G valence double-zeta
   %         ditchfield1971a
   %
   % F
   %     6-31G valence double-zeta
   %         hehre1972a
   %
   %     Polarization functions associated with 6-31G
   %         hariharan1973a
   %
   <BLANKLINE> 
   <BLANKLINE> 
   @article{ditchfield1971a,
       author = {<NAME>. and <NAME>. and <NAME>.}, 
       title = {Self-Consistent Molecular-Orbital Methods. IX. An Extended Gaussian-Type Basis for Molecular-Orbital Studies of Organic Molecules},
       journal = {J. Chem. Phys.},
       volume = {54},
       page = {724-728},
       year = {1971},
       doi = {10.1063/1.1674902}
   }
   ...


   >>> # Available formats are available via get_reference_formats
   >>> # (returned as an OrderedDict)
   >>> basis_set_exchange.get_reference_formats()
   OrderedDict([('bib', 'BibTeX'), ('txt', 'Plain Text'), ('json', 'JSON')])


Versioning
-------------------

Basis sets within the package are versioned. This allows for changes to be made to a
basis set, while keeping the old data accessible for historical purposes.
Versions are specified by integers. By default,
v0 will match the original BSE data.

Versions are meant to be increased only when there is a material change to the data.
If data is simply being added (new elements), the version will not be incremented.

Both `basis_set_exchange.get_basis` and :func:`basis_set_exchange.get_references` accept a `version` parameter,
which is a string. If `version` is not specified, the latest version is used.

.. doctest::

   >>> # Get latest version
   >>> bs_str = basis_set_exchange.get_basis('6-31G*', fmt='gaussian94')

   >>> # Get the original BSE data
   >>> bs_str = basis_set_exchange.get_basis('6-31G*', version='0', fmt='gaussian94')

   >>> # Versions can also be passed as integers
   >>> bs_str = basis_set_exchange.get_basis('6-31G*', version=0, fmt='gaussian94')

{'fraction_non_alphanumeric': 0.1454025726536446, 'fraction_numerical': 0.0474511672224869, 'mean_word_length': 2.93993993993994, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 221, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 12, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5060087', 'n_tokens_mistral': 3760, 'n_tokens_neox': 3256, 'n_words': 1022}