Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

FML #3041

Merged
merged 12 commits into from
Oct 25, 2023
Merged

FML #3041

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
92c0fa8
Move FML from Gusto to Firedrake
JDBetteridge Jul 26, 2023
8dfdf33
Bring across updates to FML in Gusto to the FML branch (#3055)
tommbendall Aug 11, 2023
ba95a46
Fix FML tests for complex
JDBetteridge Sep 22, 2023
f2e4c3d
Fix FML docstrings
JDBetteridge Sep 22, 2023
844b4a0
Apply suggestions from code review
JDBetteridge Oct 5, 2023
4b90e35
Remove RST roles from docstrings
JDBetteridge Oct 11, 2023
620285a
Add type hinting
JDBetteridge Oct 12, 2023
8b59ff8
Changes so Python3.8 is still usable
JDBetteridge Oct 12, 2023
002e437
Update firedrake/fml/form_manipulation_language.py
dham Oct 18, 2023
b1d8ebe
Update firedrake/fml/form_manipulation_language.py
dham Oct 18, 2023
0999e81
Apply comments from Reuben and Lawrence, use imperative voice, remove…
JDBetteridge Oct 23, 2023
0da7455
Imperative mooooood.
dham Oct 25, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 48 additions & 46 deletions firedrake/fml/form_manipulation_language.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,9 @@ def __init__(self, form, label_dict=None):
"""
Parameters
----------
form : :class:`ufl.Form`
form : ufl.Form
The form for this terms.
label_dict : :obj:`dict`, optional
label_dict : `dict`, optional
JDBetteridge marked this conversation as resolved.
Show resolved Hide resolved
Dictionary of key-value pairs corresponding to current form labels.
Defaults to None.
"""
Expand All @@ -45,7 +45,7 @@ def get(self, label):

Parameters
----------
label : :class:`Label`
label : Label
The label to return the value of.

Returns
Expand All @@ -61,10 +61,10 @@ def has_label(self, *labels, return_tuple=False):

Parameters
----------
*labels : :class:`Label`
*labels : Label
A label or series of labels. A tuple is automatically returned if
multiple labels are provided as arguments.
return_tuple : :obj:`bool`, optional
return_tuple : `bool`, optional
JDBetteridge marked this conversation as resolved.
Show resolved Hide resolved
If True, forces a tuple to be returned even if only one label is
provided as an argument. Defaults to False.

Expand All @@ -84,12 +84,12 @@ def __add__(self, other):

Parameters
----------
other : :class:`Term` or :class:`LabelledForm`
other : Term or LabelledForm
The term or labelled form to add to this term.

Returns
-------
:class:`LabelledForm`
LabelledForm
A labelled form containing the terms.
"""
if self is NullTerm:
Expand All @@ -111,12 +111,12 @@ def __sub__(self, other):

Parameters
----------
other : :class:`Term` or :class:`LabelledForm`
other : Term or LabelledForm
The term or labelled form to subtract from this term.

Returns
-------
:class:`LabelledForm`
LabelledForm
A labelled form containing the terms.
"""
other = other * Constant(-1.0)
Expand All @@ -128,12 +128,12 @@ def __mul__(self, other):

Parameters
----------
other : float, :class:`Constant` or :class:`ufl.algebra.Product`
other : float, Constant or ufl.algebra.Product
The quantity to multiply this term by.

Returns
-------
:class:`Term`
Term
The product of the term with the quantity.
"""
return Term(other*self.form, self.labels)
Expand All @@ -146,12 +146,13 @@ def __truediv__(self, other):

Parameters
----------
other : float, :class:`Constant` or :class:`ufl.algebra.Product`
other : float, Constant or ufl.algebra.Product
The quantity to divide this term by.

Returns
-------
:class:`Term`: The quotient of the term divided by the quantity.
Term
The quotient of the term divided by the quantity.
"""
return self * (Constant(1.0) / other)

Expand All @@ -167,8 +168,8 @@ class LabelledForm(object):
"""
A form, broken down into terms that pair individual forms with labels.

The `LabelledForm` object holds a list of terms, which pair
:class:`ufl.Form` objects with :class:`.Label`\\ s. The :meth:`label_map`
The LabelledForm object holds a list of terms, which pair
ufl.Form objects with .Label\\ s. The label_map
JDBetteridge marked this conversation as resolved.
Show resolved Hide resolved
dham marked this conversation as resolved.
Show resolved Hide resolved
routine allows the terms to be manipulated or selected based on particular
filters.
"""
Expand All @@ -178,8 +179,8 @@ def __init__(self, *terms):
"""
Parameters
----------
*terms :class:`Term`
Terms to combine to make the `LabelledForm`.
*terms : Term
Terms to combine to make the LabelledForm.

Raises
------
Expand All @@ -198,12 +199,12 @@ def __add__(self, other):

Parameters
----------
other : :class:`ufl.Form`, :class:`Term` or :class:`LabelledForm`
other : ufl.Form, Term or LabelledForm
The form, term or labelled form to add to this labelled form.

Returns
-------
:class:`LabelledForm`
LabelledForm
A labelled form containing the terms.
"""
if isinstance(other, ufl.Form):
Expand All @@ -225,12 +226,12 @@ def __sub__(self, other):

Parameters
----------
other : :class:`ufl.Form`, :class:`Term` or :class:`LabelledForm`
other : ufl.Form, Term or LabelledForm
The form, term or labelled form to subtract from this labelled form.

Returns
-------
:class:`LabelledForm`
LabelledForm
A labelled form containing the terms.
"""
if type(other) is Term:
Expand All @@ -249,13 +250,14 @@ def __mul__(self, other):

Parameters
----------
other : float, :class:`Constant` or :class:`ufl.algebra.Product`
other : float, Constant or ufl.algebra.Product
The quantity to multiply this labelled form by. All terms in the
form are multiplied.

Returns
-------
:class:`LabelledForm`: The product of all terms with the quantity.
LabelledForm
The product of all terms with the quantity.
"""
return self.label_map(all_terms, lambda t: Term(other*t.form, t.labels))

Expand All @@ -265,13 +267,13 @@ def __truediv__(self, other):

Parameters
----------
other : float, :class:`Constant` or :class:`ufl.algebra.Product`
other : float, Constant or ufl.algebra.Product
The quantity to divide this labelled form by. All terms in the form
are divided.

Returns
-------
:class:`LabelledForm`
LabelledForm
The quotient of all terms with the quantity.
"""
return self * (Constant(1.0) / other)
Expand All @@ -293,18 +295,18 @@ def label_map(self, term_filter, map_if_true=identity,

Parameters
----------
term_filter : :obj:`callable`
term_filter : `callable`
JDBetteridge marked this conversation as resolved.
Show resolved Hide resolved
A function to filter the labelled form's terms.
map_if_true : :obj:`callable`, optional
map_if_true : `callable`, optional
JDBetteridge marked this conversation as resolved.
Show resolved Hide resolved
How to map the terms for which the term_filter returns True.
Defaults to identity.
map_if_false : :obj:`callable`, optional
map_if_false : `callable`, optional
JDBetteridge marked this conversation as resolved.
Show resolved Hide resolved
How to map the terms for which the term_filter returns False.
Defaults to identity.

Returns
-------
:class:`LabelledForm`
LabelledForm
A new labelled form with the terms mapped.
"""

Expand Down Expand Up @@ -338,7 +340,7 @@ def form(self):

Returns
-------
:class:`ufl.Form`
ufl.Form
The whole form corresponding to all the terms.
"""
# Throw an error if there is no form
Expand All @@ -359,10 +361,10 @@ def __init__(self, label, *, value=True, validator=None):
----------
label : str
The name of the label.
value : :obj:`Any`, optional
value : `any`, optional
JDBetteridge marked this conversation as resolved.
Show resolved Hide resolved
The value for the label to take. Can be any type (subject to the
validator). Defaults to True.
validator : :obj:`callable`, optional
validator : `callable`, optional
JDBetteridge marked this conversation as resolved.
Show resolved Hide resolved
Function to check the validity of any value later passed to the
label. Defaults to None.
"""
Expand All @@ -376,22 +378,22 @@ def __call__(self, target, value=None):

Parameters
----------
target : :class:`ufl.Form`, :class:`Term` or :class:`LabelledForm`
target : ufl.Form, Term or LabelledForm
The form, term or labelled form to be labelled.
value : Any, optional
The value to attach to this label. Defaults to None.

Raises
------
ValueError
If the `target` is not a :class:`ufl.Form`, :class:`Term` or
:class:`LabelledForm`.
If the `target` is not a ufl.Form, Term or
LabelledForm.

Returns
-------
:class:`Term` or :class:`LabelledForm`
A :class:`Term` is returned if the target is a :class:`Term`,
otherwise a :class:`LabelledForm` is returned.
Term or LabelledForm
A Term is returned if the target is a Term,
otherwise a LabelledForm is returned.
"""
# if value is provided, check that we have a validator function
# and validate the value, otherwise use default value
Expand All @@ -416,18 +418,18 @@ def remove(self, target):
"""
Removes a label from a term or labelled form.

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

Parameters
----------
target : :class:`Term` or :class:`LabelledForm`
target : Term or LabelledForm
Term or labelled form to have this label removed from.

Raises
------
ValueError
If the `target` is not a :class:`Term` or a :class:`LabelledForm`.
If the `target` is not a Term or a LabelledForm.
"""

if isinstance(target, LabelledForm):
Expand All @@ -446,12 +448,12 @@ def update_value(self, target, new):
"""
Updates the label of a term or labelled form.

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

Parameters
----------
target : :class:`Term` or :class:`LabelledForm`
target : Term or LabelledForm
Term or labelled form to have this label updated.
new : Any
The new value for this label to take. The type is subject to the
Expand All @@ -460,7 +462,7 @@ def update_value(self, target, new):
Raises
------
ValueError
If the `target` is not a :class:`Term` or a :class:`LabelledForm`.
If the `target` is not a Term or a LabelledForm.
"""

if isinstance(target, LabelledForm):
Expand Down
Loading