Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion docs/notebooks/dedalus_tutorial_2.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -355,7 +355,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"Scale factors can also be provided as second arguments when setting or retrieving field data via the geitem/setitem interface:"
"Scale factors can also be provided as second arguments when setting or retrieving field data via the getitem/setitem interface:"
]
},
{
Expand Down
2 changes: 1 addition & 1 deletion docs/notebooks/dedalus_tutorial_3.ipynb
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@
"\n",
"We'll discretize $x$ with a Chebyshev basis and pick a dealiasing factor of 2 to correctly dealias the cubic nonlinearity.\n",
"\n",
"This version of Dedalus currently requires explicilty adding [tau terms](../pages/tau_method.rst) as unknowns to the problem in order to enforce boundary conditions.\n",
"This version of Dedalus currently requires explicitly adding [tau terms](../pages/tau_method.rst) as unknowns to the problem in order to enforce boundary conditions.\n",
"This problem requires two constant tau terms to enforce the two endpoint boundary conditions."
]
},
Expand Down
4 changes: 2 additions & 2 deletions docs/pages/general_functions.rst
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
General Functions
*****************

The ``GeneralFunction`` and ``UnaryGridFunction`` classes enables users to simply define new explicit operators for the right-hand side and analysis tasks of their simulations.
The ``GeneralFunction`` and ``UnaryGridFunction`` classes enable users to simply define new explicit operators for the right-hand side and analysis tasks of their simulations.
Such operators can be used to apply arbitrary user-defined functions to the grid values or coefficients of some set of input fields, or even do things like introduce random data or read data from an external source.

A ``GeneralFunction`` object is instantiated with a Dedalus distributor, domain, tensor signature, dtype, layout object or descriptor (e.g. ``'g'`` or ``'c'`` for grid or coefficient space), function, list of arguments, and dictionary of keywords.
The resulting object is a Dedalus operator that can be evaluated and composed like other Dedalus operators.
It operates by first ensuring that any arguments that are Dedalus field objects are in the specified layout, then calling the function with the specified arguments and keywords, and finally setting the result as the output data in the specified layout.

A simpler option that should work for many use cases is the ``UnaryGridFunction`` class, which specifically applies a function to the grid data of a single field.
The output field's distributor, domain/bases, tensor signature, and dtype are all taken to be idential to those of the input field.
The output field's distributor, domain/bases, tensor signature, and dtype are all taken to be identical to those of the input field.
Only the function and input field need to be specified.
The function must be vectorized, take a single Numpy array as input, and include an ``out`` argument that specifies the output array.
Applying most Numpy or Scipy universal functions to a Dedalus field will automatically produce the corresponding ``UnaryGridFunction`` operator.
Expand Down
4 changes: 2 additions & 2 deletions docs/pages/half_dimensions.rst
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ Cartesian problems

In Cartesian coordinate systems, the constant dimensions (with no bases) should be placed as the last dimensions in the coordinate system.
Note this may require marking the coordinate system as being left-handed so that the proper signs are used in curls and cross products.
The reason is that Dedalus distributes problems over the leading axes, and if one of these is constant, the problem will end up entirely on a single core, bottleneckling the scaling.
The reason is that Dedalus distributes problems over the leading axes, and if one of these is constant, the problem will end up entirely on a single core, bottlenecking the scaling.

For instance, consider a 2.5D problem in a 3D Cartesian domain with coordinates :math:`(x, y, z)`, where the solution is independent of :math:`y`, and the coordinate system is defined normally with a 1D process mesh of size :math:`p=8`:

Expand Down Expand Up @@ -45,7 +45,7 @@ Curvilinear problems
--------------------

In curvilinear coordinates, axisymmetric problems can be handled by setting the azimuthal resolution to 1.
However, unlike Cartesian coordinate, the coordinate ordering is fixed.
However, unlike Cartesian coordinates, the coordinate ordering is fixed.
Since the azimuthal coordinate is the first in the curvilinear coordinate systems, distributing over this dimension can be avoided by prepending a 1 to the process mesh shape.
So for instance, an axisymmetric problem in the ball can be parallelized over :math:`p=8` processes as follows:

Expand Down
2 changes: 1 addition & 1 deletion docs/pages/performance_tips.rst
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ Process meshes for better load balancing

Dedalus uses multidimensional block distributions when decomposing domains in parallel.
By default, problems are parallelized over a 1D process mesh of all available MPI processes.
Multidimensional parallelization is easily enabled by specifing a mesh shape using the ``mesh`` keyword when instantiating a ``Distributor`` object.
Multidimensional parallelization is easily enabled by specifying a mesh shape using the ``mesh`` keyword when instantiating a ``Distributor`` object.
The specified mesh shape should be a tuple with a length one less than the problem dimension.

Ideal load balancing occurs when the size of a distributed dimension is evenly divisible by the corresponding mesh size.
Expand Down
14 changes: 7 additions & 7 deletions docs/pages/tau_method.rst
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
Tau Method
**********

The *generalized tau method* is a system for imposing boundary boundary conditions (BCs) when solving partial differential equations (PDEs) using polynomial spectral methods.
The *generalized tau method* is a system for imposing boundary conditions (BCs) when solving partial differential equations (PDEs) using polynomial spectral methods.
It consists of explicitly adding *tau terms* to the PDE which introduce degrees of freedom that allow the problem to be solved exactly over polynomials.
Determining the optimal tau terms to add to a given PDE is an open problem, and while we hope to eventually automate this process in Dedalus, currently these terms must be manually added when specifying equations in Dedalus v3.

The underyling mathematical issue is that most PDEs that we wish to solve do not have exact polynomial solutions.
The underlying mathematical issue is that most PDEs that we wish to solve do not have exact polynomial solutions.
Instead, we seek polynomial solutions that approximate the true solution.
All spectral methods find such a solution by modifying the underlying equations in some way, and then solve for the exact polynomial solution to the modified equations.
The tau method makes these modifications explicit in the problem specification rather than hiding them within the solution algorithm.
Expand Down Expand Up @@ -76,14 +76,14 @@ If the RHS terms are truncated at degree :math:`N` in :math:`y` and the tau poly

In Dedalus v2, equations were required to be entered in first-order form as above.
Tau terms were then automatically added to the differential equations with :math:`P(y) = U_N(y)`, using the second-kind Chebyshev polynomials :math:`U_n(y)`.
This system consituted a generalized tau method using a first-order form of the Cheybshev ultraspherical method.
This system constituted a generalized tau method using a first-order form of the Chebyshev ultraspherical method.
Algorithmically, it is equivalent to dropping the last rows from the differential equations after they have been discretized with the ultraspherical method (using sparse Chebyshev T-to-U operators).
Enforcing boundary conditions in this fashion is easily automatable, but results in larger linear systems due to the first-order reduction.

Higher-order systems
--------------------

To more efficiently handle high-order systems, and to more easily accomodate the singular equations arising in curvilinear domains, Dedalus v3 supports equations with arbitrary differential order.
To more efficiently handle high-order systems, and to more easily accommodate the singular equations arising in curvilinear domains, Dedalus v3 supports equations with arbitrary differential order.
For Chebyshev dimensions as well as annuli and spherical shells, we recommend adding tau terms to the equations in a manner consistent with the first-order formulations discussed above.
For example, after adding the tau terms above, we can eliminate the first-order-reduction variables to recover the original second-order equations, but containing the same tau corrections:

Expand Down Expand Up @@ -136,8 +136,8 @@ Here we'll take :math:`P(y)` to be the highest mode in the Chebyshev-U basis, in
lift = lambda A: d3.Lift(A, lift_basis, -1) # Shortcut for multiplying by U_{N-1}(y)
grad_u = d3.grad(u) - ey*lift(tau_u1) # Operator representing G

We can then create a problem and enter the tau-modified PDEs, boundary condtions, and pressure gauge in vectorial form using these substitutions.
Note that we will need to add the contant tau variable to the divergence equation as described in the :doc:`gauge_conditions` page.
We can then create a problem and enter the tau-modified PDEs, boundary conditions, and pressure gauge in vectorial form using these substitutions.
Note that we will need to add the constant tau variable to the divergence equation as described in the :doc:`gauge_conditions` page.
This allows us to impose the pressure gauge and removes the redundancy between the integral of the divergence equation and the integral of the inflow boundary conditions.

.. code-block:: python
Expand Down Expand Up @@ -190,7 +190,7 @@ Now we can enter the PDE with just the single tau term in the momentum equation:
problem.add_equation("u(r=1) = 0")
problem.add_equation("integ(p) = 0")

Again, the same appraoch can be used to add scalar taus for tracer fields/equations, as illustrated in the :doc:`example scripts <tutorials>`.
Again, the same approach can be used to add scalar taus for tracer fields/equations, as illustrated in the :doc:`example scripts <tutorials>`.

Summary
-------
Expand Down