{
  "name": "waver",
  "display_name": "waver",
  "visibility": "public",
  "icon": "",
  "categories": [],
  "schema_version": "0.2.1",
  "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
}