pylbo.gimli =========== .. py:module:: pylbo.gimli Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/pylbo/gimli/_version/index /autoapi/pylbo/gimli/amrvac/index /autoapi/pylbo/gimli/equilibrium/index /autoapi/pylbo/gimli/legolas/index /autoapi/pylbo/gimli/utils/index Classes ------- .. autoapisummary:: pylbo.gimli.Variables pylbo.gimli.Equilibrium pylbo.gimli.NumericalEquilibrium pylbo.gimli.Legolas pylbo.gimli.Amrvac Package Contents ---------------- .. py:class:: Variables Defines a set of variables and constants to be used in defining an Equilibrium object. .. attribute:: x, y, z Coordinates. :type: sympy symbols .. attribute:: rho0, T0, B0sq Density, temperature, and magnetic field squared for use in expressions depending on these quantities. :type: sympy symbols .. attribute:: k2, k3 Wavenumbers. :type: sympy symbols .. attribute:: gamma Adiabatic index. :type: sympy symbol .. attribute:: rhoc, Tc, B2c, B3c, v2c, v3c, pc Constants typically used for amplitudes or uniform terms in their corresponding equilibrium quantities. The corresponding Legolas variable names are cte_rho0, cte_T0, cte_B02, cte_B03, cte_v02, cte_v03, and cte_p0. :type: sympy symbols .. attribute:: p1, p2, p3, p4, p5, p6, p7, p8 Additional free-use constants. :type: sympy symbols .. attribute:: alpha, beta, delta, theta, tau, lam, nu Additional free-use constants. (Note that 'lam' is used instead of 'lambda' to avoid conflict with the reserved keyword. The corresponding Legolas variable name is 'lambda'.) :type: sympy symbols .. attribute:: r0, rc, rj, Bth0, Bz0, V, j0, g Additional constants, originally used in cylindrical coordinates. :type: sympy symbols .. attribute:: fkey Dictionary translating LaTeX notation to Legolas variable names. :type: dict .. rubric:: Examples >>> from pylbo.gimli import Variables >>> var = Variables() .. !! processed by numpydoc !! .. py:attribute:: gamma .. py:attribute:: fkey .. py:class:: Equilibrium(var, rho0, v02, v03, T0, B02=None, B03=None, resistivity=None, gravity=None, condpara=None, condperp=None, cooling=None, heating=None, legolas_grid_spacing=None, heatcool=None) Class containing all equilibrium expressions and initialisation functions. This object is a required argument when generating user files with the Legolas and Amrvac classes. :param var: The Variables object containing the symbols to be used in the equilibrium expressions. :type var: :class:`Variables` :param rho0: The equilibrium density expression. :type rho0: sympy expression :param v02: The equilibrium velocity expressions. :type v02: sympy expressions :param v03: The equilibrium velocity expressions. :type v03: sympy expressions :param T0: The equilibrium temperature expression. :type T0: sympy expression :param B02: The equilibrium magnetic field expressions. :type B02: sympy expressions :param B03: The equilibrium magnetic field expressions. :type B03: sympy expressions :param resistivity: The resistivity expression. :type resistivity: sympy expression :param gravity: The gravitational acceleration. :type gravity: constant :param condpara: The parallel conduction prescription. :type condpara: sympy expression :param condperp: The perpendicular conduction prescription. :type condperp: sympy expression :param cooling: The cooling prescription. :type cooling: sympy expression :param heating: The heating prescription. :type heating: sympy expression :param heatcool: Parameters for cooling and heating, including 'force_thermal_balance'. :type heatcool: dict .. attribute:: variables Variables object from which all expressions are constructed. :type: Variables object .. attribute:: rho0 The equilibrium density expression. :type: sympy expression .. attribute:: v02, v03 The equilibrium velocity expressions. :type: sympy expressions .. attribute:: T0 The equilibrium temperature expression. :type: sympy expression .. attribute:: B02, B03 The equilibrium magnetic field expressions. :type: sympy expressions .. rubric:: Examples The example below defines a homogeneous hydrodynamic equilibrium with constant density and temperature. Their values can be set later when passing this equilibrium to the Legolas or Amrvac class along with a dictionary. >>> from pylbo.gimli import Equilibrium, Variables >>> var = Variables() >>> eq = Equilibrium(var, rho0=var.rhoc, v02=0, v03=0, T0=var.Tc) .. !! processed by numpydoc !! .. py:attribute:: variables .. py:attribute:: rho0 .. py:attribute:: T0 .. py:attribute:: heatcool :value: None .. py:attribute:: grid_spacing .. py:attribute:: _dict_phys .. py:method:: _validate_equil() .. py:method:: get_physics() Returns a dictionary containing the physics expressions and the dependencies to check for. .. !! processed by numpydoc !! .. py:method:: get_dependencies() Checks for dependencies on other equilibrium quantities. Returns a dictionary with the replacement expressions for use in Fortran files. .. !! processed by numpydoc !! .. py:method:: get_current(geometry, dim=3) Determines the current density of the equilibrium magnetic field. :param geometry: Either 'Cartesian' or 'cylindrical'. :type geometry: str :param dim: Dimension of the desired setup (currently 2 or 3). :type dim: int .. !! processed by numpydoc !! .. py:method:: add_current(geometry, dim=3) Adds the current density of the equilibrium magnetic field to the Equilibrium object as attributes J02 and J03. :param geometry: Either 'Cartesian' or 'cylindrical'. :type geometry: str :param dim: Dimension of the desired setup (currently 2 or 3). :type dim: int .. !! processed by numpydoc !! .. py:method:: Bfield_forcefree(geometry, dim=3) Determines whether the equilibrium magnetic field is force-free. :param geometry: Either 'Cartesian' or 'cylindrical'. :type geometry: str :param dim: Dimension of the desired setup (currently 2 or 3). :type dim: int .. !! processed by numpydoc !! .. py:class:: NumericalEquilibrium(arrays) Class to convert numerical arrays to a Legolas-readable format. :param arrays: A dictionary linking key/header to a numerical array. Must contain "rho0" and "T0" and one of ("u1", "x", "r"). Optional arrays are "v01", "v02", "v03", "B01", "B02", "B03", and "grav". :type arrays: dict .. attribute:: arrays Dictionary with specified arrays. :type: dict .. rubric:: Examples The example below defines a homogeneous hydrodynamic equilibrium with constant density and temperature. >>> import numpy as np >>> from pylbo.gimli import NumericalEquilibrium >>> dictionary = { >>> "x" : np.linspace(0, 1, 100), >>> "rho0": 2 * np.ones(100), >>> "T0" : 0.5 * np.ones(100) >>> } >>> equil = NumericalEquilibrium(dictionary) >>> equil.to_legolas_arrays(filename="homogeneous") .. !! processed by numpydoc !! .. py:attribute:: arrays .. py:method:: _validate() .. py:method:: to_legolas_arrays(filename='arrays', loc='./') Prepares a numerical arrays file (.lar) for use with Legolas. :param filename: Name of the .lar file. Default is 'arrays'. :type filename: str, optional :param loc: The location to save the .lar file. Default is the current directory. :type loc: str, optional .. !! processed by numpydoc !! .. py:class:: Legolas(equilibrium, config) Class for generating user-defined Legolas modules and parfiles. :param equilibrium: The equilibrium object containing the user-defined equilibrium and physics functions. :type equilibrium: Equilibrium :param config: A dictionary containing the configuration for the Legolas run (both equilibrium parameter values and technical settings). :type config: dict .. !! processed by numpydoc !! .. py:attribute:: equilibrium .. py:attribute:: config .. py:method:: _validate_config() Validates the validity of the configuration dictionary. :raises KeyError: If the configuration dictionary is missing the `physics_type` key. :raises ValueError: If `physics_type` is not "hd" or "mhd". .. !! processed by numpydoc !! .. py:method:: _compare_heatcool() Compares the presence of 'heatcool' in the equilibrium with the radiative cooling settings in the config. 'heatcool' overrides config settings, but if 'heatcool' is not present, config settings are added to the equilibrium. .. !! processed by numpydoc !! .. py:method:: _check_resistivity() Makes sure that resistivity is enabled if needed. .. !! processed by numpydoc !! .. py:method:: user_module(filename='smod_user_defined', loc=None) Writes the user module for the Legolas run. :param filename: The name of the user module file. :type filename: str :param loc: Path to the directory where the user module will be stored. Default is the current directory. :type loc: str, ~os.PathLike .. rubric:: Examples The example below defines a homogeneous hydrodynamic equilibrium with constant density and temperature. The values of the equilibrium parameters are set in the configuration dictionary. >>> from pylbo.gimli import Variables, Equilibrium, Legolas >>> var = Variables() >>> eq = Equilibrium(var, rho0=var.rhoc, v02=0, v03=0, T0=var.Tc) >>> config = { >>> "geometry": "Cartesian", >>> "x_start": 0, >>> "x_end": 1, >>> "gridpoints": 51, >>> "parameters": { >>> "k2": 0.5, >>> "k3": 0, >>> "cte_rho0": 1, >>> "cte_T0": 1 >>> }, >>> "equilibrium_type": "user_defined", >>> "boundary_type": "wall_weak", >>> "physics_type": "mhd" >>> } >>> legolas = Legolas(eq, config) >>> legolas.user_module() .. !! processed by numpydoc !! .. py:method:: parfile(filename='legolas_config', loc=None) Writes the parameter file for the Legolas run. :param filename: The name of the parameter file. :type filename: str :param make_dir: If `True`, creates a directory for the parameter file. :type make_dir: bool :returns: **parfiles** -- A list containing the paths to the parameter files. :rtype: list .. rubric:: Examples The example below defines a homogeneous hydrodynamic equilibrium with constant density and temperature. The values of the equilibrium parameters are set in the configuration dictionary and written to the parameter file. >>> from pylbo.gimli import Variables, Equilibrium, Legolas >>> var = Variables() >>> eq = Equilibrium(var, rho0=var.rhoc, v02=0, v03=0, T0=var.Tc) >>> config = { >>> "geometry": "Cartesian", >>> "x_start": 0, >>> "x_end": 1, >>> "gridpoints": 51, >>> "parameters": { >>> "k2": 0.5, >>> "k3": 0, >>> "cte_rho0": 1, >>> "cte_T0": 1 >>> }, >>> "equilibrium_type": "user_defined", >>> "boundary_type": "wall_weak", >>> "physics_type": "mhd" >>> } >>> legolas = Legolas(eq, config) >>> legolas.parfile() .. !! processed by numpydoc !! .. py:class:: Amrvac(config) Class to prepare Legolas data for use in MPI-AMRVAC (https://amrvac.org). :param config: The configuration dictionary detailing everything needed for the desired functionalities. :type config: dict .. !! processed by numpydoc !! .. py:attribute:: config .. py:method:: _validate_config() Validates the presence and value of `physics_type` in the configuration dictionary. :raises KeyError: If `physics_type` is missing. :raises ValueError: If `physics_type` is invalid. .. !! processed by numpydoc !! .. py:method:: _validate_datfile() Validates whether a valid Legolas data file was specified in the configuration. Further checks whether all necessary parameters are present in the configuration to prepare Legolas data for use with MPI-AMRVAC. :raises AssertionError: If the length of `weights` is not equal to the number of eigenvalues or if the elements of the weights do not add up to 1; if `ef_factor` does not have modulus 1; if `norm_range` does not have length 2; if `norm_range`'s first element is larger than the second. :raises KeyError: If no datfile is specified; if no initial guess for the eigenvalue is specified. :raises TypeError: If `ev_guess` is not a single float/complex number or a list/NumPy array of float/complex numbers; if `weights` is not a list or NumPy array; if `ef_factor` is not a list with length equal to the number of eigenvalues, or an integer, float, or complex number; if `quantity` is not a string; if `percentage` is not a float; if `norm_range` is not a NumPy array. :raises ValueError: If `quantity` is not in the list of equilibrium quantities. :raises Exception: If the datfile is invalid. .. !! processed by numpydoc !! .. py:method:: _validate_config_for_mod_usr() Validates whether the configuration dictionary contains all the arguments to generate a mod_usr.t file for use with MPI-AMRVAC. .. !! processed by numpydoc !! .. py:method:: _validate_simulation_dict() .. py:method:: _get_combined_perturbation(ef, clean=True) Takes Legolas's perturbations of different eigenvalues and adds them up to a single perturbation. :param ef: The eigenfunction to combine. :type ef: str :returns: The combined perturbation. :rtype: np.ndarray .. !! processed by numpydoc !! .. py:method:: _get_total_perturbation(ef_type, clean=True) Combines the perturbations of different eigenvalues into a single perturbation. Derives the pressure perturbation from the density and temperature perturbations. :param ef_type: The eigenfunction to calculate. :type ef_type: str :returns: The total perturbation. :rtype: np.ndarray .. !! processed by numpydoc !! .. py:method:: _integrate_energy_term(array, order) .. py:method:: _get_ef_normalisation(clean=True) Normalises the perturbation of the specified quantity by the maximum background value. :returns: The normalisation factor. :rtype: float .. !! processed by numpydoc !! .. py:method:: _get_energy_normalisation(clean=True) Normalises the perturbation eigenfunctions by the energy. :returns: The normalisation factor. :rtype: float .. !! processed by numpydoc !! .. py:method:: _get_normalisation(clean=True) Selects which procedure to follow for the normalisation. :returns: The normalisation factor. :rtype: float .. !! processed by numpydoc !! .. py:method:: _check_physical_perturbation(ef_name, pert) .. py:method:: prepare_legolas_data(name=None, loc=None, clean=True) Prepares a file (.ldat) from the Legolas data for use with MPI-AMRVAC. :param name: Name of the .ldat file :type name: str :param loc: Path to the directory where the .ldat file will be stored. Default is the current directory. :type loc: str, ~os.PathLike :raises ValueError: If the datfile is invalid. .. rubric:: Examples >>> from pylbo.gimli import Amrvac >>> amrvac_config = { >>> "datfile": "./datfile.dat", >>> "physics_type": "mhd", >>> "ev_guess": [-0.1, 0.1], >>> "percentage": 0.01, >>> "quantity": "rho0" >>> } >>> amrvac = gimli.Amrvac(amrvac_config) >>> amrvac.prepare_legolas_data() .. !! processed by numpydoc !! .. py:method:: user_module(filename='mod_usr', loc=None) Writes the user module for MPI-AMRVAC. :param filename: Name of the user module file, defaults to mod_usr :type filename: str :param loc: Path to the directory where the user module will be stored. Default is the current directory. :type loc: str, ~os.PathLike .. !! processed by numpydoc !! .. py:method:: parfile(basename='amrvac_config', loc=None, subdir=True, prefix_numbers=False, nb_prefix_digits=4) Generates parfiles based on the `parfile` dictionary. The separate namelists do not have to be taken into account, and a normal dictionary should be supplied where the keys correspond to the namelist items that are required. Typechecking is done automatically during parfile generation. :param basename: The basename for the parfile, the `.par` suffix is added automatically and is not needed. If multiple parfiles are generated, these will be prepended by a 4-digit number (e.g. 0003myparfile.par). If not provided, the basename will default to `amrvac_config`. :type basename: str :param output_dir: Output directory where the parfiles are saved, defaults to the current working directory if not specified. A subdirectory called `parfiles` will be created in which the parfiles will be saved. :type output_dir: str, ~os.PathLike :param subdir: If `True` (default), creates a subdirectory `parfiles` in the output folder. :type subdir: boolean :param prefix_numbers: If `True` prepends the `basename` by a n-digit number (e.g. xxxxmyparfile.par). The number of digits is specified by `nb_prefix_digits`. :type prefix_numbers: boolean :param nb_prefix_digits: Number of digits to prepend to the `basename` if `prefix_numbers` is `True`. Defaults to 4. :type nb_prefix_digits: int :returns: **parfiles** -- A list with the paths to the parfiles that were generated. :rtype: list .. !! processed by numpydoc !!