{"name":"waver","display_name":"waver","visibility":"public","icon":"","categories":[],"schema_version":"0.2.0","on_activate":null,"on_deactivate":null,"contributions":{"commands":[{"id":"waver.simulation","title":"simulation","python_name":"waver._dock_widget:simulation","short_title":null,"category":null,"icon":null,"enablement":null},{"id":"waver.sample_fourier","title":"sample_fourier","python_name":"waver._dock_widget:sample_fourier","short_title":null,"category":null,"icon":null,"enablement":null}],"readers":[{"command":"waver.napari_get_reader","filename_patterns":["*"],"accepts_directories":true}],"writers":null,"widgets":[{"command":"waver.simulation","display_name":"simulation","autogenerate":false},{"command":"waver.sample_fourier","display_name":"sample_fourier","autogenerate":false}],"sample_data":null,"themes":null,"menus":{},"submenus":null,"keybindings":null,"configuration":[]},"package_metadata":{"metadata_version":"2.1","name":"waver","version":"0.0.4","dynamic":null,"platform":["UNKNOWN"],"supported_platform":null,"summary":"Wave simulations","description":"# waver\n\n[![License](https://img.shields.io/pypi/l/waver.svg?color=green)](https://github.com/sofroniewn/waver/raw/master/LICENSE)\n[![PyPI](https://img.shields.io/pypi/v/waver.svg?color=green)](https://pypi.org/project/waver)\n[![Python Version](https://img.shields.io/pypi/pyversions/waver.svg?color=green)](https://python.org)\n[![tests](https://github.com/sofroniewn/waver/workflows/tests/badge.svg)](https://github.com/sofroniewn/waver/actions)\n[![codecov](https://codecov.io/gh/sofroniewn/waver/branch/main/graph/badge.svg?token=QBP7K6YUT7)](https://codecov.io/gh/sofroniewn/waver)\n\nRun simulations of the [wave equation](https://en.wikipedia.org/wiki/Wave_equation) in nD on grids of variable speed in Python. This library owes a lot of its design and approach to the [fdtd](https://github.com/flaport/fdtd) library, a Python 3D electromagnetic FDTD simulator.\n\nThis package allows for a fair amount of customization over your wave simulation. You can\n - specify the size and spacing of the grid\n - specify the time step for the simulation, which will be checked to ensure stability of the simulation\n - specify the duration of the simulation\n - setting a variable speed array (one value per grid point) to allow for \"objects\" in your environment\n - set the source of the wave, which can be a point, line, or any (n-1)D subarray\n - record the wave with a detector, which can be the full grid, the full boundary, or a particular boundary\n - use convenience methods to run many simulations with different sources on the same grid and detector combination\n\nYou can use [napari](https://napari.org/), a multi-dimensional image viewer for Python, to allow for easy visualization of the detected wave. Some functionality is also available as a napari plugin to allow for running simulations from a graphical user interface.\n\nResults can look like\n\nhttps://user-images.githubusercontent.com/6531703/128283012-a784ec06-4df9-4ddf-bf4f-e21b927fe4a3.mov\n\n----------------------------------\n\n## Installation\n\nYou can install `waver` via [pip]:\n\n    pip install waver\n\n## Usage\n\n### Convenience Methods\n\nThe most convenient way to use waver is to use one of two convenience methods that will create and run a simulation\nfor you and return the results.\n\nThe first method `run_single_source` allows you to run a single simulation with a single source on one grid and \nrecord the results using a detector. For example\n\n```python\nfrom waver.simulation import run_single_source\n\nsingle_sim_params = {\n    'size': (12.8e-3, 12.8e-3),\n    'spacing': 100e-6,\n    'duration': 80e-6,\n    'min_speed': 343,\n    'max_speed': 686,\n    'speed': 686,\n    'time_step': 50e-9,\n    'temporal_downsample': 2,\n    'location': (6.4e-3, 6.4e-3),\n    'period': 5e-6,\n    'ncycles':1,\n}\n\ndetected_wave, speed_grid = run_single_source(**single_sim_params)\n```\n\nThe second method `run_multiple_sources` allows you to run multiple simulations with multiple sources on the same\ngrid and with the same detector and return the results. For example\n\n```python\nfrom waver.simulation import run_multiple_sources\n\nmulti_sim_params = {\n    'size': (12.8e-3, 12.8e-3),\n    'spacing': 100e-6,\n    'duration': 80e-6,\n    'min_speed': 343,\n    'max_speed': 686,\n    'speed': 686,\n    'time_step': 50e-9,\n    'temporal_downsample': 2,\n    'sources': [{\n        'location': (6.4e-3, 6.4e-3),\n        'period': 5e-6,\n        'ncycles':1,\n    }]\n}\n\ndetected_wave, speed_grid = run_multiple_sources(**multi_sim_params)\n```\n\nThe main difference between these two methods is that `run_multiple_sources` takes a `sources` parameter which takes a list \nof dictionaries with keys corresponding to source related keyword arguments found in `run_single_source`.\n\n### Visualization\n\nIf you want to quickly visualize the results of `run_multiple_sources`, you can use the `run_and_visualize` command which will \nrun the simulation and then launch napari with the results, as seen in [examples/2D/point_source.py](./examples/2D/point_source.py)\n\n```python\nfrom waver.datasets import run_and_visualize\n\nrun_and_visualize(**multi_sim_params)\n```\n\n### Datasets\n\nIf you want to run simulations with on many different speed grids you can use the `generate_simulation_dataset` method as a convenience. The results will be saved to a [zarr](https://zarr.readthedocs.io/en/stable/) file of your chosing. You can then use the `load_simulation_dataset` to load the dataset.\n\n```python\nfrom waver.datasets import generate_simulation_dataset\n\n# Define root path for simulation\npath = './simulation_dataset.zarr'\nruns = 5\n\n# Define a simulation, 12.8mm, 100um spacing\ndataset_sim_params = {\n    'size': (12.8e-3, 12.8e-3),\n    'spacing': 100e-6,\n    'duration': 80e-6,\n    'min_speed': 343,\n    'max_speed': 686,\n    'speed': 'mixed_random_ifft',\n    'time_step': 50e-9,\n    'sources': [{\n        'location': (None, 0),\n        'period': 5e-6,\n        'ncycles':1,\n    }],\n    'temporal_downsample': 2,\n    'boundary': 1,\n    'edge': 1,\n}\n\n# Run and save simulation\ngenerate_simulation_dataset(path, runs, **dataset_sim_params)\n```\n\nThe `generate_simulation_dataset` allows the `speed` to be a string that will specify a particular method of randomly generating speed values for the simulation grid.\n\n### The Simulation Object\n\nIf you'd like to understand in a little bit more detail how a simulation is defined then you might want to use the unerlying simulation object `Simulation` and manually set key objects like the `Source` and `Detector`. A full example of this is as follows\n\n```python\n# Create a simulation\nsim = Simulation(size=size, spacing=spacing, max_speed=max_speed, time_step=time_step)\n\n# Set speed array\nsim.set_speed(speed=speed, min_speed=min_speed, max_speed=max_speed)\n\n# Add source\nsim.add_source(location=location, period=period, ncycles=ncycles, phase=phase)\n\n# Add detector grid\nsim.add_detector(spatial_downsample=spatial_downsample,\n                    boundary=boundary, edge=edge)\n\n# Run simulation\nsim.run(duration=duration, temporal_downsample=temporal_downsample, progress=progress, leave=leave)\n\n# Print simulation wave and speed data\nprint('wave: ', sim.detected_wave)\nprint('speed: ', sim.grid_speed)\n```\n\nNote these steps are done inside the `run_single_source` method for you as a convenience.\n\n## Known Limitations\n\nA [perfectly matched layer](https://en.wikipedia.org/wiki/Perfectly_matched_layer) boundary has recently been added, but might not perform well under all conditions. Additional contributions would be welcome here.\n\nRight now the simulations are quite slow. I'd like to add a [JAX](https://github.com/google/jax) backend, but \nhavn't done so yet. Contributions would be welcome.\n\n## Contributing\n\nContributions are very welcome. Tests can be run with [tox], please ensure\nthe coverage at least stays the same before you submit a pull request.\n\n## License\n\nDistributed under the terms of the [BSD-3] license,\n\"waver\" is free and open source software\n\n## Issues\n\nIf you encounter any problems, please [file an issue] along with a detailed description.\n\n[napari]: https://github.com/napari/napari\n[Cookiecutter]: https://github.com/audreyr/cookiecutter\n[@napari]: https://github.com/napari\n[MIT]: http://opensource.org/licenses/MIT\n[BSD-3]: http://opensource.org/licenses/BSD-3-Clause\n[GNU GPL v3.0]: http://www.gnu.org/licenses/gpl-3.0.txt\n[GNU LGPL v3.0]: http://www.gnu.org/licenses/lgpl-3.0.txt\n[Apache Software License 2.0]: http://www.apache.org/licenses/LICENSE-2.0\n[Mozilla Public License 2.0]: https://www.mozilla.org/media/MPL/2.0/index.txt\n[cookiecutter-napari-plugin]: https://github.com/napari/cookiecutter-napari-plugin\n[file an issue]: https://github.com/sofroniewn/waver/issues\n[napari]: https://github.com/napari/napari\n[tox]: https://tox.readthedocs.io/en/latest/\n[pip]: https://pypi.org/project/pip/\n[PyPI]: https://pypi.org/\n\n\n","description_content_type":"text/markdown","keywords":null,"home_page":"https://github.com/sofroniewn/waver","download_url":null,"author":"Nicholas Sofroniew","author_email":"sofroniewn@gmail.com","maintainer":null,"maintainer_email":null,"license":"BSD-3","classifier":["Development Status :: 2 - Pre-Alpha","Intended Audience :: Developers","Framework :: napari","Topic :: Software Development :: Testing","Programming Language :: Python","Programming Language :: Python :: 3","Programming Language :: Python :: 3.7","Programming Language :: Python :: 3.8","Programming Language :: Python :: 3.9","Operating System :: OS Independent","License :: OSI Approved :: BSD License"],"requires_dist":["magicgui (>=0.2.10)","napari (>=0.4.10)","napari-plugin-engine (>=0.1.4)","numpy","zarr"],"requires_python":">=3.7","requires_external":null,"project_url":null,"provides_extra":null,"provides_dist":null,"obsoletes_dist":null},"npe1_shim":true}