Create a rectangular domain¶

class opentidalfarm.domains.rectangle_domain.RectangularDomain(x0, y0, x1, y1, nx, ny)[source]¶

Create a rectangular domain.

Parameters:	x0 (float) – The x coordinate of the bottom-left. y0 (float) – The y coordinate of the bottom-left. x1 (float) – The x coordinate of the top-right corner. y1 (float) – The y coordinate of the top-right corner.

cell_ids = None¶

A dolfin.CellFunction containing the area markers.

facet_ids = None¶

A dolfin.FacetFunction containing the surface markers.

mesh = None¶

A dolfin.Mesh containing the mesh.

Load domain from a mesh file¶

class opentidalfarm.domains.file_domain.FileDomain(mesh_file, facet_ids_file=None, cell_ids_file=None)[source]¶

Create a domain from DOLFIN mesh files (.xml).

Parameters:	mesh_file (str) – The .xml file of the mesh. facet_ids_file (str) – The .xml file containing the facet ids of the mesh. If None, the default is to mesh_file + “_facet_region.xml”. cell_ids_file (str) – The .xml file containing the cell ids of the mesh. If None, the default is to mesh_file + “_physical_region.xml”.

cell_ids = None¶

A dolfin.CellFunction containing the area markers.

facet_ids = None¶

A dolfin.FacetFunction containing the surface markers.

mesh = None¶

A dolfin.Mesh containing the mesh.

Steady shallow water¶

class opentidalfarm.problems.steady_sw.SteadySWProblem(parameters)[source]¶

Create a steady-state shallow water problem:

\[\begin{split}-\nabla\cdot\nu\nabla u+u\cdot\nabla u+g\nabla \eta + \frac{c_b + c_t}{H} \| u\| u &= f_u, \\ \nabla \cdot \left( H u \right) &= 0,\end{split}\]

where

• \(u\) is the velocity,
• \(\eta\) is the free-surface displacement,
• \(H=\eta + h\) is the total water depth where \(h\) is the water depth at rest,
• \(f_u\) is the velocity forcing term,
• \(c_b\) is the (quadratic) natural bottom friction coefficient,
• \(c_t\) is the (quadratic) friction coefficient due to the turbine farm,
• \(\nu\) is the viscosity coefficient,
• \(g\) is the gravitational constant,

Parameters:	parameters – A SteadySWProblemParameters object containing the parameters of the problem.

static default_parameters()[source]¶

Returns a SteadySWProblemParameters with default parameters.

class opentidalfarm.problems.steady_sw.SteadySWProblemParameters[source]¶

A parameters set for a SteadySWProblem.

Domain parameters:

Variables:	domain – The computational domain, see Domains.

Physical parameters:

Variables:	depth – Water depth. Default: 50.0 g – Gravitational constant. Default: 9.81 viscosity – Water viscosity. Default: 3.0 friction – Natural bottom friction. Default: 0.0025 rho – Density of water. Default: 1000.0

Equation parameters:

Variables:	include_advection – Boolean indicating if the advection is included. Default: True include_viscosity – Boolean indicating if the viscosity is included. Default: True linear_divergence – Boolean indicating if the divergence equation is linearised. Default: False f_u – A source term for the velocity component as a dolfin.Expression. Default: Constant((0, 0))

Boundary conditions:

Variables:	bctype – Specifies how the boundary conditions should be enforced. Valid options are: ‘weak_dirichlet’, ‘strong_dirichlet’ or ‘flather’. Default: ‘strong_dirichlet’ bcs – A opentidalfarm.boundary_conditions.BoundaryConditionSet containing a list of boundary conditions for the problem.

Discretization settings:

Variables:	finite_element – The finite-element pair to use. Default:

opentidalfarm.finite_elements.p2p1

Multi steady shallow water¶

class opentidalfarm.problems.multi_steady_sw.MultiSteadySWProblem(parameters)[source]¶

Create a shallow water problem consisting of a sequence of (independent) steady-state shallow water problems. More specifically, it solves for each time-level \(n\):

\[\begin{split}-\nabla\cdot\nu\nabla u^n+u^n\cdot\nabla u^n+g\nabla \eta^n + \frac{c_b + c_t}{H^n} \| u^n\| u^n &= f_u^n, \\ \nabla \cdot \left( H^n u^n \right) &= 0,\end{split}\]

where

• \(u\) is the velocity,
• \(\eta\) is the free-surface displacement,
• \(H=\eta + h\) is the total water depth where \(h\) is the water depth at rest,
• \(f_u\) is the velocity forcing term,
• \(c_b\) is the (quadratic) natural bottom friction coefficient,
• \(c_t\) is the (quadratic) friction coefficient due to the turbine farm,
• \(\nu\) is the viscosity coefficient,
• \(g\) is the gravitational constant,

parameter parameters:
	A MultiSteadySWProblemParameters object containing the parameters of the problem.

static default_parameters()[source]¶

Returns a dictionary with the default parameters

class opentidalfarm.problems.multi_steady_sw.MultiSteadySWProblemParameters[source]¶

A set of parameters for a MultiSteadySWProblem.

The parameters are as described in opentidalfarm.problems.steady_sw.SteadySWProblemParameters.

In addition following parameters are available:

Temporal parameters:

Variables:	dt – The timestep. Default: 1.0. start_time – The start time. Default: 0.0. finish_time – The finish time. Default: 100.0.

Time-dependent shallow water¶

class opentidalfarm.problems.sw.SWProblem(parameters)[source]¶

Create a transient shallow water problem:

\[\begin{split}\frac{\partial u}{\partial t} -\nabla\cdot\nu\nabla u+u\cdot\nabla u+g\nabla \eta + \frac{c_b + c_t}{H} \| u\| u &= f_u, \\ \frac{\partial \eta}{\partial t} + \nabla \cdot \left( H u \right) &= 0,\end{split}\]

where

• \(u\) is the velocity,
• \(\eta\) is the free-surface displacement,
• \(H=\eta + h\) is the total water depth where \(h\) is the water depth at rest,
• \(f_u\) is the velocity forcing term,
• \(c_b\) is the (quadratic) natural bottom friction coefficient,
• \(c_t\) is the (quadratic) friction coefficient due to the turbine farm,
• \(\nu\) is the viscosity coefficient,
• \(g\) is the gravitational constant,

Parameters:	parameters – A SWProblemParameters object containing the parameters of the problem.

static default_parameters()[source]¶

Returns a dictionary with the default parameters

class opentidalfarm.problems.sw.SWProblemParameters[source]¶

A set of parameters for a SWProblem.

The parameters are as described in opentidalfarm.problems.steady_sw.SteadySWProblemParameters.

In addition following parameters are available:

Time parameters:

Variables:	theta – The theta value for the timestepping-scheme. Default 1.0. dt – The timestep. Default: 1.0. start_time – The start time. Default: 0.0. finish_time – The finish time. Default: 100.0.

Functional time integration paramters (FIXME: Move to reduced functional):

Variables:	functional_final_time_only – Boolean indicating if the functional should be integrated over time or evaluated at the end of time only. Default: True.

Common options¶

Advanced options¶

Coupled shallow water solver¶

class opentidalfarm.solvers.coupled_sw_solver.CoupledSWSolver(problem, solver_params)[source]¶

The coupled solver solves the shallow water equations as a fully coupled system with a \(\theta\)-timestepping discretization.

For a opentidalfarm.problems.steady_sw.SteadySWProblem, it solves \(u\) and \(\eta\) such that:

\[\begin{split}u \cdot \nabla u - \nu \Delta u + g \nabla \eta + \frac{c_b + c_t}{H} \| u\| u & = f_u, \\ \nabla \cdot \left(H u\right) & = 0.\end{split}\]

For a opentidalfarm.problems.multi_steady_sw.MultiSteadySWProblem, it solves \(u^{n+1}\) and \(\eta^{n+1}\) for each timelevel (including the initial time) such that:

\[\begin{split}u^{n+1} \cdot \nabla u^{n+1} - \nu \Delta u^{n+1} + g \nabla \eta^{n+1} + \frac{c_b + c_t}{H^{n+1}} \| u^{n+1}\| u^{n+1} & = f_u^{n+1}, \\ \nabla \cdot \left(H^{n+1} u^{n+1}\right) & = 0.\end{split}\]

For a opentidalfarm.problems.sw.SWProblem, and given an initial condition \(u^{0}\) and \(\eta^{0}\) it solves \(u^{n+1}\) and \(\eta^{n+1}\) for each timelevel such that:

\[\begin{split}\frac{1}{\Delta t} \left(u^{n+1} - u^{n}\right) + u^{n+\theta} \cdot \nabla u^{n+\theta} - \nu \Delta u^{n+\theta} + g \nabla \eta^{n+\theta} + \frac{c_b + c_t}{H^{n+\theta}} \| u^{n+\theta}\| u^{n+\theta} & = f_u^{n+\theta}, \\ \frac{1}{\Delta t} \left(\eta^{n+1} - \eta^{n}\right) + \nabla \cdot \left(H^{n+\theta} u^{n+\theta}\right) & = 0.\end{split}\]

with \(\theta \in [0, 1]\) and \(u^{n+\theta} := \theta u^{n+1} + (1-\theta) u^n\) and \(\eta^{n+\theta} := \theta \eta^{n+1} + (1-\theta) \eta^n\).

Furthermore:

• \(u\) is the velocity,
• \(\eta\) is the free-surface displacement,
• \(H=\eta + h\) is the total water depth where \(h\) is the water depth at rest,
• \(f_u\) is the velocity forcing term,
• \(c_b\) is the (quadratic) natural bottom friction coefficient,
• \(c_t\) is the (quadratic) friction coefficient due to the turbine farm,
• \(\nu\) is the viscosity coefficient,
• \(g\) is the gravitational constant,
• \(\Delta t\) is the time step.

Some terms, such as the advection or the diffusion term, may be deactivated in the problem specification.

The resulting equations are solved with Newton-iterations and the linear problems solved as specified in the dolfin_solver setting in CoupledSWSolverParameters.

static default_parameters()[source]¶

Return the default parameters for the CoupledSWSolver.

solve(annotate=True)[source]¶

Returns an iterator for solving the shallow water equations.

class opentidalfarm.solvers.coupled_sw_solver.CoupledSWSolverParameters[source]¶

A set of parameters for a CoupledSWSolver.

Following parameters are available:

Variables:

dolfin_solver – The dictionary with parameters for the dolfin Newton solver. A list of valid entries can be printed with: info(NonlinearVariationalSolver.default_parameters(), True) By default, the MUMPS direct solver is used for the linear system. If not available, the default solver and preconditioner of FEniCS is used. dump_period – Specifies how often the solution should be dumped to disk. Use a negative value to disable it. Default 1. cache_forward_state – If True, the shallow water solutions are stored for every timestep and are used as initial guesses for the next solve. If False, the solution of the previous timestep is used as an initial guess. Default: True print_individual_turbine_power – Print out the turbine power for each turbine. Default: False quadrature_degree – The quadrature degree for the matrix assembly. Default: -1 (automatic) cpp_flags – A list of cpp compiler options for the code generation. Default: [“-O3”, “-ffast-math”, “-march=native”] revolve_parameters – The adjoint checkpointing settings as a set of the form (strategy, snaps_on_disk, snaps_in_ram, verbose). Default: None output_dir – The base directory in which to store the file ouputs. Default: os.curdir output_turbine_power – Output the power generation of the individual turbines. Default: False

Pressure-correction shallow water solver¶

class opentidalfarm.solvers.ipcs_sw_solver.IPCSSWSolver(problem, parameters)[source]¶

This incremental pressure correction scheme (IPCS) is an operator splitting scheme that follows the idea of Goda [1] and Simo [2]. This scheme preserves the exact same stability properties as Navier-Stokes and hence does not introduce additional dissipation in the flow (FIXME: needs verification).

The idea is to replace the unknown free-surface with an approximation. This is chosen as the free-surface solution from the previous solution.

The time discretization is done using a \(\theta\)-scheme, the convection, friction and divergence are handled semi-implicitly. Thus, we have a discretized version of the shallow water equations as

\[\begin{split}\frac{1}{\Delta t}\left( u^{n+1}-u^{n} \right)-\nabla\cdot\nu\nabla u^{n+\theta}+u^*\cdot\nabla u^{n+\theta}+g\nabla \eta^{n+\theta} + \frac{c_b + c_t}{H^n} \| u^n\| u^{n+\theta} &= f_u^{n+\theta}, \\ \frac{1}{\Delta t}\left( \eta^{n+1}-\eta^{n} \right) + \nabla \cdot \left( H^{n} u^{n+\theta} \right) &= 0,\end{split}\]

where \(\square^{n+\theta} = \theta{\square}^{n+1}+(1-\theta)\square^n, \theta \in [0, 1]\) and \(u^* = \frac{3}{2}u^n - \frac{1}{2}u^{n-1}\).

This convection term is unconditionally stable, and with \(\theta=0.5\), this equation is second order in time and space [2] (FIXME: Needs verification).

For the operator splitting, we use the free-surface solution from the previous timestep as an estimation, giving an equation for a tentative velocity, \(\tilde{u}^{n+1}\):

\[\frac{1}{\Delta t}\left( \tilde{u}^{n+1}-u^{n} \right) - \nabla\cdot\nu\nabla \tilde{u}^{n+\theta} + u^*\cdot\nabla \tilde u^{n+\theta}+g\nabla \eta^{n} + \frac{c_b + c_t}{H^n} \| u^n\| \tilde u^{n+\theta} = f_u^{n+\theta}.\]

This tenative velocity does not satisfy the divergence equation, and thus we define a velocity correction \(u^c=u^{n+1}-\tilde{u}^{n+1}\). Substracting the second equation from the first, we see that

\[\begin{split}\frac{1}{\Delta t}u^c - \theta \nabla\cdot\nu\nabla u^c + \theta u^*\cdot\nabla u^{c} + g\theta \nabla\left( \eta^{n+1} - \eta^n\right) + \theta \frac{c_b + c_t}{H^n} \| u^n\| u^{c} &= 0, \\ \frac{1}{\Delta t}\left( \eta^{n+1}-\eta^{n} \right) + \theta \nabla \cdot \left( H^{n} u^c \right) &= -\nabla \cdot \left( H^{n} \tilde{u}^{n+\theta} \right).\end{split}\]

The operator splitting is a first order approximation, \(O(\Delta t)\), so we can, without reducing the order of the approximation simplify the above to

\[\begin{split}\frac{1}{\Delta t}u^c + g\theta \nabla\left( \eta^{n+1} - \eta^n\right) &= 0, \\ \frac{1}{\Delta t}\left( \eta^{n+1}-\eta^{n} \right) + \theta \nabla \cdot \left( H^{n} u^c \right) &= -\nabla \cdot \left( H^{n} \tilde{u}^{n+\theta} \right),\end{split}\]

which is reducible to the problem:

\[\eta^{n+1}-\eta^{n} - g \Delta t^2 \theta^2 \nabla \cdot \left( H^{n+1} \nabla\left( \eta^{n+1} - \eta^n\right) \right) = -\Delta t \nabla \cdot \left( H^{n} \tilde{u}^{n+\theta} \right).\]

The corrected velocity is then easily calculated from

\[u^{n+1} = \tilde{u}^{n+1} - \Delta tg\theta\nabla\left(\eta^{n+1}-\eta^n\right)\]

The scheme can be summarized in the following steps:

1. Replace the pressure with a known approximation and solve for a tenative velocity \(\tilde u^{n+1}\).
2. Solve a free-surface correction equation for the free-surface, \(\eta^{n+1}\)
3. Use the corrected pressure to find the velocity correction and calculate \(u^{n+1}\)
4. Update t, and repeat.

Remarks:

• This solver only works with transient problems, that is with opentidalfarm.problems.sw.SWProblem.
• This solver supports large eddy simulation (LES). The LES model is implemented via the opentidalfarm.solvers.les.LES class.

[1]	Goda, Katuhiko. A multistep technique with implicit difference schemes for calculating two-or three-dimensional cavity flows. Journal of Computational Physics 30.1 (1979): 76-95.

[2]	(1, 2) Simo, J. C., and F. Armero. Unconditional stability and long-term behavior of transient algorithms for the incompressible Navier-Stokes and Euler equations. Computer Methods in Applied Mechanics and Engineering 111.1 (1994): 111-154.

solve(annotate=True)[source]¶

Solve the shallow water equations

class opentidalfarm.solvers.ipcs_sw_solver.IPCSSWSolverParameters[source]¶

A set of parameters for a IPCSSWSolver.

Performance parameters:

Variables:

dolfin_solver – The dictionary with parameters for the dolfin Newton solver. A list of valid entries can be printed with: info(NonlinearVariationalSolver.default_parameters(), True) By default, the MUMPS direct solver is used for the linear system. If not availabe, the default solver and preconditioner of FEniCS is used. quadrature_degree – The quadrature degree for the matrix assembly. Default: -1 (auto) cpp_flags – A list of cpp compiler options for the code generation. Default: [“-O3”, “-ffast-math”, “-march=native”]

Large eddy simulation parameters:

Variables:	les_model – De-/Activates the LES model. Default: True les_model_parameters – A dictionary with parameters for the LES model. Default: {‘smagorinsky_coefficient’: 1e-2}

Prototype Functional¶

Functional objects are overloads of the prototype functional. This allows functionals to be combined and scaled. The initialisation and ‘Jt’ methods should be overloaded.

Power Functionals¶

class opentidalfarm.functionals.power_functionals.PowerCurveFunctional(farm)[source]¶

TODO: doesn’t work yet...

class opentidalfarm.functionals.power_functionals.PowerFunctional(problem)[source]¶

Implements a simple functional of the form:

\[J(u, m) = \int \rho c_t ||u||^3~ dx,\]

where \(c_t\) defines the friction field due to the turbines.

Parameters:	problem (Instance of the problem class.) – The problem for which the functional is being computed.

Jt(state, turbine_field)[source]¶

Computes the power output of the farm.

Parameters:	state (UFL) – Current solution state turbine_field (UFL) – Turbine friction field

Jt_individual(state, i)[source]¶

Computes the power output of the i’th turbine.

Parameters:	state (UFL) – Current solution state i (Integer) – refers to the i’th turbine

force(state, turbine_field)[source]¶

Computes the force field over turbine field

Parameters:	state (UFL) – Current solution state. turbine_field (UFL) – Turbine friction field

force_individual(state, i)[source]¶

Computes the total force on the i’th turbine

Parameters:	state (UFL) – Current solution state i (Integer) – refers to the i’th turbine

power(state, turbine_field)[source]¶

Computes the power field over the domain.

Parameters:	state (UFL) – Current solution state. turbine_field (UFL) – Turbine friction field

Create a rectangular farm¶

class opentidalfarm.farm.rectangular_farm.RectangularFarm(domain, site_x_start, site_x_end, site_y_start, site_y_end, turbine=None, site_ids=None)[source]¶

Extends Farm. Defines a rectangular Farm.

This class holds the turbines within a rectangular site.

add_regular_turbine_layout(num_x, num_y, x_start=None, x_end=None, y_start=None, y_end=None)[source]¶

Adds a rectangular turbine layout to the farm.

A rectangular turbine layout with turbines evenly spread out in each direction across the given rectangular site.

Parameters:

turbine (Turbine object.) – Defines the type of turbine to add to the farm. num_x (int) – The number of turbines placed in the x-direction. num_y (int) – The number of turbines placed in the y-direction. x_start (float) – The minimum x-coordinate of the site. x_end (float) – The maximum x-coordinate of the site. y_start (float) – The minimum y-coordinate of the site. y_end (float) – The maximum y-coordinate of the site.

Raises:

ValueError

add_staggered_turbine_layout(num_x, num_y, x_start=None, x_end=None, y_start=None, y_end=None)[source]¶

Adds a rectangular, staggered turbine layout to the farm.

A rectangular turbine layout with turbines evenly spread out in each direction across the given rectangular site.

Parameters:

turbine (Turbine object.) – Defines the type of turbine to add to the farm. num_x (int) – The number of turbines placed in the x-direction. num_y (int) – The number of turbines placed in the y-direction (will be one less on every second row). x_start (float) – The minimum x-coordinate of the site. x_end (float) – The maximum x-coordinate of the site. y_start (float) – The minimum y-coordinate of the site. y_end (float) – The maximum y-coordinate of the site.

Raises:

ValueError

site_boundary_constraints()[source]¶

Returns the site boundary constraints for a rectangular site.

These constraints ensure that the turbine positions remain within the turbine site during optimisation.

Raises:	ValueError
Returns:	Tuple of lists of length equal to the twice the number of turbines. Each list contains dolfin_adjoint.Constant objects of the upper and lower bound coordinates.

site_x_end[source]¶

The maximum x-coordinate of the site.

Getter:	Returns the maximum x-coordinate of the site.
Type:	float

site_x_start[source]¶

The minimum x-coordinate of the site.

Getter:	Returns the minimum x-coordinate of the site.
Type:	float

site_y_end[source]¶

The maximum y-coordinate of the site.

Getter:	Returns the maximum y-coordinate of the site.
Type:	float

site_y_start[source]¶

The minimum y-coordinate of the site.

Getter:	Returns the minimum y-coordinate of the site.
Type:	float

Create a base farm¶

class opentidalfarm.farm.base_farm.BaseFarm(domain=None, turbine=None, site_ids=None)[source]¶

A base Farm class from which other Farm classes should be derived.

add_turbine(coordinates)[source]¶

Add a turbine to the farm at the given coordinates.

Creates a new turbine of the same specification as the prototype turbine and places it at coordinates.

Parameters:	coordinates (list()) – The x-y coordinates where the turbine should be placed.

control_array[source]¶

A serialized representation of the farm based on the controls.

Returns:	A serialized representation of the farm based on the controls.
Return type:	numpy.ndarray

friction_function[source]¶

minimum_distance_constraints()[source]¶

Returns an instance of MinimumDistanceConstraints.

Returns:	An instance of InequalityConstraint defining the minimum distance between turbines.
Return type:	opentidalfarm.farm.MinimumDistanceConstraints

number_of_turbines[source]¶

The number of turbines in the farm. :returns: The number of turbines in the farm. :rtype: int

set_turbine_positions(positions)[source]¶

Sets the turbine position and an equal friction parameter.

Parameters:	positions (list) – List of tuples containint x-y coordinates of turbines to be added.

site_boundary_constraints()[source]¶

Raises NotImplementedError if called.

turbine_frictions[source]¶

The friction coefficients of turbines within the farm. :returns: The friction coefficients of turbines within the farm. :rtype: list()

turbine_positions[source]¶

The positions of turbines within the farm. :returns: The positions of turbines within the farm. :rtype: list()

turbine_specification¶

update()[source]¶

Site constraints¶

Minimum distance constraints¶

class opentidalfarm.optimisation_helpers.ConvexPolygonSiteConstraint(farm, vertices)[source]¶

Bases: InequalityConstraint

Generates the inequality constraints for generic polygon constraints. The parameter polygon must be a list of point coordinates that describes the site edges in anti-clockwise order.

function(m)[source]¶

jacobian(m)[source]¶

length()[source]¶

output_workspace()[source]¶

class opentidalfarm.optimisation_helpers.DomainRestrictionConstraints(config, feasible_area, attraction_center)[source]¶

Bases: InequalityConstraint

function(m)[source]¶

jacobian(m)[source]¶

length()[source]¶

opentidalfarm.optimisation_helpers.friction_constraints(config, lb=0.0, ub=None)[source]¶

This function returns the constraints to ensure that the turbine friction controls remain reasonable.

opentidalfarm.optimisation_helpers.get_distance_function(config, domains)[source]¶

opentidalfarm.optimisation_helpers.get_domain_constraints(config, feasible_area, attraction_center)[source]¶

opentidalfarm.optimisation_helpers.position_constraints(config)[source]¶

This function returns the constraints to ensure that the turbine positions remain inside the domain.