Mondaic

salvus.material.elastic.hexagonal

salvus.material.elastic.hexagonal salvus material elastic hexagonal

Hexagonal (VTI) anisotropic elastic materials.

Classes

EngineeringConstants

class EngineeringConstants(salvus.material.elastic.hexagonal._Hexagonal):
    def __init__(
        self,
        RHO: _pd.types.ParameterOrConstantT,
        E1: _pd.types.ParameterOrConstantT,
        E3: _pd.types.ParameterOrConstantT,
        G13: _pd.types.ParameterOrConstantT,
        V12: _pd.types.ParameterOrConstantT,
        V13: _pd.types.ParameterOrConstantT,
    ) -> None: ...

An hexagonal material parametrized with engineering constants.

An hexagonal material has two planes of symmetry and therefore 6 independent parameters plus the density.

The shear moduli here are assumed to be in the engineering convention: twice the normal shear moduli.

The following equalities hold compared to the full orthotropic case:

  • E2 = E1
  • V32 = V31
  • V23 = V13
  • V31 / E3 = V13 / E1
  • V21 = V12
  • G21 = E2 / (2 * (1 + V21))

The normal and reverse Poisson’s ratios are also named the major and minor Poisson’s ratio, depending on which has the larger magnitude. However, this material always defines it by first and second axes, i.e. v12 and v13.

This material is rotationally symmetric around its vertical, the dimensions described in these constants by the index 3. This means that:

  • the Young’s modulus in the 1 and 2 dimensions are equal.
  • The two Poisson’s ratio between the third and the two other dimensions are equal, as are their reverse Poisson’s ratio.
  • The Poisson’s ratio between dimension 1 and dimension 2 is the same as its reverse.
Parameters
  • RHO _pd.types.ParameterOrConstantT — The density in kg / m^3.
  • E1 _pd.types.ParameterOrConstantT — Young’s modulus in Pa.
  • E3 _pd.types.ParameterOrConstantT — Young’s modulus in Pa.
  • G13 _pd.types.ParameterOrConstantT — Shear modulus in Pa, engineering convention.
  • V12 _pd.types.ParameterOrConstantT — Poisson’s ratio.
  • V13 _pd.types.ParameterOrConstantT — Poisson’s ratio.
Attributes
ds typing.Mapping

Material’s xarray representation.

flatten dict

Get all parameters as a dict.

viscosity Material | None

Get the optional attenuation.

Methods
from_dataset()
def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...

Construct a material from an xarray Dataset.

Parameters
  • ds xr.Dataset — The dataset to construct the material from.
Returns Material[_pd.types.ParameterFlavorT]
from_json()
def from_json(d: builtins.dict) -> Any: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • d builtins.dict — Dictionary containing its init parameters and a few other things.
Returns Any
from_material()
def from_material(
    m: Material,
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> _Hexagonal: ...

Construct this material from another within the same physical system.

Parameters
  • m Material — Material to transform.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns _Hexagonal — The transformed material.
from_params()
def from_params(
    rho: _pd.types.ParameterInput,
    e1: _pd.types.ParameterInput,
    e3: _pd.types.ParameterInput,
    g13: _pd.types.ParameterInput,
    v12: _pd.types.ParameterInput,
    v13: _pd.types.ParameterInput,
) -> typing.Self: ...

Construct an hexagonal material from its engineering constants.

The shear moduli here are assumed to be in the engineering convention: twice the normal shear moduli.

Parameters
  • rho _pd.types.ParameterInput — The density in kg / m^3.
  • e1 _pd.types.ParameterInput — Young’s modulus in Pa.
  • e3 _pd.types.ParameterInput — Young’s modulus in Pa.
  • g13 _pd.types.ParameterInput — Shear modulus in Pa, engineering convention.
  • v12 _pd.types.ParameterInput — Poisson’s ratio.
  • v13 _pd.types.ParameterInput — Poisson’s ratio.
Returns typing.Self
from_tensor_components()
def from_tensor_components(
    m: GenericTensorComponents[_pd.types.ParameterFlavorT],
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> typing.Self: ...

Create material from tensor components acoustic parameter material.

Overwrite this method if your material can not be constructed from acoustic constants.

A class method to create a anisotropic material of a desired symmetry class from a canonical TC material. The method will automatically check if the canonical material that is passed meets the symmetry requirements of the desired materials. If it does not, a TypeError will be raised.

Parameters
  • m GenericTensorComponents[_pd.types.ParameterFlavorT] — The material in tensor components parametrization to be used to construct the new material.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns typing.Self
material_system()
def material_system() -> type[PhysicalMaterial]: ...

Get the material system of the material.

Returns type[PhysicalMaterial]
map()
def map(
    self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> typing.Self: ...

Generic map for dataclass instances.

f should be a function taking two parameters: the name of the dataclass member and its value, and it should return a tuple containing the same quantities. If a member is not to be transformed, f should just return a tuple of the input member name and value, unchanged. Both names and values can be transformed, with the semantics following those of dataclasses.replace.

In Salvus we primarily treat dataclasses as containers offering semantics similar to typed dictionaries. Deriving from this protocol allows any relevant dataclass to additionally be treated functorially. This allows for the generic un- and re-wrapping of value held in dataclasses, and essentially replaces the following imperative code:

@dataclass
class A:
    member: int

# Before
my_a = A(member=1)
my_a_new = dataclasses.replace(my_a, member=2 * my_a.member)

# After
my_a_new = A(val=1).map(lambda key, val: (key, 2 * val))

As with many functional patterns, the perceived benefits for simple demonstrative purposes is minimal. The scalability of this pattern becomes apparent, however, when parsing deeply nested abstractions, as the transformation logic can be factored out into independent functions. This is used extensively, for example, in the realization logic of the layered mesher, where generic materials can have generic parameters, etc.

Parameters
  • f typing.Callable[[str, typing.Any], tuple[str, typing.Any]] — The function to map over the dataclass.
Returns typing.Self — A new, potentially transformed, dataclass.
map_realized_parameters()
def map_realized_parameters(
    self,
    f_constant: typing.Callable[
        [str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_discrete: typing.Callable[
        [str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_analytic: typing.Callable[
        [str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter
    ] = salvus.material.base_materials._map_realized_default,
) -> Self: ...

Apply functions to each parameter individually, distinguishing _pd.

Useful when one wants to transform each parameter type separately. For instance, transformations of discrete parameters often require more associated logic than their constant equivalents. This function abstracts away the boilerplate of check for each parameter type, and subsequently transforming it with some function, as well as ensuring that the parameters are indeed of the correct realized type.

The signatures of each transformation function should take the parameter’s name and value as two distinct inputs, and return the (potentially modified) parameter value.

Parameters
  • f_constant typing.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] — The function to apply to constant parameters. Defaults to returning the parameter as-is.
  • f_discrete typing.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] — The function to apply to discrete parameters. Defaults to returning the parameter as-is.
  • f_analytic typing.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] — The function to apply to analytic parameters. Defaults to returning the parameter as-is.
Returns Self
qc_test()
def qc_test(
    self,
    level: validation.QCLevel | str = QCLevel.strict,
    display_issues: bool = True,
) -> dict[str, MaterialQCIssue]: ...

Run a series of material quality control tests.

The function also prints a summary of the issues found, including their severity and any mitigation steps that can be taken.

Parameters
  • level validation.QCLevel | str — The level of quality control to perform. The BASIC level performs minimal checks, while the STRICT level performs more thorough checks that are potentially slow. One can pass an enumeration value or a string representation of the level.
  • display_issues bool — If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
Returns dict[str, MaterialQCIssue] — A dictionary of MaterialQCIssue objects representing the issues found during the quality control checks. The keys are formatted as “type:code”, where type is the type of the issue (e.g, “mesh” or “material”) and code is a specific code for the issue (e.g., “NON_POSITIVE_VP”). If no issues are found, an empty dictionary is returned.
to_json()
def to_json(
    self,
    external_file_hash: types = None,
    timer: types = None,
    log_to_logger: bool = False,
    comm: types = None,
) -> builtins.dict: ...

Serialize the object to a dictionary that can be written to JSON.

Parameters
  • external_file_hash types — Hash of any external files associated with this object. Can be passed here in which case it will be stored in a centralized location in the JSON file.
  • timer types — Execution timer.
  • log_to_logger bool — Log timings to the logger.
  • comm types — MPI communicator, if any.
Returns builtins.dict
to_tensor_components()
def to_tensor_components(
    self, expand_symmetries: bool = False
) -> MaterialDict | GenericTensorComponents: ...

Generate a tensor component representation of the material.

This method ensures compatibility with solver and other symmetries.

Parameters
  • expand_symmetries bool — boolean determining if to return a expanded canonical parameters instead of the TensorComponents object in the relevant symmetry system. Defaults to False.
Returns MaterialDict | GenericTensorComponents — The material in tensor component form.
to_wavelength_oracle()
def to_wavelength_oracle(
    self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...

The wavelength oracle.

Parameters
  • n_dim typing.Literal[2, 3] | None — Dimension to return the oracle for, deprecated.
Returns _pd.types.ParameterOrConstantT
with_attenuation()
def with_attenuation(self, attenuation: Material | None) -> Self: ...

Add attenuation to an object.

Parameters
  • attenuation Material | None — The attenuation material.
Returns Self — The object with an attenuation material attached.
with_orientation()
def with_orientation(self, orientation: Material | None) -> Material: ...

Experimental way to add orientation to a material.

Parameters
  • orientation Material | None — The orientation.
Returns Material — The object with an orientation material attached.

TensorComponents

class TensorComponents(
    salvus.material.elastic.hexagonal._Hexagonal,
    salvus.material.elastic.ElasticTensorComponents,
):
    def __init__(
        self,
        RHO: _pd.types.ParameterOrConstantT,
        C11: _pd.types.ParameterOrConstantT,
        C12: _pd.types.ParameterOrConstantT,
        C13: _pd.types.ParameterOrConstantT,
        C33: _pd.types.ParameterOrConstantT,
        C44: _pd.types.ParameterOrConstantT,
    ) -> None: ...

Hexagonal anisotropic elastic material parametrized by elastic constants.

Parameters
  • RHO _pd.types.ParameterOrConstantT — The density in kg / m^3.
  • C11 _pd.types.ParameterOrConstantT — The c_11 component of the stiffness tensor in Pa.
  • C12 _pd.types.ParameterOrConstantT — The c_12 component of the stiffness tensor in Pa.
  • C13 _pd.types.ParameterOrConstantT — The c_13 component of the stiffness tensor in Pa.
  • C33 _pd.types.ParameterOrConstantT — The c_33 component of the stiffness tensor in Pa.
  • C44 _pd.types.ParameterOrConstantT — The c_44 component of the stiffness tensor in Pa.
Attributes
ds typing.Mapping

Material’s xarray representation.

flatten dict

Get all parameters as a dict.

halfC11minC12 _pd.types.ParameterFlavorT

Material property that might be accessed in checking symmetry.

viscosity Material | None

Get the optional attenuation.

Methods
all_components()
def all_components() -> list[str]: ...

Get all components.

Returns list[str]
equal_components()
def equal_components() -> dict[str, str]: ...

Get equal components for a material class.

Returns dict[str, str]
from_dataset()
def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...

Construct a material from an xarray Dataset.

Parameters
  • ds xr.Dataset — The dataset to construct the material from.
Returns Material[_pd.types.ParameterFlavorT]
from_json()
def from_json(d: builtins.dict) -> Any: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • d builtins.dict — Dictionary containing its init parameters and a few other things.
Returns Any
from_material()
def from_material(
    m: Material,
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> _Hexagonal: ...

Construct this material from another within the same physical system.

Parameters
  • m Material — Material to transform.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns _Hexagonal — The transformed material.
from_params()
def from_params(
    rho: _pd.types.ParameterInput,
    c11: _pd.types.ParameterInput,
    c12: _pd.types.ParameterInput,
    c13: _pd.types.ParameterInput,
    c33: _pd.types.ParameterInput,
    c44: _pd.types.ParameterInput,
) -> typing.Self: ...

Construct a hexagonal material from elastic constants.

Parameters
  • rho _pd.types.ParameterInput — The density in kg / m^3.
  • c11 _pd.types.ParameterInput — The c_11 component of the stiffness tensor in Pa.
  • c12 _pd.types.ParameterInput — The c_12 component of the stiffness tensor in Pa.
  • c13 _pd.types.ParameterInput — The c_13 component of the stiffness tensor in Pa.
  • c33 _pd.types.ParameterInput — The c_33 component of the stiffness tensor in Pa.
  • c44 _pd.types.ParameterInput — The c_44 component of the stiffness tensor in Pa.
Returns typing.Self
from_tensor_components()
def from_tensor_components(
    m: GenericTensorComponents[_pd.types.ParameterFlavorT],
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> Self: ...

Create material from tensor components acoustic parameter material.

Overwrite this method if your material can not be constructed from acoustic constants.

A class method to create a anisotropic material of a desired symmetry class from a canonical TC material. The method will automatically check if the canonical material that is passed meets the symmetry requirements of the desired materials. If it does not, a TypeError will be raised.

Parameters
  • m GenericTensorComponents[_pd.types.ParameterFlavorT] — The material in tensor components parametrization to be used to construct the new material.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns Self
material_system()
def material_system() -> type[PhysicalMaterial]: ...

Get the material system of the material.

Returns type[PhysicalMaterial]
nonzero_components()
def nonzero_components() -> list[str]: ...

Get nonzero components for a material class.

Returns list[str]
zero_components()
def zero_components() -> list[str]: ...

Get zero components for a material class.

Returns list[str]
map()
def map(
    self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> typing.Self: ...

Generic map for dataclass instances.

f should be a function taking two parameters: the name of the dataclass member and its value, and it should return a tuple containing the same quantities. If a member is not to be transformed, f should just return a tuple of the input member name and value, unchanged. Both names and values can be transformed, with the semantics following those of dataclasses.replace.

In Salvus we primarily treat dataclasses as containers offering semantics similar to typed dictionaries. Deriving from this protocol allows any relevant dataclass to additionally be treated functorially. This allows for the generic un- and re-wrapping of value held in dataclasses, and essentially replaces the following imperative code:

@dataclass
class A:
    member: int

# Before
my_a = A(member=1)
my_a_new = dataclasses.replace(my_a, member=2 * my_a.member)

# After
my_a_new = A(val=1).map(lambda key, val: (key, 2 * val))

As with many functional patterns, the perceived benefits for simple demonstrative purposes is minimal. The scalability of this pattern becomes apparent, however, when parsing deeply nested abstractions, as the transformation logic can be factored out into independent functions. This is used extensively, for example, in the realization logic of the layered mesher, where generic materials can have generic parameters, etc.

Parameters
  • f typing.Callable[[str, typing.Any], tuple[str, typing.Any]] — The function to map over the dataclass.
Returns typing.Self — A new, potentially transformed, dataclass.
map_realized_parameters()
def map_realized_parameters(
    self,
    f_constant: typing.Callable[
        [str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_discrete: typing.Callable[
        [str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_analytic: typing.Callable[
        [str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter
    ] = salvus.material.base_materials._map_realized_default,
) -> Self: ...

Apply functions to each parameter individually, distinguishing _pd.

Useful when one wants to transform each parameter type separately. For instance, transformations of discrete parameters often require more associated logic than their constant equivalents. This function abstracts away the boilerplate of check for each parameter type, and subsequently transforming it with some function, as well as ensuring that the parameters are indeed of the correct realized type.

The signatures of each transformation function should take the parameter’s name and value as two distinct inputs, and return the (potentially modified) parameter value.

Parameters
  • f_constant typing.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] — The function to apply to constant parameters. Defaults to returning the parameter as-is.
  • f_discrete typing.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] — The function to apply to discrete parameters. Defaults to returning the parameter as-is.
  • f_analytic typing.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] — The function to apply to analytic parameters. Defaults to returning the parameter as-is.
Returns Self
qc_test()
def qc_test(
    self,
    level: validation.QCLevel | str = QCLevel.strict,
    display_issues: bool = True,
) -> dict[str, MaterialQCIssue]: ...

Run a series of material quality control tests.

The function also prints a summary of the issues found, including their severity and any mitigation steps that can be taken.

Parameters
  • level validation.QCLevel | str — The level of quality control to perform. The BASIC level performs minimal checks, while the STRICT level performs more thorough checks that are potentially slow. One can pass an enumeration value or a string representation of the level.
  • display_issues bool — If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
Returns dict[str, MaterialQCIssue] — A dictionary of MaterialQCIssue objects representing the issues found during the quality control checks. The keys are formatted as “type:code”, where type is the type of the issue (e.g, “mesh” or “material”) and code is a specific code for the issue (e.g., “NON_POSITIVE_VP”). If no issues are found, an empty dictionary is returned.
to_json()
def to_json(
    self,
    external_file_hash: types = None,
    timer: types = None,
    log_to_logger: bool = False,
    comm: types = None,
) -> builtins.dict: ...

Serialize the object to a dictionary that can be written to JSON.

Parameters
  • external_file_hash types — Hash of any external files associated with this object. Can be passed here in which case it will be stored in a centralized location in the JSON file.
  • timer types — Execution timer.
  • log_to_logger bool — Log timings to the logger.
  • comm types — MPI communicator, if any.
Returns builtins.dict
to_tensor_components()
def to_tensor_components(
    self, expand_symmetries: bool = False
) -> MaterialDict | GenericTensorComponents: ...

Generate a tensor component representation of the material.

This method ensures compatibility with solver and other symmetries.

Parameters
  • expand_symmetries bool — boolean determining if to return a expanded canonical parameters instead of the TensorComponents object in the relevant symmetry system. Defaults to False.
Returns MaterialDict | GenericTensorComponents — The material in tensor component form.
to_wavelength_oracle()
def to_wavelength_oracle(
    self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...

The wavelength oracle.

Parameters
  • n_dim typing.Literal[2, 3] | None — Dimension to return the oracle for, deprecated.
Returns _pd.types.ParameterOrConstantT
with_attenuation()
def with_attenuation(self, attenuation: Material | None) -> Self: ...

Add attenuation to an object.

Parameters
  • attenuation Material | None — The attenuation material.
Returns Self — The object with an attenuation material attached.
with_orientation()
def with_orientation(self, orientation: Material | None) -> Material: ...

Experimental way to add orientation to a material.

Parameters
  • orientation Material | None — The orientation.
Returns Material — The object with an orientation material attached.

Thomsen

class Thomsen(salvus.material.elastic.hexagonal._Hexagonal):
    def __init__(
        self,
        RHO: _pd.types.ParameterOrConstantT,
        VP: _pd.types.ParameterOrConstantT,
        VS: _pd.types.ParameterOrConstantT,
        DELTA: _pd.types.ParameterOrConstantT,
        GAMMA: _pd.types.ParameterOrConstantT,
        EPSILON: _pd.types.ParameterOrConstantT,
    ) -> None: ...

Anisotropic elastic materials specified using Thomsen’s parameters, with hexagonal symmetry.

VP and VS are defined along the materials symmetry axis (the vertical).

Parameters
  • RHO _pd.types.ParameterOrConstantT — Density in kg / m^3.
  • VP _pd.types.ParameterOrConstantT — P-wave velocity in m / s along the symmetry axis.
  • VS _pd.types.ParameterOrConstantT — S-wave velocity in m / s along the symmetry axis.
  • DELTA _pd.types.ParameterOrConstantT — Thomsen’s delta parameter (dimensionless).
  • GAMMA _pd.types.ParameterOrConstantT — Thomsen’s gamma parameter (dimensionless).
  • EPSILON _pd.types.ParameterOrConstantT — Thomsen’s epsilon parameter (dimensionless).
Attributes
ds typing.Mapping

Material’s xarray representation.

flatten dict

Get all parameters as a dict.

viscosity Material | None

Get the optional attenuation.

Methods
from_acoustic()
def from_acoustic(
    acoustic_thomsen: AThomsen[_pd.types.ParameterFlavorT],
    vp_vs: _pd.types.ParameterInput,
    gamma: _pd.types.ParameterInput,
    qmu: _pd.types.ParameterInput | None = None,
) -> typing.Self: ...

Create this material from the elastic constants parametrization.

Parameters
  • acoustic_thomsen AThomsen[_pd.types.ParameterFlavorT] — The material to create this material from.
  • vp_vs _pd.types.ParameterInput — Ratio between vp and vs speeds.
  • gamma _pd.types.ParameterInput — the anisotropy parameter for shear wave speed.
  • qmu _pd.types.ParameterInput | None — Qmu.
Returns typing.Self
from_dataset()
def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...

Construct a material from an xarray Dataset.

Parameters
  • ds xr.Dataset — The dataset to construct the material from.
Returns Material[_pd.types.ParameterFlavorT]
from_json()
def from_json(d: builtins.dict) -> Any: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • d builtins.dict — Dictionary containing its init parameters and a few other things.
Returns Any
from_material()
def from_material(
    m: Material,
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> _Hexagonal: ...

Construct this material from another within the same physical system.

Parameters
  • m Material — Material to transform.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns _Hexagonal — The transformed material.
from_params()
def from_params(
    rho: _pd.types.ParameterInput,
    vp: _pd.types.ParameterInput,
    vs: _pd.types.ParameterInput,
    delta: _pd.types.ParameterInput,
    gamma: _pd.types.ParameterInput,
    epsilon: _pd.types.ParameterInput,
) -> typing.Self: ...

Construct this material from generic parameters.

Parameters
  • rho _pd.types.ParameterInput — Density in kg / m^3.
  • vp _pd.types.ParameterInput — P-wave velocity in m / s.
  • vs _pd.types.ParameterInput — S-wave velocity in m / s.
  • delta _pd.types.ParameterInput — Thomsen’s delta parameter (dimensionless).
  • gamma _pd.types.ParameterInput — Thomsen’s gamma parameter (dimensionless).
  • epsilon _pd.types.ParameterInput — Thomsen’s epsilon parameter (dimensionless).
Returns typing.Self — The material.
from_tensor_components()
def from_tensor_components(
    m: GenericTensorComponents[_pd.types.ParameterFlavorT],
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> typing.Self: ...

Create material from tensor components acoustic parameter material.

Overwrite this method if your material can not be constructed from acoustic constants.

A class method to create a anisotropic material of a desired symmetry class from a canonical TC material. The method will automatically check if the canonical material that is passed meets the symmetry requirements of the desired materials. If it does not, a TypeError will be raised.

Parameters
  • m GenericTensorComponents[_pd.types.ParameterFlavorT] — The material in tensor components parametrization to be used to construct the new material.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns typing.Self
material_system()
def material_system() -> type[PhysicalMaterial]: ...

Get the material system of the material.

Returns type[PhysicalMaterial]
map()
def map(
    self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> typing.Self: ...

Generic map for dataclass instances.

f should be a function taking two parameters: the name of the dataclass member and its value, and it should return a tuple containing the same quantities. If a member is not to be transformed, f should just return a tuple of the input member name and value, unchanged. Both names and values can be transformed, with the semantics following those of dataclasses.replace.

In Salvus we primarily treat dataclasses as containers offering semantics similar to typed dictionaries. Deriving from this protocol allows any relevant dataclass to additionally be treated functorially. This allows for the generic un- and re-wrapping of value held in dataclasses, and essentially replaces the following imperative code:

@dataclass
class A:
    member: int

# Before
my_a = A(member=1)
my_a_new = dataclasses.replace(my_a, member=2 * my_a.member)

# After
my_a_new = A(val=1).map(lambda key, val: (key, 2 * val))

As with many functional patterns, the perceived benefits for simple demonstrative purposes is minimal. The scalability of this pattern becomes apparent, however, when parsing deeply nested abstractions, as the transformation logic can be factored out into independent functions. This is used extensively, for example, in the realization logic of the layered mesher, where generic materials can have generic parameters, etc.

Parameters
  • f typing.Callable[[str, typing.Any], tuple[str, typing.Any]] — The function to map over the dataclass.
Returns typing.Self — A new, potentially transformed, dataclass.
map_realized_parameters()
def map_realized_parameters(
    self,
    f_constant: typing.Callable[
        [str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_discrete: typing.Callable[
        [str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_analytic: typing.Callable[
        [str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter
    ] = salvus.material.base_materials._map_realized_default,
) -> Self: ...

Apply functions to each parameter individually, distinguishing _pd.

Useful when one wants to transform each parameter type separately. For instance, transformations of discrete parameters often require more associated logic than their constant equivalents. This function abstracts away the boilerplate of check for each parameter type, and subsequently transforming it with some function, as well as ensuring that the parameters are indeed of the correct realized type.

The signatures of each transformation function should take the parameter’s name and value as two distinct inputs, and return the (potentially modified) parameter value.

Parameters
  • f_constant typing.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] — The function to apply to constant parameters. Defaults to returning the parameter as-is.
  • f_discrete typing.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] — The function to apply to discrete parameters. Defaults to returning the parameter as-is.
  • f_analytic typing.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] — The function to apply to analytic parameters. Defaults to returning the parameter as-is.
Returns Self
qc_test()
def qc_test(
    self,
    level: validation.QCLevel | str = QCLevel.strict,
    display_issues: bool = True,
) -> dict[str, MaterialQCIssue]: ...

Run a series of material quality control tests.

The function also prints a summary of the issues found, including their severity and any mitigation steps that can be taken.

Parameters
  • level validation.QCLevel | str — The level of quality control to perform. The BASIC level performs minimal checks, while the STRICT level performs more thorough checks that are potentially slow. One can pass an enumeration value or a string representation of the level.
  • display_issues bool — If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
Returns dict[str, MaterialQCIssue] — A dictionary of MaterialQCIssue objects representing the issues found during the quality control checks. The keys are formatted as “type:code”, where type is the type of the issue (e.g, “mesh” or “material”) and code is a specific code for the issue (e.g., “NON_POSITIVE_VP”). If no issues are found, an empty dictionary is returned.
to_acoustic()
def to_acoustic(self) -> AThomsen[_pd.types.ParameterFlavorT]: ...

Create acoustic variant of this material from the elastic.

Returns AThomsen[_pd.types.ParameterFlavorT]
to_json()
def to_json(
    self,
    external_file_hash: types = None,
    timer: types = None,
    log_to_logger: bool = False,
    comm: types = None,
) -> builtins.dict: ...

Serialize the object to a dictionary that can be written to JSON.

Parameters
  • external_file_hash types — Hash of any external files associated with this object. Can be passed here in which case it will be stored in a centralized location in the JSON file.
  • timer types — Execution timer.
  • log_to_logger bool — Log timings to the logger.
  • comm types — MPI communicator, if any.
Returns builtins.dict
to_tensor_components()
def to_tensor_components(
    self, expand_symmetries: bool = False
) -> MaterialDict | GenericTensorComponents: ...

Generate a tensor component representation of the material.

This method ensures compatibility with solver and other symmetries.

Parameters
  • expand_symmetries bool — boolean determining if to return a expanded canonical parameters instead of the TensorComponents object in the relevant symmetry system. Defaults to False.
Returns MaterialDict | GenericTensorComponents — The material in tensor component form.
to_wavelength_oracle()
def to_wavelength_oracle(
    self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...

The wavelength oracle.

Parameters
  • n_dim typing.Literal[2, 3] | None — Dimension to return the oracle for, deprecated.
Returns _pd.types.ParameterOrConstantT
with_attenuation()
def with_attenuation(self, attenuation: Material | None) -> Self: ...

Add attenuation to an object.

Parameters
  • attenuation Material | None — The attenuation material.
Returns Self — The object with an attenuation material attached.
with_orientation()
def with_orientation(self, orientation: Material | None) -> Material: ...

Experimental way to add orientation to a material.

Parameters
  • orientation Material | None — The orientation.
Returns Material — The object with an orientation material attached.

Thomsen2D

class Thomsen2D(salvus.material.elastic.hexagonal._Hexagonal):
    def __init__(
        self,
        RHO: _pd.types.ParameterOrConstantT,
        VP: _pd.types.ParameterOrConstantT,
        VS: _pd.types.ParameterOrConstantT,
        DELTA: _pd.types.ParameterOrConstantT,
        EPSILON: _pd.types.ParameterOrConstantT,
    ) -> None: ...

Anisotropic elastic 2D in-plane material specified using Thomsen’s parameters.

Five-parameter set: {RHO, VP, VS, DELTA, EPSILON}. GAMMA — the V_SH/V_SV shear-anisotropy parameter — is dropped because the 2D in-plane elastic system has only one shear mode. The wavefront’s diamond-ness along the symmetry axis is therefore fixed and γ has no degree of freedom to tune.

VP and VS are defined along the material’s symmetry axis (the vertical).

Parameters
  • RHO _pd.types.ParameterOrConstantT — Density in kg / m^3.
  • VP _pd.types.ParameterOrConstantT — P-wave velocity in m / s along the symmetry axis.
  • VS _pd.types.ParameterOrConstantT — S-wave velocity in m / s along the symmetry axis.
  • DELTA _pd.types.ParameterOrConstantT — Thomsen’s delta parameter (dimensionless).
  • EPSILON _pd.types.ParameterOrConstantT — Thomsen’s epsilon parameter (dimensionless).
Attributes
ds typing.Mapping

Material’s xarray representation.

flatten dict

Get all parameters as a dict.

viscosity Material | None

Get the optional attenuation.

Methods
from_dataset()
def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...

Construct a material from an xarray Dataset.

Parameters
  • ds xr.Dataset — The dataset to construct the material from.
Returns Material[_pd.types.ParameterFlavorT]
from_json()
def from_json(d: builtins.dict) -> Any: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • d builtins.dict — Dictionary containing its init parameters and a few other things.
Returns Any
from_material()
def from_material(
    m: Material,
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> _Hexagonal: ...

Construct this material from another within the same physical system.

Parameters
  • m Material — Material to transform.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns _Hexagonal — The transformed material.
from_params()
def from_params(
    rho: _pd.types.ParameterInput,
    vp: _pd.types.ParameterInput,
    vs: _pd.types.ParameterInput,
    delta: _pd.types.ParameterInput,
    epsilon: _pd.types.ParameterInput,
) -> typing.Self: ...

Construct this material from generic parameters.

Parameters
  • rho _pd.types.ParameterInput — Density in kg / m^3.
  • vp _pd.types.ParameterInput — P-wave velocity in m / s.
  • vs _pd.types.ParameterInput — S-wave velocity in m / s.
  • delta _pd.types.ParameterInput — Thomsen’s delta parameter (dimensionless).
  • epsilon _pd.types.ParameterInput — Thomsen’s epsilon parameter (dimensionless).
Returns typing.Self — The material.
from_tensor_components()
def from_tensor_components(
    m: GenericTensorComponents[_pd.types.ParameterFlavorT],
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> typing.Self: ...

Create material from tensor components acoustic parameter material.

Overwrite this method if your material can not be constructed from acoustic constants.

A class method to create a anisotropic material of a desired symmetry class from a canonical TC material. The method will automatically check if the canonical material that is passed meets the symmetry requirements of the desired materials. If it does not, a TypeError will be raised.

Parameters
  • m GenericTensorComponents[_pd.types.ParameterFlavorT] — The material in tensor components parametrization to be used to construct the new material.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns typing.Self
material_system()
def material_system() -> type[PhysicalMaterial]: ...

Get the material system of the material.

Returns type[PhysicalMaterial]
map()
def map(
    self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> typing.Self: ...

Generic map for dataclass instances.

f should be a function taking two parameters: the name of the dataclass member and its value, and it should return a tuple containing the same quantities. If a member is not to be transformed, f should just return a tuple of the input member name and value, unchanged. Both names and values can be transformed, with the semantics following those of dataclasses.replace.

In Salvus we primarily treat dataclasses as containers offering semantics similar to typed dictionaries. Deriving from this protocol allows any relevant dataclass to additionally be treated functorially. This allows for the generic un- and re-wrapping of value held in dataclasses, and essentially replaces the following imperative code:

@dataclass
class A:
    member: int

# Before
my_a = A(member=1)
my_a_new = dataclasses.replace(my_a, member=2 * my_a.member)

# After
my_a_new = A(val=1).map(lambda key, val: (key, 2 * val))

As with many functional patterns, the perceived benefits for simple demonstrative purposes is minimal. The scalability of this pattern becomes apparent, however, when parsing deeply nested abstractions, as the transformation logic can be factored out into independent functions. This is used extensively, for example, in the realization logic of the layered mesher, where generic materials can have generic parameters, etc.

Parameters
  • f typing.Callable[[str, typing.Any], tuple[str, typing.Any]] — The function to map over the dataclass.
Returns typing.Self — A new, potentially transformed, dataclass.
map_realized_parameters()
def map_realized_parameters(
    self,
    f_constant: typing.Callable[
        [str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_discrete: typing.Callable[
        [str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_analytic: typing.Callable[
        [str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter
    ] = salvus.material.base_materials._map_realized_default,
) -> Self: ...

Apply functions to each parameter individually, distinguishing _pd.

Useful when one wants to transform each parameter type separately. For instance, transformations of discrete parameters often require more associated logic than their constant equivalents. This function abstracts away the boilerplate of check for each parameter type, and subsequently transforming it with some function, as well as ensuring that the parameters are indeed of the correct realized type.

The signatures of each transformation function should take the parameter’s name and value as two distinct inputs, and return the (potentially modified) parameter value.

Parameters
  • f_constant typing.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] — The function to apply to constant parameters. Defaults to returning the parameter as-is.
  • f_discrete typing.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] — The function to apply to discrete parameters. Defaults to returning the parameter as-is.
  • f_analytic typing.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] — The function to apply to analytic parameters. Defaults to returning the parameter as-is.
Returns Self
qc_test()
def qc_test(
    self,
    level: validation.QCLevel | str = QCLevel.strict,
    display_issues: bool = True,
) -> dict[str, MaterialQCIssue]: ...

Run a series of material quality control tests.

The function also prints a summary of the issues found, including their severity and any mitigation steps that can be taken.

Parameters
  • level validation.QCLevel | str — The level of quality control to perform. The BASIC level performs minimal checks, while the STRICT level performs more thorough checks that are potentially slow. One can pass an enumeration value or a string representation of the level.
  • display_issues bool — If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
Returns dict[str, MaterialQCIssue] — A dictionary of MaterialQCIssue objects representing the issues found during the quality control checks. The keys are formatted as “type:code”, where type is the type of the issue (e.g, “mesh” or “material”) and code is a specific code for the issue (e.g., “NON_POSITIVE_VP”). If no issues are found, an empty dictionary is returned.
to_acoustic()
def to_acoustic(self) -> AThomsen[_pd.types.ParameterFlavorT]: ...

Create acoustic variant of this material from the elastic.

Returns AThomsen[_pd.types.ParameterFlavorT]
to_json()
def to_json(
    self,
    external_file_hash: types = None,
    timer: types = None,
    log_to_logger: bool = False,
    comm: types = None,
) -> builtins.dict: ...

Serialize the object to a dictionary that can be written to JSON.

Parameters
  • external_file_hash types — Hash of any external files associated with this object. Can be passed here in which case it will be stored in a centralized location in the JSON file.
  • timer types — Execution timer.
  • log_to_logger bool — Log timings to the logger.
  • comm types — MPI communicator, if any.
Returns builtins.dict
to_tensor_components()
def to_tensor_components(
    self, expand_symmetries: bool = False
) -> MaterialDict | GenericTensorComponents: ...

Generate a tensor component representation of the material.

This method ensures compatibility with solver and other symmetries.

Parameters
  • expand_symmetries bool — boolean determining if to return a expanded canonical parameters instead of the TensorComponents object in the relevant symmetry system. Defaults to False.
Returns MaterialDict | GenericTensorComponents — The material in tensor component form.
to_wavelength_oracle()
def to_wavelength_oracle(
    self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...

The wavelength oracle.

Parameters
  • n_dim typing.Literal[2, 3] | None — Dimension to return the oracle for, deprecated.
Returns _pd.types.ParameterOrConstantT
with_attenuation()
def with_attenuation(self, attenuation: Material | None) -> Self: ...

Add attenuation to an object.

Parameters
  • attenuation Material | None — The attenuation material.
Returns Self — The object with an attenuation material attached.
with_orientation()
def with_orientation(self, orientation: Material | None) -> Material: ...

Experimental way to add orientation to a material.

Parameters
  • orientation Material | None — The orientation.
Returns Material — The object with an orientation material attached.

Velocity

class Velocity(salvus.material.elastic.hexagonal._Hexagonal):
    def __init__(
        self,
        RHO: _pd.types.ParameterOrConstantT,
        VPH: _pd.types.ParameterOrConstantT,
        VPV: _pd.types.ParameterOrConstantT,
        VSH: _pd.types.ParameterOrConstantT,
        VSV: _pd.types.ParameterOrConstantT,
        ETA: _pd.types.ParameterOrConstantT,
    ) -> None: ...

Hexagonal anisotropic elastic material parametrized by velocities.

Parameters
  • RHO _pd.types.ParameterOrConstantT — Density in kg / m^3.
  • VPH _pd.types.ParameterOrConstantT — Horizontal P-wave velocity in m / s.
  • VPV _pd.types.ParameterOrConstantT — Vertical P-wave velocity in m / s.
  • VSH _pd.types.ParameterOrConstantT — Horizontal S-wave velocity in m / s.
  • VSV _pd.types.ParameterOrConstantT — Vertical S-wave velocity in m / s.
  • ETA _pd.types.ParameterOrConstantT — Eta.
Attributes
ds typing.Mapping

Material’s xarray representation.

flatten dict

Get all parameters as a dict.

viscosity Material | None

Get the optional attenuation.

Methods
from_dataset()
def from_dataset(ds: xr.Dataset) -> Material[_pd.types.ParameterFlavorT]: ...

Construct a material from an xarray Dataset.

Parameters
  • ds xr.Dataset — The dataset to construct the material from.
Returns Material[_pd.types.ParameterFlavorT]
from_json()
def from_json(d: builtins.dict) -> Any: ...

Recreate the object from a dictionary serialization of its initialization parameters.

Parameters
  • d builtins.dict — Dictionary containing its init parameters and a few other things.
Returns Any
from_material()
def from_material(
    m: Material,
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> _Hexagonal: ...

Construct this material from another within the same physical system.

Parameters
  • m Material — Material to transform.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns _Hexagonal — The transformed material.
from_params()
def from_params(
    rho: _pd.types.ParameterInput,
    vph: _pd.types.ParameterInput,
    vpv: _pd.types.ParameterInput,
    vsh: _pd.types.ParameterInput,
    vsv: _pd.types.ParameterInput,
    eta: _pd.types.ParameterInput,
) -> typing.Self: ...

Construct this material from generic parameters.

Parameters
  • rho _pd.types.ParameterInput — Density in kg / m^3.
  • vph _pd.types.ParameterInput — Horizontal P-wave velocity in m / s.
  • vpv _pd.types.ParameterInput — Vertical P-wave velocity in m / s.
  • vsh _pd.types.ParameterInput — Horizontal S-wave velocity in m / s.
  • vsv _pd.types.ParameterInput — Vertical S-wave velocity in m / s.
  • eta _pd.types.ParameterInput — Eta.
Returns typing.Self — The material.
from_tensor_components()
def from_tensor_components(
    m: GenericTensorComponents[_pd.types.ParameterFlavorT],
    reduction_method: (
        typing.Literal["remove-components", "force"] | None
    ) = None,
) -> typing.Self: ...

Create material from tensor components acoustic parameter material.

Overwrite this method if your material can not be constructed from acoustic constants.

A class method to create a anisotropic material of a desired symmetry class from a canonical TC material. The method will automatically check if the canonical material that is passed meets the symmetry requirements of the desired materials. If it does not, a TypeError will be raised.

Parameters
  • m GenericTensorComponents[_pd.types.ParameterFlavorT] — The material in tensor components parametrization to be used to construct the new material.
  • reduction_method typing.Literal['remove-components', 'force'] | None — Method to move between incompatible symmetry classes. None will only move to symmetries that are equal or more permissive, while remove-components will drop components that are found to match the new material’s constraints as necessary, and thus leading to loss of free parameters but not of information. The option “force” will take all information necessary to construct the new parameter set without verification, leading to loss of information.
Returns typing.Self
material_system()
def material_system() -> type[PhysicalMaterial]: ...

Get the material system of the material.

Returns type[PhysicalMaterial]
map()
def map(
    self, f: typing.Callable[[str, typing.Any], tuple[str, typing.Any]]
) -> typing.Self: ...

Generic map for dataclass instances.

f should be a function taking two parameters: the name of the dataclass member and its value, and it should return a tuple containing the same quantities. If a member is not to be transformed, f should just return a tuple of the input member name and value, unchanged. Both names and values can be transformed, with the semantics following those of dataclasses.replace.

In Salvus we primarily treat dataclasses as containers offering semantics similar to typed dictionaries. Deriving from this protocol allows any relevant dataclass to additionally be treated functorially. This allows for the generic un- and re-wrapping of value held in dataclasses, and essentially replaces the following imperative code:

@dataclass
class A:
    member: int

# Before
my_a = A(member=1)
my_a_new = dataclasses.replace(my_a, member=2 * my_a.member)

# After
my_a_new = A(val=1).map(lambda key, val: (key, 2 * val))

As with many functional patterns, the perceived benefits for simple demonstrative purposes is minimal. The scalability of this pattern becomes apparent, however, when parsing deeply nested abstractions, as the transformation logic can be factored out into independent functions. This is used extensively, for example, in the realization logic of the layered mesher, where generic materials can have generic parameters, etc.

Parameters
  • f typing.Callable[[str, typing.Any], tuple[str, typing.Any]] — The function to map over the dataclass.
Returns typing.Self — A new, potentially transformed, dataclass.
map_realized_parameters()
def map_realized_parameters(
    self,
    f_constant: typing.Callable[
        [str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_discrete: typing.Callable[
        [str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter
    ] = salvus.material.base_materials._map_realized_default,
    f_analytic: typing.Callable[
        [str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter
    ] = salvus.material.base_materials._map_realized_default,
) -> Self: ...

Apply functions to each parameter individually, distinguishing _pd.

Useful when one wants to transform each parameter type separately. For instance, transformations of discrete parameters often require more associated logic than their constant equivalents. This function abstracts away the boilerplate of check for each parameter type, and subsequently transforming it with some function, as well as ensuring that the parameters are indeed of the correct realized type.

The signatures of each transformation function should take the parameter’s name and value as two distinct inputs, and return the (potentially modified) parameter value.

Parameters
  • f_constant typing.Callable[[str, _pd.realized.constant.Parameter], _pd.realized.constant.Parameter] — The function to apply to constant parameters. Defaults to returning the parameter as-is.
  • f_discrete typing.Callable[[str, _pd.realized.discrete.Parameter], _pd.realized.discrete.Parameter] — The function to apply to discrete parameters. Defaults to returning the parameter as-is.
  • f_analytic typing.Callable[[str, _pd.realized.analytic.Parameter], _pd.realized.analytic.Parameter] — The function to apply to analytic parameters. Defaults to returning the parameter as-is.
Returns Self
qc_test()
def qc_test(
    self,
    level: validation.QCLevel | str = QCLevel.strict,
    display_issues: bool = True,
) -> dict[str, MaterialQCIssue]: ...

Run a series of material quality control tests.

The function also prints a summary of the issues found, including their severity and any mitigation steps that can be taken.

Parameters
  • level validation.QCLevel | str — The level of quality control to perform. The BASIC level performs minimal checks, while the STRICT level performs more thorough checks that are potentially slow. One can pass an enumeration value or a string representation of the level.
  • display_issues bool — If True, prints the issues found during the quality control checks. If False, issues are collected but not printed.
Returns dict[str, MaterialQCIssue] — A dictionary of MaterialQCIssue objects representing the issues found during the quality control checks. The keys are formatted as “type:code”, where type is the type of the issue (e.g, “mesh” or “material”) and code is a specific code for the issue (e.g., “NON_POSITIVE_VP”). If no issues are found, an empty dictionary is returned.
to_acoustic()
def to_acoustic(self) -> AVelocity[_pd.types.ParameterFlavorT]: ...

Create acoustic variant of this material.

Returns AVelocity[_pd.types.ParameterFlavorT]
to_json()
def to_json(
    self,
    external_file_hash: types = None,
    timer: types = None,
    log_to_logger: bool = False,
    comm: types = None,
) -> builtins.dict: ...

Serialize the object to a dictionary that can be written to JSON.

Parameters
  • external_file_hash types — Hash of any external files associated with this object. Can be passed here in which case it will be stored in a centralized location in the JSON file.
  • timer types — Execution timer.
  • log_to_logger bool — Log timings to the logger.
  • comm types — MPI communicator, if any.
Returns builtins.dict
to_tensor_components()
def to_tensor_components(
    self, expand_symmetries: bool = False
) -> MaterialDict | GenericTensorComponents: ...

Generate a tensor component representation of the material.

This method ensures compatibility with solver and other symmetries.

Parameters
  • expand_symmetries bool — boolean determining if to return a expanded canonical parameters instead of the TensorComponents object in the relevant symmetry system. Defaults to False.
Returns MaterialDict | GenericTensorComponents — The material in tensor component form.
to_wavelength_oracle()
def to_wavelength_oracle(
    self, n_dim: typing.Literal[2, 3] | None = None
) -> _pd.types.ParameterOrConstantT: ...

The wavelength oracle.

Parameters
  • n_dim typing.Literal[2, 3] | None — Dimension to return the oracle for, deprecated.
Returns _pd.types.ParameterOrConstantT
with_attenuation()
def with_attenuation(self, attenuation: Material | None) -> Self: ...

Add attenuation to an object.

Parameters
  • attenuation Material | None — The attenuation material.
Returns Self — The object with an attenuation material attached.
with_orientation()
def with_orientation(self, orientation: Material | None) -> Material: ...

Experimental way to add orientation to a material.

Parameters
  • orientation Material | None — The orientation.
Returns Material — The object with an orientation material attached.

Used in tutorials