firedrake.fml package

Submodules

firedrake.fml.form_manipulation_language module

A language for manipulating forms using labels.

class firedrake.fml.form_manipulation_language.Label(label, *, value: Any = True, validator: Callable | None = None)[source]

Bases: object

Object for tagging forms, allowing them to be manipulated.

Parameters:

  • label – The name of the label.

  • value – The value for the label to take. Can be any type (subject to the validator). Defaults to True.

  • validator – Function to check the validity of any value later passed to the label. Defaults to None.

__call__(target: Form | Term | LabelledForm, value: Any = None) → Term | LabelledForm[source]

Apply the label to a form or term.

Parameters:

  • target – The form, term or labelled form to be labelled.

  • value – The value to attach to this label. Defaults to None.

Raises:

ValueError – If the target is not a ufl.Form, Term or LabelledForm.

Returns:

A Term is returned if the target is a Term, otherwise a LabelledForm is returned.

Return type:

Union[Term, LabelledForm]

default_value
label
remove(target: Term | LabelledForm)[source]

Remove a label from a term or labelled form.

This removes any Label with this label from target. If called on an LabelledForm, it acts term-wise.

Parameters:

target – Term or labelled form to have this label removed from.

Raises:

ValueError – If the target is not a Term or a LabelledForm.

update_value(target: Term | LabelledForm, new: Any)[source]

Update the label of a term or labelled form.

This updates the value of any Label with this label from target. If called on an LabelledForm, it acts term-wise.

Parameters:

  • target – Term or labelled form to have this label updated.

  • new – The new value for this label to take. The type is subject to the label’s validator (if it has one).

Raises:

ValueError – If the target is not a Term or a LabelledForm.

validator
value
class firedrake.fml.form_manipulation_language.LabelledForm(*terms: Sequence[Term])[source]

Bases: object

A form, broken down into terms that pair individual forms with labels.

The LabelledForm object holds a list of terms, which pair ufl.Form objects with Label s. The label_map routine allows the terms to be manipulated or selected based on particular filters.

Parameters:

*terms (Term) – Terms to combine to make the LabelledForm.

Raises:

TypeError – If any argument is not a term.:

property form: Form

Provide the whole form from the labelled form.

Raises:

TypeError – If the labelled form has no terms.

Returns:

The whole form corresponding to all the terms.

Return type:

ufl.Form

label_map(term_filter: ~typing.Callable[[~firedrake.fml.form_manipulation_language.Term], bool], map_if_true: ~typing.Callable[[~firedrake.fml.form_manipulation_language.Term], ~firedrake.fml.form_manipulation_language.Term | None] = <function identity>, map_if_false: ~typing.Callable[[~firedrake.fml.form_manipulation_language.Term], ~firedrake.fml.form_manipulation_language.Term | None] = <function identity>) → LabelledForm[source]

Map selected terms in the labelled form, returning a new labelled form.

Parameters:

  • term_filter – A function to filter the labelled form’s terms.

  • map_if_true – How to map the terms for which the term_filter returns True. Defaults to identity.

  • map_if_false – How to map the terms for which the term_filter returns False. Defaults to identity.

Returns:

A new labelled form with the terms mapped.

Return type:

LabelledForm

terms
class firedrake.fml.form_manipulation_language.Term(form: Form, label_dict: Mapping = None)[source]

Bases: object

A Term object contains a form and its labels.

Parameters:

  • form – The form for this terms.

  • label_dict – Dictionary of key-value pairs corresponding to current form labels. Defaults to None.

form
get(label: Label) → Any[source]

Return the value of a label.

Parameters:

label – The label to return the value of.

Returns:

The value of a label.

Return type:

Any

has_label(*labels: Label, return_tuple: bool = False) → Tuple[bool] | bool[source]

Return whether the specified labels are attached to this term.

Parameters:

  • *labels – A label or series of labels. A tuple is automatically returned if multiple labels are provided as arguments.

  • return_tuple – If True, forces a tuple to be returned even if only one label is provided as an argument. Defaults to False.

Returns:

Booleans corresponding to whether the term has the specified labels.

Return type:

bool

labels
firedrake.fml.form_manipulation_language.all_terms(t: Term) → bool[source]

Map all terms to True.

Parameters:

t – A term.

Returns:

True.

Return type:

bool

firedrake.fml.form_manipulation_language.drop(t: Term) → None[source]

Map all terms to None.

Parameters:

t – A term.

Returns:

None.

Return type:

None

firedrake.fml.form_manipulation_language.identity(t: Term) → Term[source]

The identity map.

Parameters:

t – A term.

Returns:

The same term.

Return type:

Term

firedrake.fml.form_manipulation_language.keep(t: Term) → Term[source]

Keep all terms.

Functionally equivalent to identity.

Parameters:

t – A term.

Returns:

The same term.

Return type:

Term

firedrake.fml.replacement module

Generic routines for replacing functions using FML.

firedrake.fml.replacement.replace_subject(new_subj: Expr, old_idx: int | None = None, new_idx: int | None = None) → Callable[[Term], Term][source]

Replace the subject in a term with a new variable.

Parameters:

  • new – The new expression to replace the subject.

  • old_idx – The index of the old subject to be replaced. If the old variable is not indexable then this should be None.

  • new_idx – The index of the new subject to replace with. If the new variable is not indexable then this should be None.

Returns:

A function that takes in t, a Term, and returns a new Term with form containing the new_test and labels=t.labels

Return type:

Callable

firedrake.fml.replacement.replace_test_function(new_test: Argument, old_idx: int | None = None, new_idx: int | None = None) → Callable[[Term], Term][source]

Replace the test function in a term with a new test function.

Parameters:

  • new_test – The new test function.

  • old_idx – The index of the old TestFunction to be replaced. If the old variable is not indexable then this should be None.

  • new_idx – The index of the new TestFunction to replace with. If the new variable is not indexable then this should be None.

Returns:

A function that takes in t, a .Term, and returns a new .Term with form containing the new_test and labels=t.labels

Return type:

Callable

firedrake.fml.replacement.replace_trial_function(new_trial: Argument | Function, old_idx: int | None = None, new_idx: int | None = None) → Callable[[Term], Term][source]

Replace the trial function in a term with a new expression.

Parameters:

  • new – The new function.

  • old_idx – The index of the old Function or TrialFunction to be replaced. If the old variable is not indexable then this should be None.

  • new_idx – The index of the new Function or TrialFunction to replace with. If the new variable is not indexable then this should be None.

Returns:

A function that takes in t, a Term, and returns a new Term with form containing the new_test and labels=t.labels

Return type:

Callable

Module contents