<commit_before>"""Functions to calculate classical transport coefficients.

.. topic:: Examples:

   * :ref:`sphx_glr_auto_examples_plot_braginskii.py`

Introduction
============

Classical transport theory is derived by using kinetic theory to close the
plasma two-fluid (electron and ion fluid) equations in the collisional limit.
The first complete model in this form was done by <NAME> [1]_.

This module uses fitting functions from literature ([1]_, [2]_, [3]_, [4]_,
[5]_ and the next section) to calculate the transport coefficients, which are
the resistivity, thermoelectric conductivity, thermal conductivity, and
viscosity.

Keep in mind the following assumptions under which the transport equations
are derived:

1. The plasma is fully ionized, only consisting of ions and electrons.
   Neutral atoms are neglected.
2. Turbulent transport does not dominate
3. The velocity distribution is close to Maxwellian. This implies:
    i. Collisional mean free path << gradient scale length along field
    ii. Gyroradius << gradient scale length perpendicular to field
4. The plasma is highly collisional: collisional frequency >> gyrofrequency

When classical transport is not valid, e.g. due to the presence of strong
gradients or turbulent transport, the transport is significantly increased
by these other effects. Thus classical transport often serves as a lower
bound on the losses / transport encountered in a plasma.

Using the module and available variables
========================================
Given that many of the transport variables share a lot of the same computation
and many are often needed to be calculated simultaneously, this module provides
a `ClassicalTransport` class that can be initialized once with all of the
variables necessary for calculation. It then provides all of the functionality
as methods (please refer to its documentation).

If you only wish to calculate a single transport variable (or if just don't
like object oriented interfaces), we have also provided function based wrappers
that use `ClassicalTransport` under the hood. For documentation on the wrappers
themselves and for some explanation of each of the variables, see:

* `resistivity`
* `thermoelectric_conductivity`
* `ion_thermal_conductivity`
* `electron_thermal_conductivity`
* `ion_viscosity`
* `electron_viscosity`

.. warning::

    Please note that as PlasmaPy is a very new package, this API should not be
    considered stable yet.

Classical transport models
==========================
In this section, we present a broad overview of classical transport models
implemented within this module.

Braginskii [1]_
---------------

The original Braginskii treatment as presented in the highly cited review
paper from 1965. Coefficients are found from expansion of the kinetic
equation in Laguerre polynomials, truncated at the second term in their
series expansion (k = 2). This theory allows for arbitrary Hall parameter
and include results for Z = 1, 2, 3, 4, and infinity (the case of Lorentz
gas completely stripped of electrons, and the stationary ion approximation).

Spitzer-Harm [2]_ [3]_
----------------------

These coefficients were obtained from a numerical solution of the Fokker-
Planck equation. They give one of the earliest and most accurate (in the
Fokker-Planck sense) results for electron transport in simple plasma. They
principally apply in the unmagnetized / parallel field case, although for
resistivity Spitzer also calculated a famous result for a strong
perpendicular magnetic field. Results are for Z = 1, 2, 4, 16,
and infinity (Lorentz gas / stationary ion approximation).

Epperlein-Haines [4]_
---------------------

Not yet implemented.

Ji-Held [5]_
------------

This is a modern treatment of the classical transport problem that has been
carried out with laudable care. It allows for arbitrary hall parameter and
arbitrary Z for all coefficients. Similar to the Epperlein-Haines model,
it corrects some known inaccuracies in the original Braginskii results,
notably the asymptotic behavior of alpha-cross and beta_perp as Hall ->
+infinity. It also studies effects of electron collisions in the ion
terms, which all other treatments have not. To neglect electron-electron
collisions, leave mu = 0. To consider them, specify mu and theta.

References
==========
.. [1] <NAME>. "Transport processes in a plasma." Reviews of
       plasma physics 1 (1965): 205. (1965)
.. [2] <NAME>, Lyman, and <NAME>. "Transport phenomena in a
       completely ionized gas." Physical Review 89.5 (1953): 977. (1953)
.. [3] Physics of Fully Ionized Gases, <NAME> (1962)
.. [4] <NAME>., and <NAME>. "Plasma transport coefficients
       in a magnetic field by direct numerical solution of the
       Fokker–Planck equation." The Physics of fluids 29.4 (1986):
       1029-1041.
.. [5] <NAME>, and <NAME>. "Closure and transport theory for
       high-collisionality electron-ion plasmas." Physics of Plasmas 20.4
       (2013): 042114.
"""
import warnings

import numpy as np
from astropy import units as u

from plasmapy import utils
from plasmapy import atomic
from plasmapy.atomic.atomic import _is_electron
from .collisions import Coulomb_logarithm
from plasmapy.physics.parameters import (Hall_parameter,
                                         _grab_charge)
from plasmapy.physics.transport.collisions import (fundamental_electron_collision_freq,
                                                   fundamental_ion_collision_freq)
from plasmapy.constants import e, m_e, k_B

__all__ = [
    "ClassicalTransport",
    "resistivity",
    "thermoelectric_conductivity",
    "ion_thermal_conductivity",
    "electron_thermal_conductivity",
    "ion_viscosity",
    "electron_viscosity",
]

class ClassicalTransport:
    r"""
    Classical transport coefficients (e.g. Braginskii, 1965).

    Notes
    -----
    TODO


    Parameters
    ----------
    T_e : ~astropy.units.Quantity
        Electron temperature in units of temperature or energy per particle

    n_e : ~astropy.units.Quantity
        The electron number density in units convertible to per cubic meter.

    T_i : ~astropy.units.Quantity
        Ion temperature in units of temperature or energy per particle

    n_i : ~astropy.units.Quantity
        The ion number density in units convertible to per cubic meter.

    ion_particle : string
        Representation of the ion species (e.g., 'p' for protons,
        'e' for electrons, 'D+' for deuterium, or 'He-4 +1' for singly
        ionized helium-4). If no charge state information is provided,
        then the particles are assumed to be singly charged.<commit_msg>fill out doc for ClassicalTransport object<commit_after>"""Functions to calculate classical transport coefficients.

.. topic:: Examples:

   * :ref:`sphx_glr_auto_examples_plot_braginskii.py`

Introduction
============

Classical transport theory is derived by using kinetic theory to close the
plasma two-fluid (electron and ion fluid) equations in the collisional limit.
The first complete model in this form was done by <NAME> [1]_.

This module uses fitting functions from literature ([1]_, [2]_, [3]_, [4]_,
[5]_ and the next section) to calculate the transport coefficients, which are
the resistivity, thermoelectric conductivity, thermal conductivity, and
viscosity.

Keep in mind the following assumptions under which the transport equations
are derived:

1. The plasma is fully ionized, only consisting of ions and electrons.
   Neutral atoms are neglected.
2. Turbulent transport does not dominate
3. The velocity distribution is close to Maxwellian. This implies:
    i. Collisional mean free path << gradient scale length along field
    ii. Gyroradius << gradient scale length perpendicular to field
4. The plasma is highly collisional: collisional frequency >> gyrofrequency

When classical transport is not valid, e.g. due to the presence of strong
gradients or turbulent transport, the transport is significantly increased
by these other effects. Thus classical transport often serves as a lower
bound on the losses / transport encountered in a plasma.

Using the module and available variables
========================================
Given that many of the transport variables share a lot of the same computation
and many are often needed to be calculated simultaneously, this module provides
a `ClassicalTransport` class that can be initialized once with all of the
variables necessary for calculation. It then provides all of the functionality
as methods (please refer to its documentation).

If you only wish to calculate a single transport variable (or if just don't
like object oriented interfaces), we have also provided function based wrappers
that use `ClassicalTransport` under the hood. For documentation on the wrappers
themselves and for some explanation of each of the variables, see:

* `resistivity`
* `thermoelectric_conductivity`
* `ion_thermal_conductivity`
* `electron_thermal_conductivity`
* `ion_viscosity`
* `electron_viscosity`

.. warning::

    Please note that as PlasmaPy is a very new package, this API should not be
    considered stable yet.

Classical transport models
==========================
In this section, we present a broad overview of classical transport models
implemented within this module.

Braginskii [1]_
---------------

The original Braginskii treatment as presented in the highly cited review
paper from 1965. Coefficients are found from expansion of the kinetic
equation in Laguerre polynomials, truncated at the second term in their
series expansion (k = 2). This theory allows for arbitrary Hall parameter
and include results for Z = 1, 2, 3, 4, and infinity (the case of Lorentz
gas completely stripped of electrons, and the stationary ion approximation).

Spitzer-Harm [2]_ [3]_
----------------------

These coefficients were obtained from a numerical solution of the Fokker-
Planck equation. They give one of the earliest and most accurate (in the
Fokker-Planck sense) results for electron transport in simple plasma. They
principally apply in the unmagnetized / parallel field case, although for
resistivity Spitzer also calculated a famous result for a strong
perpendicular magnetic field. Results are for Z = 1, 2, 4, 16,
and infinity (Lorentz gas / stationary ion approximation).

Epperlein-Haines [4]_
---------------------

Not yet implemented.

Ji-Held [5]_
------------

This is a modern treatment of the classical transport problem that has been
carried out with laudable care. It allows for arbitrary hall parameter and
arbitrary Z for all coefficients. Similar to the Epperlein-Haines model,
it corrects some known inaccuracies in the original Braginskii results,
notably the asymptotic behavior of alpha-cross and beta_perp as Hall ->
+infinity. It also studies effects of electron collisions in the ion
terms, which all other treatments have not. To neglect electron-electron
collisions, leave mu = 0. To consider them, specify mu and theta.

References
==========
.. [1] <NAME>. "Transport processes in a plasma." Reviews of
       plasma physics 1 (1965): 205. (1965)
.. [2] <NAME>, Lyman, and <NAME>. "Transport phenomena in a
       completely ionized gas." Physical Review 89.5 (1953): 977. (1953)
.. [3] Physics of Fully Ionized Gases, L. Spitzer (1962)
.. [4] <NAME>., and <NAME>. "Plasma transport coefficients
       in a magnetic field by direct numerical solution of the
       Fokker–Planck equation." The Physics of fluids 29.4 (1986):
       1029-1041.
.. [5] <NAME>, and <NAME>. "Closure and transport theory for
       high-collisionality electron-ion plasmas." Physics of Plasmas 20.4
       (2013): 042114.
"""
import warnings

import numpy as np
from astropy import units as u

from plasmapy import utils
from plasmapy import atomic
from plasmapy.atomic.atomic import _is_electron
from .collisions import Coulomb_logarithm
from plasmapy.physics.parameters import (Hall_parameter,
                                         _grab_charge)
from plasmapy.physics.transport.collisions import (fundamental_electron_collision_freq,
                                                   fundamental_ion_collision_freq)
from plasmapy.constants import e, m_e, k_B

__all__ = [
    "ClassicalTransport",
    "resistivity",
    "thermoelectric_conductivity",
    "ion_thermal_conductivity",
    "electron_thermal_conductivity",
    "ion_viscosity",
    "electron_viscosity",
]

class ClassicalTransport:
    r"""
    Classical transport coefficients (e.g. Braginskii, 1965).

    Notes
    -----
    Given that many of the transport variables share a lot of the same
    computation and many are often needed to be calculated simultaneously, this
    class can be initialized once with all of the variables necessary for
    calculation. It then provides all of the functionality as methods (please
    refer to their documentation).

    Parameters
    ----------
    T_e : ~astropy.units.Quantity
        Electron temperature in units of temperature or energy per particle

    n_e : ~astropy.units.Quantity
        The electron number density in units convertible to per cubic meter.

    T_i : ~astropy.units.Quantity
        Ion temperature in units of temperature or energy per particle

    n_i : ~astropy.units.Quantity
        The ion number density in units convertible to per cubic meter.

    ion_particle : string
        Representation of the ion species (e.g., 'p' for protons,
        'e' for electrons, 'D+' for deuterium, or 'He-4 +1' for singly
        ionized helium-4). If no charge state information is provided,
        then the particles are assumed to be singly charged.
{'fraction_non_alphanumeric': 0.07921228598721435, 'fraction_numerical': 0.01469615695495628, 'mean_word_length': 3.733913043478261, 'pattern_counts': {'":': 0, '<': 28, '<?xml version=': 0, '>': 26, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 8, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1547054', 'n_tokens_mistral': 3718, 'n_tokens_neox': 3362, 'n_words': 1703}