# Getting Started with MomentGauge.Models MomentGauge.Models is a module that provides classes for different types of exponential family distributions that can be used to model rarefied gas dynamics and other applications of the maximal entropy moment method. The module also provides methods for converting between different representations of the distributions, such as natural parameters, moments, and fluid properties. This submodule contains the classes for defining different exponential family models that can be used with MomentGauge. An exponential family model is a probability distribution that has the form $$f(u; \beta, g) = \exp(\sum_{i=0}^M \beta_i \phi_i(u, g))$$ where $\phi_i$ are sufficient statistics, $\beta$ is the natural parameter of the distribution, $\phi_0(u, g) = 1$, and $g$ is extra gauge parameters that may or may not be requested by the moments $\phi_i$. The base class for exponential family model is `BaseExpFamilyModel`, which provides methods for computing the sufficient statistics, the natural parameters, the moments, and the fluid properties of a given model. The subclasses of `BaseExpFamilyModel` are `CanonicalExpFamilyModel` and `GaugedExpFamilyModel`, which implement different ways of sampling from the model using canonical forms and gauge transformations, respectively. The specific models that inherit from these base classes are: - `Maxwellian`: The Maxwellian distribution for one-dimensional flow (1D) with three parameters: density, flow velocity in x direction, and temperature. - `ESBGK`: The Elliptic Statistical (ES) Maxwellian distribution for 1D flow with four parameters, allowing one to set the Prandlt number of the BGK collision model. - `Moment35`: The the 35-moment distribution for one-dimensional flow with 9 parameters. In this guide, we will show you how to use MomentGauge.Models to create and manipulate a Maxwellian distribution for one dimension flow. We will also demonstrate how to compute custom statistics and moments from the distribution. The Maxwell distribution for one dimension flow in the Canonical form is defined as: $$f(\mathbf{u}) = \beta_0 \exp( \phi_0(\mathbf{u}) + \beta_1 \phi_1(\mathbf{u}) + \beta_2 \phi_2(\mathbf{u}) - \log Z )$$ where $\beta_0, \beta_1, \beta_2$ are the natural parameters of the distribution and $$\phi_0(\mathbf{u}) = 1.$$ $$\phi_1(\mathbf{u}) = u_x$$ $$\phi_2(\mathbf{u}) = u_x^2 + u_y^2 + u_z^2.$$ are the sufficient statistics of the distribution. In addition, the partition function $Z$ is defined as $$Z = \int \exp( \beta_1 \phi_1(\mathbf{u}) + \beta_2 \phi_2(\mathbf{u})) d \mathbf{u}, $$ which acts as the normalizer of the distribution. ## Importing the module and setting up constants To use MomentGauge.Models, you need to import the module and its dependencies: ```python import jax.numpy as jnp from MomentGauge.Models.Maxwellian import Maxwell_Canonical_Legendre_1D ``` You also need to prepare a dictionary of constants that will be used as an argument for the distribution class. The dictionary should contain the mass of the particle, the Boltzmann constant, and some parameters for numerical integration and optimization. For example: ```python constant = {"m": 1., "kB": 1.,"n_x": 8, "n_r": 8, "B_x": 16, "B_r": 16 , "alpha" : 1., "beta" : 0.5, "c": 5e-4, "atol": 5e-6, "rtol":1e-5, "max_iter": 100, "max_back_tracking_iter": 25, "tol": 1e-8, "min_step_size": 1e-6, "reg_hessian": True, "debug" : False } ``` Detaied description of the parameters in this dictionary could be found in the API Reference. ## Initializing the distribution class To create a Maxwellian distribution for 1D flow, you need to initialize the `Maxwell_Canonical_Legendre_1D` class with the constant dictionary as an argument. For example: ```python Maxwell = Maxwell_Canonical_Legendre_1D(constant) ``` This will create an instance of the class that can be used to perform various operations on the distribution. ## Specifying the domain and the natural parameters To work with the distribution, you need to specify the sample domain and the natural parameters of the distribution. For Maxwell_Canonical_Legendre_1D, the sample domain is a tuple of three numbers that define the lower and upper bounds of the velocity space in x-direction and the radius of the polar coordinate system. For example: ```python domain_para = jnp.array([-15,15,15]) ``` The natural parameters are a tuple of three numbers that directly determine the distribution. They are related to the density, velocity, and temperature of the gas by analytical formulas. For example: ```python rhoVT = jnp.array([1,0,3]) beta = Maxwell.rhoVT_to_natural_paras(rhoVT,domain_para) ``` This will convert the physical quantities (rho, v, T) to the natural parameters (beta_0, beta_1, beta_2). ## Converting between different representations The distribution class provides methods for converting between different representations of the distribution, such as natrual parameters and moments of sufficient statistics. ### Moments The moments are a tuple of three numbers that represent the integrals of the sufficient statistics ($\phi_0, \phi_1, \phi_2$) over the sample domain and are defined as: $$M_i = \int \phi_i(\mathbf{u}) f(\mathbf{u}) d \mathbf{u}, $$ They are related to the natural parameters ($\beta_0, \beta_1, \beta_2$). For example: ```python moments = Maxwell.natural_paras_to_moments(beta, domain_para ) ``` This will convert the natural parameters ($\beta_0, \beta_1, \beta_2$) to the moments $M_i$ of the sufficient statistics ( $\phi_0, \phi_1, \phi_2$ ). Conversely, you can also convert moments to natural parameters by numerical optimization. For example: ```python beta_ini = beta*0.9 beta_opt, opt_info = Maxwell.moments_to_natural_paras(beta_ini, moments, domain_para ) ``` This will use an initial guess `beta_ini` and optimize the natural parameters to match the given moments. ## Fluid properties The fluid properties are a tuple of sixteen numbers that represent various physical quantities of the gas derived from the distribution function. They include density, velocity components in x-, y-, and z-directions; temperature; pressure; stress components in xx-, xy-, xz-, yy-, yz-, and zz-directions; and heat flux components in x-, y-, and z-directions. They are related to the natural parameters by analytical formulas. For example: ```python fp = Maxwell.natural_paras_to_fluid_properties(beta,domain_para) rho, n, v_x, v_y, v_z, T, p, sigma_xx, sigma_xy, sigma_xz, sigma_yy, sigma_yz, sigma_zz, q_x, q_y, q_z = fp ``` This will convert the natural parameters ($\beta_0, \beta_1, \beta_2$) to the fluid properties (rho, v_x, T, etc.). ## Custom statistics The custom statistics are user-defined functions of the velocity vector that can be used to compute additional quantities of interest from the distribution function. They are related to the natural parameters by numerical integration. For example: ```python # define a custom statistics function u_x, u_x**2, whose moments are to be computed from the natural parameters (beta_0, beta_1, beta_2). custom_statistics = lambda u: jnp.array([u[0], u[0]**2]) # Convert the natural parameters (beta_0, beta_1, beta_2) to the moments of the custom statistics. custom_statistics_moments = Maxwell.natural_paras_to_custom_moments(beta, domain_para, custom_statistics, stats_gauge_paras=() ) ``` This will compute the moments of the custom statistics function $u_x$, $u_x^2$ simutaneously over the sample domain. ## Summary In this guide, we have shown you how to use MomentGauge.Models to create and manipulate a Maxwellian distribution in one dimension. We have also demonstrated how to convert between different representations of the distribution, such as natural parameters, moments, fluid properties, and custom statistics. You can use similar methods for other distribution classes in the module, such as `Moment35_Canonical_Legendre_1D`, which implement higher-order moment closures for rarefied gas dynamics. For more details and examples, please refer to the documentation and source code of MomentGauge.Models.