What is the defined way of running <basic swarm>.add_particles_with_global_coordinates() in parallel?

[jcgraciosa]

Suppose we add three particles using add_particles_with_global_coordinates():

xy_st = np.array([[0.5, 0.33], [1.5, 0.33], [1.5, 0.50]])

basic_swarm.add_particles_with_coordinates(xy_st, migrate = True)

In serial, this is not a problem.
In parallel, say N ranks, should we split xy_st into N groups before calling add_particles_with_coordinates?
Currently, not splitting xy_st and running it in parallel results to the particles being duplicated in each rank.

[lmoresi]

This method is designed to add particles without checking that the points are local. If we have pre-computed points across the domain, the add_particles_with_coordinates would be a better choice because it would ensure no unintended duplication.

We can use it for things like the global evaluation of values anywhere in the domain. That particular use case might legitimately create duplicate points and we would need to honour them.

We might also use this for transferring mesh values from one mesh to a differently-distributed, adapted mesh. In this case we don't expect any duplicate points because of the way they were derived, but it's exactly the same global-evaluation as above.

If this is super-confusing, then perhaps it should be a hidden method that is only for use internally by things like the global-evaluation tools.

[lmoresi]

Status update

The design decision from the earlier discussion stands: add_particles_with_global_coordinates() is intended for cases where all ranks receive the same global coordinate array and the method handles distribution internally. The current behavior (each rank adds all points, then migration sorts them) is correct but may appear to create duplicates before migration runs.

For the use case of adding pre-partitioned points where each rank has different coordinates, add_particles_with_coordinates() (without "global") is the right method.

We should clarify this distinction in the documentation. The "global" variant may also benefit from being marked as internal-only (prefixed with _) since its primary use case is internal operations like global evaluation and mesh transfer, not direct user calls.

Leaving open as a documentation/API cleanup item.

[lmoresi]

Addressed in PR #66 (merged to development). The docstrings for add_particles_with_coordinates and add_particles_with_global_coordinates now clearly document their parallel semantics. Available for testing on the development branch.