Skip to content

This PR fixes the docstrings in cython #249

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

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from
Open

This PR fixes the docstrings in cython #249

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
49 changes: 35 additions & 14 deletions cyprecice/cyprecice.pyx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,12 +39,13 @@ cdef class Participant:
"""
Main Application Programming Interface of preCICE.
To adapt a solver to preCICE, follow the following main structure:
- Create an object of Participant with Participant()
- Initialize preCICE with Participant::initialize()
- Advance to the next (time)step with Participant::advance()
- Finalize preCICE with Participant::finalize()
- We use solver, simulation code, and participant as synonyms.
- The preferred name in the documentation is participant.

- Create an object of Participant with Participant()
- Initialize preCICE with Participant::initialize()
- Advance to the next (time)step with Participant::advance()
- Finalize preCICE with Participant::finalize()
- We use solver, simulation code, and participant as synonyms.
- The preferred name in the documentation is participant.
"""

# fake __init__ needed to display docstring for __cinit__ (see https://stackoverflow.com/a/42733794/5158031)
Expand Down Expand Up @@ -105,10 +106,10 @@ cdef class Participant:
method to finally exchange the data.

This function handles:
- Parallel communication to the coupling partner/s is setup.
- Meshes are exchanged between coupling partners and the parallel partitions are created.
- [Serial Coupling Scheme] If the solver is not starting the simulation, coupling data is received
from the coupling partner's first computation.

- Parallel communication to the coupling partner/s is setup.
- Meshes are exchanged between coupling partners and the parallel partitions are created.
- [Serial Coupling Scheme] If the solver is not starting the simulation, coupling data is received from the coupling partner's first computation.

Returns
-------
Expand Down Expand Up @@ -206,8 +207,10 @@ cdef class Participant:
"""
Checks if the coupled simulation is still ongoing.
A coupling is ongoing as long as
- the maximum number of timesteps has not been reached, and
- the final time has not been reached.

- the maximum number of timesteps has not been reached, and
- the final time has not been reached.

The user should call finalize() after this function returns false.

Returns
Expand All @@ -227,8 +230,9 @@ cdef class Participant:
"""
Checks if the current coupling timewindow is completed.
The following reasons require several solver time steps per coupling time step:
- A solver chooses to perform subcycling.
- An implicit coupling timestep iteration is not yet converged.

- A solver chooses to perform subcycling.
- An implicit coupling timestep iteration is not yet converged.

Returns
-------
Expand Down Expand Up @@ -790,27 +794,31 @@ cdef class Participant:
Examples
--------
Write scalar data for a 2D problem with 5 vertices:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> vertex_ids = [1, 2, 3, 4, 5]
>>> values = np.array([v1, v2, v3, v4, v5])
>>> participant.write_data(mesh_name, data_name, vertex_ids, values)

Write vector data for a 2D problem with 5 vertices:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> vertex_ids = [1, 2, 3, 4, 5]
>>> values = np.array([[v1_x, v1_y], [v2_x, v2_y], [v3_x, v3_y], [v4_x, v4_y], [v5_x, v5_y]])
>>> participant.write_data(mesh_name, data_name, vertex_ids, values)

Write vector data for a 3D (D=3) problem with 5 (N=5) vertices:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> vertex_ids = [1, 2, 3, 4, 5]
>>> values = np.array([[v1_x, v1_y, v1_z], [v2_x, v2_y, v2_z], [v3_x, v3_y, v3_z], [v4_x, v4_y, v4_z], [v5_x, v5_y, v5_z]])
>>> participant.write_data(mesh_name, data_name, vertex_ids, values)

Write vector data for a 3D (D=3) problem with 5 (N=5) vertices, where the values are provided as a list of tuples:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> vertex_ids = [1, 2, 3, 4, 5]
Expand Down Expand Up @@ -873,6 +881,7 @@ cdef class Participant:
Examples
--------
Read scalar data for a 2D problem with 5 vertices:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> vertex_ids = [1, 2, 3, 4, 5]
Expand All @@ -882,6 +891,7 @@ cdef class Participant:
>>> (5, )

Read vector data for a 2D problem with 5 vertices:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> vertex_ids = [1, 2, 3, 4, 5]
Expand All @@ -891,6 +901,7 @@ cdef class Participant:
>>> (5, 2)

Read vector data for a 3D system with 5 vertices:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> vertex_ids = [1, 2, 3, 4, 5]
Expand Down Expand Up @@ -951,13 +962,15 @@ cdef class Participant:
Examples
--------
Write scalar data for a 2D problem with 5 vertices:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> coordinates = np.array([[c1_x, c1_y], [c2_x, c2_y], [c3_x, c3_y], [c4_x, c4_y], [c5_x, c5_y]])
>>> values = np.array([v1, v2, v3, v4, v5])
>>> participant.write_and_map_data(mesh_name, data_name, coordinates, values)

Write scalar data for a 2D problem with 5 vertices, where the coordinates are provided as a list of tuples, and the values are provided as a list of scalars:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> coordinates = [(c1_x, c1_y), (c2_x, c2_y), (c3_x, c3_y), (c4_x, c4_y), (c5_x, c5_y)]
Expand Down Expand Up @@ -1008,6 +1021,7 @@ cdef class Participant:
Examples
--------
Read scalar data for a 2D problem with 2 vertices:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> coordinates = np.array([[1.0, 1.0], [2.0, 2.0]])
Expand All @@ -1017,6 +1031,7 @@ cdef class Participant:
>>> (2, )

Read scalar data for a 2D problem with 2 vertices, where the coordinates are provided as a list of tuples:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> coordinates = [(1.0, 1.0), (2.0, 2.0)]
Expand Down Expand Up @@ -1075,20 +1090,23 @@ cdef class Participant:
Examples
--------
Write gradient vector data for a 2D problem with 2 vertices:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> vertex_ids = [1, 2]
>>> gradients = np.array([[v1x_dx, v1y_dx, v1x_dy, v1y_dy], [v2x_dx, v2y_dx, v2x_dy, v2y_dy]])
>>> participant.write_gradient_data(mesh_name, data_name, vertex_ids, gradients)

Write gradient vector data for a 2D problem with 2 vertices, where the gradients are provided as a list of tuples:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> vertex_ids = [1, 2]
>>> gradients = [(v1x_dx, v1y_dx, v1x_dy, v1y_dy), (v2x_dx, v2y_dx, v2x_dy, v2y_dy)]
>>> participant.write_gradient_data(mesh_name, data_name, vertex_ids, gradients)

Write vector data for a 3D problem with 2 vertices:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> vertex_ids = [1, 2]
Expand Down Expand Up @@ -1134,6 +1152,7 @@ cdef class Participant:
Examples
--------
Check if gradient data is required for a data:

>>> mesh_name = "MeshOne"
>>> data_name = "DataOne"
>>> participant.is_gradient_data_required(mesh_name, data_name)
Expand Down Expand Up @@ -1238,6 +1257,7 @@ cdef class Participant:
Examples
--------
Start a profiling section with the event name "EventOne":

>>> event_name = "EventOne"
>>> participant.start_profiling_section(event_name)
"""
Expand All @@ -1250,6 +1270,7 @@ cdef class Participant:
Examples
--------
Stop the last profiling section:

>>> participant.stop_last_profiling_section()
"""
self.thisptr.stopLastProfilingSection()
Expand Down