Warning

You are reading a version of the website built against the unstable main branch. This content is liable to change without notice and may be inappropriate for your use case. You can find the documentation for the current stable release here.

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

firedrake.fml package¶

Submodules¶

firedrake.fml.form_manipulation_language module¶

firedrake.fml.replacement module¶

Module contents¶