# Improve the expressiveness of the python-state interface

The python-state interface is used in many areas of fluidity, and its dynamism is one of fluidity's key advantages in flexibility, power and user-friendliness. However, the interface is quite limited; it only exposes a bare minimum of the Fortran data structures to Python. This project will extend the amount of information exposed so that much more can be done with the python-state interface.

## Blueprint information

- Status:
- Not started

- Approver:
- Patrick Farrell

- Priority:
- Undefined

- Drafter:
- Patrick Farrell

- Direction:
- Needs approval

- Assignee:
- Patrick Farrell

- Definition:
- Discussion

- Series goal:
- None

- Implementation:
- Unknown

- Milestone target:
- None

- Started by

- Completed by

### Related branches

### Related bugs

### Sprints

### Whiteboard

This was the UROP proposal:

Most scientific models concerns themselves with the approximate solution of some differential equation that describes the physics of the problem of interest. For example, in ocean modelling, the Navier-Stokes equations describe nonrelativistic fluid mechanics; some approximation to them is solved for the velocity, pressure, temperature and salinity of the ocean. Typically, the user of a scientific model is not interested in these variables for their own sake, but because they are interested in some diagnostic quantity obtained from them: the average increase in world temperature, the transport of warm water from the tropics, the drag coefficient of a proposed wing, the amount of oil extracted from the ground, etc. Computing such diagnostic quantities is usually the reason why the model was developed (at great expense) in the first place.

In the typical case, the user outputs the model variables to disk as the simulation is being conducted, and then postprocesses the output with some user-written script to compute the desired diagnostic. This has several major disadvantages. Firstly, it is inaccurate, as the model may only output one timestep in ten (to save disk space, which is often a limiting factor). Secondly, it is laborious. Thirdly, the diagnostic computation may itself take significant amounts of computational power, and so the user has to go to the trouble of applying for a second batch of time on a supercomputer to compute them. These disadvantages materially hinder the progress of science, by wasting the valuable time of research scientists.

The Fluidity model, under development at Imperial College, has solved this problem in a previous UROP project (Ralf Perpeet, 2008). The problem is solved by embedding a dynamic programming language (Python) inside the model. The user can supply Python code to compute the diagnostic of interest, which the model can then execute at each timestep. This approach solves all of the problems mentioned previously: there is no disk output, it is computed at every timestep, it is painless and simple for the user, and there is no need to apply for additional supercomputer time.

However, the solution developed is incomplete. In order to let Python manipulate the solution variables, the data structures must be exposed to Python. The solution developed previously is partial because only a very limited subset of Fluidity's data structures are exposed: the user can do simple things such as addition and subtraction, but computing more complicated diagnostics, such as surface integrals, is currently impossible. This project will further expose Fluidity's data structures to Python, solving the problem comprehensively, and facilitating the research of the many tens of scientists and PhD students that use Fluidity.

Use cases:

* Patrick wants to compute the adjoint for the steady drag past a wing. The adjoint functional is coded via the python-state mechanism. However, surface information is not exposed to Python, and so the drag functional cannot be computed.

* Axelle wants to compute a force which is a function of the iterated velocity at a particular point in the domain. However, there is no picker interface, and so the value at that point cannot easily be computed.

* Patrick wants to hand-code the derivative of a functional of interest. That derivative involves, among other things, the mass matrix on the mesh of the field with respect to which we are differentiating. However, no matrices in state are passed to python, and so the mass matrix must be reassembled in python.

* Axelle wants to access the volume integral of a scalar field summed over all the processors in python.

* Axelle wants to represent a solid as a P0 step function in python. This requires the Coordinate field to be remapped onto a P0 function space.