Add magnetic field example

[akaszynski]

Adds two new example datasets generated from emg3d - Minimum working example. @prisae, your stuff is awesome, and I've been wanting to plot magnetic fields for a month now.

>>> import numpy as np
>>> from pyvista import examples
>>> grid = examples.download_dipole_hfield()
>>> data = (grid['hfield_fx']*5E10)
>>> grid['data'] = data
>>> grid.plot(volume=True, opacity='sigmoid_4')

ezgif.com-gif-maker.1.mp4

Bonus

• Improve our opacity parameter docstring in add_volume.
• Improve our invalid opacity error.

Notes

It was entirely not obvious that the scalars had to be between 0 and 255 for this to work. We should either provide more examples or perhaps a warning when the scalars are np.uint8, or ideally both. Volumetric plots are too cool to not have this spelled out.

[adeak]

Very nice!

When I run your example block locally, I get (beside the plot)

2022-07-24 00:13:18.347 (  11.844s) [        5B703740]vtkOpenGLVolumeLookupTa:84    WARN| vtkOpenGLVolumeOpacityTable (0x56ec100): This OpenGL implementation does not support the required texture size of 1048576, falling back to maximum allowed, 16384.This may cause an incorrect lookup table mapping.

>>> pv.Report()

--------------------------------------------------------------------------------
  Date: Sun Jul 24 00:14:03 2022 CEST

                OS : Linux
            CPU(s) : 8
           Machine : x86_64
      Architecture : 64bit
               RAM : 15.5 GB
       Environment : Python
        GPU Vendor : Intel
      GPU Renderer : Mesa Intel(R) UHD Graphics 620 (WHL GT2)
       GPU Version : 4.6 (Core Profile) Mesa 20.3.5

  Python 3.9.2 (default, Feb 28 2021, 17:03:44)  [GCC 10.2.1 20210110]

           pyvista : 0.36.dev0
               vtk : 9.1.0
             numpy : 1.23.0
           imageio : 2.19.3
           appdirs : 1.4.4
            scooby : 0.5.6
        matplotlib : 3.5.2
           IPython : 8.4.0
          colorcet : 3.0.0
           cmocean : 2.0
        ipyvtklink : 0.2.2
             scipy : 1.8.1
        itkwidgets : 0.32.1
              tqdm : 4.64.0
            meshio : 5.3.4
        jupyterlab : 3.4.3
         pythreejs : Version unknown
--------------------------------------------------------------------------------

[akaszynski]

Very nice!

When I run your example block locally, I get (beside the plot)

I have that occur locally as well. Recommend a follow up to clean this up.

Same with the data being between 0-255. That was really frustrating.

[codecov]

Codecov Report

Merging #3058 (a7907a3) into main (984cddb) will increase coverage by 0.00%.
The diff coverage is 100.00%.

@@           Coverage Diff           @@
##             main    #3058   +/-   ##
=======================================
  Coverage   95.74%   95.74%           
=======================================
  Files          96       96           
  Lines       20422    20431    +9     
=======================================
+ Hits        19553    19562    +9     
  Misses        869      869           

[prisae]

This is awesome @akaszynski ! I will have to try this with a more complex model, such as the SEG salt model: https://emsig.xyz/emg3d-gallery/gallery/models/SEG-EAGE_3D_salt_model.html

[prisae]

How did you store the *.vtk-files? (emg3d/dipole/efield.vtk and emg3d/dipole/hfield.vtk)

[akaszynski]

How did you store the *.vtk-files? (emg3d/dipole/efield.vtk and emg3d/dipole/hfield.vtk)

These examples were generated from the following script:
https://github.com/pyvista/vtk-data/tree/master/Data/emg3d/dipole

If you have a submission, I'd love for them to be stored at pyvista/vtk-data.

[prisae]

How did you store the *.vtk-files? (emg3d/dipole/efield.vtk and emg3d/dipole/hfield.vtk)

These examples were generated from the following script: https://github.com/pyvista/vtk-data/tree/master/Data/emg3d/dipole

If you have a submission, I'd love for them to be stored at pyvista/vtk-data.

Interesting. emg3d uses under the hood discretize for the meshing (if installed). @banesullivan introduced once a to_vtk-mixin for it: https://discretize.simpeg.xyz/en/main/api/generated/discretize.mixins.InterfaceVTK.html . However, this is only implemented for cell-centred properties. As the fields live on their corresponding edges, one would first have to interpolate the fields to cell centres, before exporting:

grid.write_vtk(
    'efield',
    models={
        'efield_fx': abs(grid.average_edge_x_to_cell * efield.fx.ravel('F')),
        'efield_fy': abs(grid.average_edge_y_to_cell * efield.fz.ravel('F')),
        'efield_fz': abs(grid.average_edge_z_to_cell * efield.fy.ravel('F')),
    },
)

[akaszynski]

I'll have to use that in the future, though a direct tie in with pyvista seems possible if you ever wanted to be able to directly plot the fields.

[prisae]

That could be cool. Currently I have, consciously, no plotting routines implemented in emg3d at all. The available plotting happens through discretize.

Besides volume plot would, of course, stream plots be very interesting for electromagnetic fields.

(from https://www.digitalearthlab.com/8-marine-csem-visualising-the-fields/)

Also cool: https://www.youtube.com/watch?v=EPxNdESwQP0

[akaszynski]

Ended up going with magpylib for now.

There were issues with grid alignment with emg3d. I can return to it later in a follow-up PR.

[prisae]

Hm. Interesting. emg3d uses discretize for the meshing. So that would mean that everything of SimPEG has also this alignment problem...? But what do you mean with alignment issues? The fields in the different directions live on different edges, so they are interpolated if you want the full tensor. But that is all implemented.

[akaszynski]

Hm. Interesting. emg3d uses discretize for the meshing. So that would mean that everything of SimPEG has also this alignment problem...? But what do you mean with alignment issues? The fields in the different directions live on different edges, so they are interpolated if you want the full tensor. But that is all implemented.

I'd like to have both. I'll open an issue in emg3d.

[akaszynski]

@prisae, I think my issue is I'm not implementing it correctly. I'll fix it to:

grid.write_vtk(
    'efield',
    models={
        'efield_fx': abs(grid.average_edge_x_to_cell * efield.fx.ravel('F')),
        'efield_fy': abs(grid.average_edge_y_to_cell * efield.fz.ravel('F')),
        'efield_fz': abs(grid.average_edge_z_to_cell * efield.fy.ravel('F')),
    },
)

Docs are down at the moment, see emsig/emg3d#308.

[prisae]

That looks good @akaszynski . The fields indeed live on the corresponding edges. So if you want to use them together it is the easiest to move them to cell centers first.

[akaszynski]

This will have to miss this release, and I'd like to make sure we get emg3d in as well here.

[akaszynski]

Recommending splitting this up into two PRs to get this merged. This PR will incorporate the magpylib example from Coil Field Lines.

@prisae, if you can get me a vtk dataset that I can use as a vtk file, I'll be able to generate that streamline example. Please post an issue and I can add it. I'm super busy at the moment and can't investigate this further, but I would love to include another example.

[akaszynski]

@tkoyama010, would appreciate another review when you get a chance.

[tkoyama010]

LGTM