Mondaic
This API reference is not for the latest stable Salvus version.

salvus.mesh.layered_meshing.layered_model.layered_model

Layered interface for SalvusProject.

Functions

fit_to()

def fit_to(
    lm: salvus.mesh.layered_meshing.layered_model.layered_model.LayeredModel,
    top: float,
    bot: float,
) -> salvus.mesh.layered_meshing.layered_model.layered_model.LayeredModel:
    ...

Fit a layered model to bounds, truncating and extending as necessary.

Parameters
  • lm salvus.mesh.layered_meshing.layered_model.layered_model.LayeredModel — The layered model to fit.
  • top float — The highest elevation.
  • bot float — The lowest elevation.
Returns salvus.mesh.layered_meshing.layered_model.layered_model.LayeredModel — A new layered model, fit to the bounds.

Classes

LayeredModel

class LayeredModel(builtins.object):
    def __init__(
        self,
        strata: Union[
            salvus.mesh.layered_meshing.material._material.Material,
            Iterable[
                Union[
                    salvus.mesh.layered_meshing.material._material.Material,
                    salvus.mesh.layered_meshing.interface.Interface,
                ]
            ],
        ],
        linear_solids: Optional[
            salvus.project.configuration.model.LinearSolids
        ] = None,
        attrs: Dict[Any, Any] = default,
    ) -> None:
        ...

An ordered collection of models bound by interface.

Parameters
  • strata Union[salvus.mesh.layered_meshing.material._material.Material, Iterable[Union[salvus.mesh.layered_meshing.material._material.Material, salvus.mesh.layered_meshing.interface.Interface]]] — A list of alternating interfaces and materials, specified in top-down order (i.e. from highest to lowest elevation). If the strata are not bounded by interfaces on either or both ends, bounding Hyperplanes will be implicitly be added as the first and/or last strata with a Depth and/or Height (respectively) of 0.
  • linear_solids Optional[salvus.project.configuration.model.LinearSolids] — One can optional specify the linear solids model to be used when running simulations including attenuation. If any materials contain parameters relevant for attenuation (i.e.: Q), this parameter must be specified.
  • attrs Dict[Any, Any] — Additional attributes to attach to the layered model.
Attributes
are_interfaces_realized bool

Determine whether all interfaces have absolute coordinates.

are_materials_realized bool

Determine whether all materials are realized.

bounding_interfaces Tuple[Union[salvus.mesh.layered_meshing.interface.Interface, NoneType], Union[salvus.mesh.layered_meshing.interface.Interface, NoneType]]

Return the bounding (top and bottom) interfaces of a layered model.

If a bound does not have a associated interface, return None for that bound.

Returns: A tuple of optional bounding interfaces.

interfaces List[salvus.mesh.layered_meshing.interface.Interface]

Get the interfaces belonging to this layered model.

is_complete bool

Determine whether a layered model is complete.

Completeness in this context refers to whether the layered model is bounded on both sides by interfaces.

layers List[salvus.mesh.layered_meshing.layered_model.layer.Layer]

Get a list of layers that tie together 2 interface with a model.

models List[salvus.mesh.layered_meshing.material._material.Material]

Get the models belonging to this layered model.

n_interfaces int

Get the number of interfaces.

n_layers int

Get the number of layers.

n_models int

Get the number of interfaces.

strata_list List[Union[salvus.mesh.layered_meshing.interface.Interface, salvus.mesh.layered_meshing.material._material.Material]]

Ensure a consistent list-based representation of strata.

Methods
from_layers()
def from_layers(
    layers: Union[
        salvus.mesh.layered_meshing.layered_model.layer.Layer,
        List[salvus.mesh.layered_meshing.layered_model.layer.Layer],
    ],
    linear_solids: Optional[
        salvus.project.configuration.model.LinearSolids
    ] = None,
) -> LayeredModel:
    ...

Unpack a list of layers into a LayeredModel.

Parameters
  • layers Union[salvus.mesh.layered_meshing.layered_model.layer.Layer, List[salvus.mesh.layered_meshing.layered_model.layer.Layer]] — List of layers, specified in a top-to-bottom order. The internal interfaces of neighboring layers must be coincident.
  • linear_solids Optional[salvus.project.configuration.model.LinearSolids] — Optional parameters governing linear solids used to approximate attenuation. If viscous materials are detected in the layered model but linear_solids is not set, an error will result.
Returns LayeredModel — The layers packed into a LayeredModel.
adjust_bounds()
def adjust_bounds(
    self, top: Optional[float] = None, bot: Optional[float] = None
) -> typing_extensions.Self:
    ...

Adjust the positions of the bounding interfaces.

New locations for bounding hyperplanes can be suggested by passing absolute elevation values for above and/or below. Any relative coordinate values will be adjusted accordingly. If bounding interfaces are not present in the current model, an interface will be added at the specified elevations.

Parameters
  • top Optional[float] — New location of the top boundary, or None to leave the top boundary unchanged.
  • bot Optional[float] — New location of the bottom boundary, or None to leave the bottom boundary unchanged.
Returns typing_extensions.Self — A new layered model with potentially adjusted bounding interfaces.
complete()
def complete(self) -> typing_extensions.Self:
    ...

Get a new layered model that includes any required bounding interfaces.

A layered model can be initialized without any bounding interfaces, or with bounding interfaces on only one side. This function adds any missing bounding interfaces so as to ensure that the resulting layered model is “complete”.

Returns typing_extensions.Self — A new layered model with any required bounding interfaces. If bounding interfaces are already present on either boundary, they are retained.
concat()
def concat(
    self,
    above: Optional[
        float,
        salvus.mesh.layered_meshing.material._material.Material,
        salvus.mesh.layered_meshing.interface.Interface,
        List[
            Union[
                salvus.mesh.layered_meshing.material._material.Material,
                salvus.mesh.layered_meshing.interface.Interface,
                NoneType,
            ]
        ],
    ] = None,
    below: Optional[
        float,
        salvus.mesh.layered_meshing.material._material.Material,
        salvus.mesh.layered_meshing.interface.Interface,
        List[
            Union[
                salvus.mesh.layered_meshing.material._material.Material,
                salvus.mesh.layered_meshing.interface.Interface,
                NoneType,
            ]
        ],
    ] = None,
) -> typing_extensions.Self:
    ...

Concatenate strata onto the ends of the layered model.

This method is useful when one is interested in adding or replacing strata on either end of the layered model. For instance, calling

lm_1 = lm_0.complete().concat(above=Hyperplane.at(0.0))

will replace the first stratum, here guaranteed to be an interface due to the presence of .complete(), with a hyperplane at the vertical coordinate zero.

Parameters
  • above Optional[float, salvus.mesh.layered_meshing.material._material.Material, salvus.mesh.layered_meshing.interface.Interface, List[Union[salvus.mesh.layered_meshing.material._material.Material, salvus.mesh.layered_meshing.interface.Interface, NoneType]]] — Strata to concatenate onto the beginning (top) of the layered model, or None if no concatenation should happen.
  • below Optional[float, salvus.mesh.layered_meshing.material._material.Material, salvus.mesh.layered_meshing.interface.Interface, List[Union[salvus.mesh.layered_meshing.material._material.Material, salvus.mesh.layered_meshing.interface.Interface, NoneType]]] — Strata to concatenate on to the end (bottom) of the layered model, or None if no concatenation should happen.
Returns typing_extensions.Self — A new layered model with including the concatenated interfaces.
dropwhile()
def dropwhile(
    self,
    f_material: Callable[
        [salvus.mesh.layered_meshing.material._material.Material], bool
    ] = salvus.mesh.layered_meshing.layered_model.layered_model._true,
    f_interface: Callable[
        [salvus.mesh.layered_meshing.interface.Interface], bool
    ] = salvus.mesh.layered_meshing.layered_model.layered_model._true,
    variant: Literal[("inclusive", "exclusive")] = "exclusive",
) -> typing_extensions.Self:
    ...

Get a new layered model with a potential subset of strata.

This function closely follows the semantics of itertools.takewhile. All strata will be kept until the stratum where one of f_model or f_interface fails.

Parameters
  • f_material Callable[[salvus.mesh.layered_meshing.material._material.Material], bool] — The function to apply to materials.
  • f_interface Callable[[salvus.mesh.layered_meshing.interface.Interface], bool] — The function to apply to interfaces.
  • variant Literal[('inclusive', 'exclusive')] — Whether to perform an exclusive or inclusive dropwhile. The inclusive variant includes the stratum just before the predicate fails, while the exclusive variant does not.
Returns typing_extensions.Self — A new layered model.
filter()
def filter(
    self,
    f_interface: Callable[
        [List[salvus.mesh.layered_meshing.interface.Interface]],
        List[salvus.mesh.layered_meshing.interface.Interface],
    ],
) -> typing_extensions.Self:
    ...

Filter interfaces out of the layered model.

Useful, for instance, to remove duplicate neighboring interfaces from a layered model (pass more_itertools.unique_justseen for f.)

Parameters
  • f_interface Callable[[List[salvus.mesh.layered_meshing.interface.Interface]], List[salvus.mesh.layered_meshing.interface.Interface]] — The filtering function. Should take a list of interfaces and return a (potentially filtered) list of interfaces.
Returns typing_extensions.Self — A new layered model with potentially filtered interfaces.
map_layers_with()
def map_layers_with(
    self,
    f_layer: Union[
        List[
            salvus.mesh.layered_meshing.layered_model.layered_model._MapLayersWithProtocol
        ],
        salvus.mesh.layered_meshing.layered_model.layered_model._MapLayersWithProtocol,
    ],
) -> typing_extensions.Self:
    ...

Apply a list of functions to each layer.

This function is useful when one wants to transform the materials while including the full context of the layer bounding the material, and the canonical use case is realizing the material’s coordinates and bounds. Note that the function passed here should take three arguments comprising of a layer’s (top_interface, material, bottom_interface) and return a (potentially transformed) material. The full layer itself cannot be returned from the function, as this may result in inconsistent interface properties across adjacent layers.

For the transformation functions, one can pass either:

- A appropriate callable (will be applied to every layer)
- A list of callables of length n_layer (will be individually
  applied to its matching layer).
Parameters
  • f_layer Union[List[salvus.mesh.layered_meshing.layered_model.layered_model._MapLayersWithProtocol], salvus.mesh.layered_meshing.layered_model.layered_model._MapLayersWithProtocol] — A function transforming layers to materials, following the semantics outlined above.
Returns typing_extensions.Self — A new LayeredModel instance with transformed materials.
map_with()
def map_with(
    self,
    f_model: Union[
        List[
            Callable[
                [salvus.mesh.layered_meshing.material._material.Material],
                salvus.mesh.layered_meshing.material._material.Material,
            ]
        ],
        Callable[
            [salvus.mesh.layered_meshing.material._material.Material],
            salvus.mesh.layered_meshing.material._material.Material,
        ],
    ] = salvus.utils.utils.identity,
    f_interface: Union[
        List[
            Callable[
                [salvus.mesh.layered_meshing.interface.Interface],
                salvus.mesh.layered_meshing.interface.Interface,
            ]
        ],
        Callable[
            [salvus.mesh.layered_meshing.interface.Interface],
            salvus.mesh.layered_meshing.interface.Interface,
        ],
    ] = salvus.utils.utils.identity,
) -> LayeredModel:
    ...

Apply a list of functions to each interface and / or material.

This function is useful when one wants to transform the components of a layered model individually. One could, for instance, shift the coordinates of each interface by a fixed value, or scale the parameters of each material, or both. An important use case for this function is in the “realization” of interfaces in the presence of some domain; that is assigning absolute coordinates where relative values have been specified.

For either the model or interface transformation functions, one can pass either:

- The identity function (default)
- A appropriate callable (will be applied to every matching strata)
- A list of callables of length n_model / n_interface (will be
  individually applied to its matching model / interface).
Parameters
  • f_model Union[List[Callable[[salvus.mesh.layered_meshing.material._material.Material], salvus.mesh.layered_meshing.material._material.Material]], Callable[[salvus.mesh.layered_meshing.material._material.Material], salvus.mesh.layered_meshing.material._material.Material]] — A function transforming materials to materials, following the semantics outlined above.
  • f_interface Union[List[Callable[[salvus.mesh.layered_meshing.interface.Interface], salvus.mesh.layered_meshing.interface.Interface]], Callable[[salvus.mesh.layered_meshing.interface.Interface], salvus.mesh.layered_meshing.interface.Interface]] — A function transform interfaces to interfaces, following the semantics outlined above.
Returns LayeredModel — A new LayeredModel instance with transformed components.
reduce_layers()
def reduce_layers(
    self, f_layer: salvus.mesh.layered_meshing.layered_model.layered_model
) -> List[~T]:
    ...

Apply a reduction to each layer and return the results as a list.

This function is useful for reducing information about each layer in a generic fashion. Pre-defined reduction functions can be found in salvus.mesh.layered_meshing.layered_model.reductions, or a custom one can be used as long as it satisfies the _ReduceLayersProtocol.

The a layered model must be “complete” before being reduced layerwise, meaning that its bounding interfaces must be defined. See the documentation of LayeredModel.complete() for details.

Parameters
  • f_layer salvus.mesh.layered_meshing.layered_model.layered_model — A function to apply to each layer. Its signature must match the call signature of _ReduceLayersProtocol.
Returns List[~T] — A list of values containing the results of applying f_layer to each layer in top-down order.
strip()
def strip(
    self, strip_instance: Literal[("material", "interface")]
) -> typing_extensions.Self:
    ...

Strip bounding strata from a layered model.

If a stratum of type strip_instance does not exist as a bounding interface, that bound of the model will be unchanged.

Parameters
  • strip_instance Literal[('material', 'interface')] — The type of strata to strip — either “material” or “interface”.
Returns typing_extensions.Self — A new layered model with the bounding strata stripped.
takewhile()
def takewhile(
    self,
    f_material: Callable[
        [salvus.mesh.layered_meshing.material._material.Material], bool
    ] = salvus.mesh.layered_meshing.layered_model.layered_model._true,
    f_interface: Callable[
        [salvus.mesh.layered_meshing.interface.Interface], bool
    ] = salvus.mesh.layered_meshing.layered_model.layered_model._true,
    variant: Literal[("inclusive", "exclusive")] = "exclusive",
) -> typing_extensions.Self:
    ...

Get a new layered model with a potential subset of strata.

This function closely follows the semantics of itertools.takewhile. All strata will be kept until the stratum where one of f_model or f_interface fails.

Parameters
  • f_material Callable[[salvus.mesh.layered_meshing.material._material.Material], bool] — The function to apply to materials.
  • f_interface Callable[[salvus.mesh.layered_meshing.interface.Interface], bool] — The function to apply to interfaces.
  • variant Literal[('inclusive', 'exclusive')] — Whether to perform an exclusive or inclusive dropwhile. The inclusive variant includes the stratum just before the predicate fails, while the exclusive variant does not.
Returns typing_extensions.Self — A new layered model.
truncate()
def truncate(
    self,
    above: Optional[float] = None,
    below: Optional[float] = None,
    variant: Literal[("inclusive", "exclusive")] = "exclusive",
) -> typing_extensions.Self:
    ...

Truncate a layered model with a potentially new Hyperplane.

Any interfaces with their maximum elevation above above are removed, and, likewise, any interfaces with their minimum elevation below below are removed.

Parameters
  • above Optional[float] — Elevation value above which interfaces will be removed, or None to leave the top boundary unchanged.
  • below Optional[float] — Elevation value after which interfaces will be removed, or None to leave the bottom boundary unchanged.
  • variant Literal[('inclusive', 'exclusive')] — Variant of of take / dropwhile to use. If “inclusive”, the next / previous interface above / below the specified elevations will also be kept; if “exclusive” they will not.
Returns typing_extensions.Self — A new, potentially truncated, layered model.