Merge pull request #6 from sequoiap/scripted-component-models

Simphony rebuild to enable scripting component models

README.md

@@ -1,16 +1,28 @@
 # Simphony
 A Simulator for Photonic circuits
 
+![Text](./docs/source/_static/images/simphony_logo.jpg)
+
 Authors: [Sequoia Ploeg](https://github.com/sequoiap), 
 [Hyrum Gunther](https://github.com/rumbonium/)
 
 Developed by [CamachoLab](https://camacholab.byu.edu/) at 
 [Brigham Young University](https://www.byu.edu/).
 
+# About this branch
+
+Previous development branches required the component models (from which instances
+are created) to be instantiated first. This attempt tries to keep them as simple
+classes, removing the requirement to instantiate. It also tries to keep the
+s-parameters with the classes, without so many file i/o and parsing algorithms.
+
+# Description
+
 This package is still under development. It initially began as an extension to
 [SiEPIC-Tools](https://github.com/lukasc-ubc/SiEPIC-Tools), but was ported here
 once it became large enough to be considered its own stand-alone project. There
-is a repository, [SiEPIC-Simphony](https://github.com/sequoiap/SiEPIC-Simphony),
+is a repository forked from lukasc-ubc/SiEPIC-Tools, 
+[SiEPIC-Tools](https://github.com/sequoiap/SiEPIC-Tools),
 that integrates Simphony with SiEPIC-Tools and KLayout in order to perform 
 photonic circuit simulations using a layout-driven design methodology.
 
@@ -26,7 +38,7 @@ Python 2 (January 1, 2020), no future compatability is planned.
 ## Documentation
 
 Documentation is built on Sphinx. They can be built using the default files by 
-navigation to the docs directory and running:
+navigating to the docs directory and running:
 
 ```
 make html
@@ -36,9 +48,9 @@ The docs are written in reST. There is a nice syntax guide with guidelines that
 we follow in the documentation 
 [here](https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html). The 
 majority of the documentation is generated from python docstrings written using
-NumPy documentation format.
+the NumPy documentation format.
 
-The changelogs can be found in docs/changelog/. There is a changelog file for 
+Changelogs can be found in docs/changelog/. There is a changelog file for 
 each released version of the software.
 
 ## Tests
@@ -55,7 +67,7 @@ from the toplevel directory.
 ## Developers
 
 This package is available on PyPI and updates are regularly pushed as "minor" 
-or "micro" versions. Before submitting any pull requests, however, you should 
+or "micro" (patch) versions. Before submitting any pull requests, however, you should 
 ensure that a pip installation of your updated package installs and functions 
 properly. To test this, try installing your package locally by removing all 
 installed versions of Simphony (by running ```pip uninstall simphony``` 
@@ -83,16 +95,17 @@ is released on PyPI, the package should have a pull request opened to its
 corresponding release branch (release-MAJOR.MINOR.x). The hierarchy is then
 as follows:
 
-- release.* (stable branch)
+- release-*.*.x (stable branch)
 - master (integration and final testing)
 - feature-name (feature development and bug fixes)
 
 Even if you are the lone developer, we follow the methodology [here](https://softwareengineering.stackexchange.com/a/294048).
 
 Be sure to update the version number manually before pushing each new version 
 to PyPI. Also be sure to amend the changelog. Versions can be pushed to PyPI 
-using the command:
+using the commands:
 
 ```
+python3 setup.py sdist bdist_wheel
 python3 -m twine upload dist/*
 ```

demo/demo.py

@@ -1,12 +1,17 @@
-import simphony
-import matplotlib.pyplot as plt
+# import simphony
+# import matplotlib.pyplot as plt
 
-model = simphony.netlist.ObjectModelNetlist.load('demo/output.json')
-sim = simphony.simulation.Simulation(model)
+# model = simphony.netlist.ObjectModelNetlist.load('demo/output.json')
+# sim = simphony.simulation.Simulation(model)
 
-x, y = sim.getMagnitudeByFrequencyTHz(2, 3)
-plt.plot(x, y)
-plt.show()
+# x, y = sim.getMagnitudeByFrequencyTHz(2, 3)
+# plt.plot(x, y)
+# plt.show()
 
-multi = simphony.simulation.MultiInputSimulation(model)
-multi.multi_input_simulation(inputs=[2])
+# multi = simphony.simulation.MultiInputSimulation(model)
+# multi.multi_input_simulation(inputs=[2])
+
+import simphony.core as core
+
+ring_resonator = core.Component("ring_resonator_radius_5", [1500,1550,1600], [0,0,0], True)
+waveguide = core.Component("waveguide_length_10", [1500,1550,1600], [0,0,0], False)

docs/changelog/0.1.5-changelog.md

@@ -1,4 +1,4 @@
-## [0.1.5] - 2019-06-2 (Scheduled)
+## [0.1.5] - 2019-06-2
 
 ### Added
 - Waveguide parameters now calculated based off new regression model provided by Easton Potokar.

docs/changelog/0.2.0-changelog.md

@@ -0,0 +1,31 @@
+## [0.2.0] - 2019-08-7
+
+Due to a complete code overhaul, this version is incompatible with previous 
+versions of Simphony. Typically, when a release is incompatible, the MAJOR
+version number is bumped. However, since this software is still in the first
+stages of development, bumping the MINOR version symbolizes major changes
+until the version 1 is officially released.
+
+### Added
+- Since we only need two of the 'connect' algorithms from scikit-rf, they were
+    brought over into this library to reduce the number of dependencies.
+- Added test cases using the pytest framework
+- Models are now cached during simulation to avoid repeating calculations
+- Logging is now the method of choice for getting info messages from the program
+- Simulation runtime is now logged at the INFO level
+- Documentation! Built using Sphinx.
+
+### Changed
+- Simphony is now segmented into three modules: core, simulation, and DeviceLibrary
+- New component implementation methods (simphony.core.base.ComponentModel)
+- Rebuilt device library to match new component implementations
+- Device library no long reads data files for s-parameters, as they've been 
+    converted and are now stored as .npz files.
+- [#6](https://github.com/sequoiap/simphony/pull/6): ENHANCEMENT: Framework 
+    rebuild, allows for easier implementation of custom component models and
+    libraries.
+
+### Removed
+- Dependencies on scikit-rf, jsons, and matplotlib have been removed.
+- Netlist export functionality no longer exists since netlists can be 
+    scripted in Python.

docs/source/architecture.rst

@@ -0,0 +1,90 @@
+####################
+Program Architecture
+####################
+
+**********************************
+Components (and Simulation Models)
+**********************************
+
+Simphony attempts to be as agnostic as possible in the implementation of
+optical components. This allows for greater flexibility and extensibility.
+It is for this reason that Simphony separates the idea of a "component" and
+a "simulation model," sometimes simply called a "model."
+
+Components
+==========
+
+A "Component" represents some discrete component that exists in a layout.
+If we consider it from the layout driven design methodology's perspective,
+a component is an object such as a y-branch or a bidirectional coupler that
+has already been designed and simulated on its own. It has a definite shape
+and predefined characteristics that allow it to be simply dropped into
+a layout and operate in a predictable fashion.
+
+Simphony treats components as though they were physical objects stored in a
+library. In other words, it is expected that they will not change shape, that
+they have a pre-specified port numbering system, etc.
+
+Simulation Models
+=================
+
+Simphony does, however,
+separate the concept of a component and a simulation model. A single component
+may have several simulation models associated with it; this allows a single
+component to be simulated with different models; perhaps different fabs create
+the same component in different ways, leading to different results. Perhaps
+there exists a model with data points interpolated from test devices and another
+model based on a neural net. To Simphony, it doesn't matter.
+
+Simulation Models ought to have a nested class called Metadata. It should, at
+a minimum, contain the following fields:
+- simulation_models
+- ports
+
+It has the following format:
+
+class Metadata:
+    simulation_models = [
+        ('containing_module', 'simulation_class_name', 'human_readable_name'),
+        ...
+    ]
+    ports = [INT]
+
+********
+Elements
+********
+
+Now that we understand what Components and Models are, "elements" are Simphony's
+default implementation of some commonly used components. These models are taken
+from SiEPIC's `EBeam PDK <https://github.com/lukasc-ubc/SiEPIC_EBeam_PDK>`_.
+
+New elements can be created and loaded programatically into Simphony. These settings, 
+however, are not persistent, and should be loaded each time Simphony is imported.
+Since element names are required to be unique, you might consider creating a library
+of elements with a prefix to the component name (e.g. in 'ebeam_bdc_te1550', 'ebeam'
+prefixes what the component actually is).
+
+Design Pattern
+==============
+
+Each element is contained within its own Python module (i.e. in a folder). The
+folder bears the component's name. Within the folder is an empty '__init__.py'
+file, a 'models.py' file where simulation models are defined, and a 'component.py'
+file that describes the physical features of the component.
+
+********
+Netlists
+********
+
+**********
+Simulators
+**********
+
+Single Port Simulator
+=====================
+
+Multi Port Simulator
+====================
+
+Monte Carlo Simulator
+=====================

docs/source/conf.py

@@ -107,8 +107,8 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = 'sphinxdoc' 
-html_theme = 'sphinx_rtd_theme'
+html_theme = 'sphinxdoc' 
+# html_theme = 'sphinx_rtd_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

docs/source/index.rst

@@ -12,7 +12,7 @@ Welcome to Simphony's documentation!
 
    reference
    components
-
+   architecture
 
 Indices and tables
 ==================

docs/source/modules.rst

@@ -0,0 +1,7 @@
+simphony
+========
+
+.. toctree::
+   :maxdepth: 4
+
+   simphony

docs/source/reference.rst

@@ -1,15 +1,31 @@
+.. H1
+
 ###
 API
 ###
 
+.. H2
+
 *******
 Netlist
 *******
 
+.. H3
+
 ObjectModelNetlist
 ==================
 
-.. autoclass:: simphony.netlist.ObjectModelNetlist
+.. automodule:: simphony
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. automodule:: simphony.core
+    :members:
+    :inherited-members:
+    :show-inheritance:
+
+.. automodule:: simphony.simulation
     :members:
     :inherited-members:
     :show-inheritance:

docs/source/simphony.DeviceLibrary.ann.rst

@@ -0,0 +1,10 @@
+simphony.DeviceLibrary.ann package
+==================================
+
+Module contents
+---------------
+
+.. automodule:: simphony.DeviceLibrary.ann
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/simphony.DeviceLibrary.ebeam.rst

@@ -0,0 +1,10 @@
+simphony.DeviceLibrary.ebeam package
+====================================
+
+Module contents
+---------------
+
+.. automodule:: simphony.DeviceLibrary.ebeam
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/simphony.DeviceLibrary.rst

@@ -0,0 +1,18 @@
+simphony.DeviceLibrary package
+==============================
+
+Subpackages
+-----------
+
+.. toctree::
+
+   simphony.DeviceLibrary.ann
+   simphony.DeviceLibrary.ebeam
+
+Module contents
+---------------
+
+.. automodule:: simphony.DeviceLibrary
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/simphony.core.rst

@@ -0,0 +1,36 @@
+simphony.core package
+=====================
+
+Submodules
+----------
+
+simphony.core.base module
+-------------------------
+
+.. automodule:: simphony.core.base
+   :members:
+   :undoc-members:
+   :show-inheritance:
+simphony.core.connect module
+----------------------------
+
+.. automodule:: simphony.core.connect
+   :members:
+   :undoc-members:
+   :show-inheritance:
+simphony.core.netlist module
+----------------------------
+
+.. automodule:: simphony.core.netlist
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: simphony.core
+   :members:
+   :undoc-members:
+   :show-inheritance: