Merge remote-tracking branch 'origin/master'

Author: andrewtliew

README.md

@@ -1,46 +1,109 @@
 # compas
 
-This is the main library of the compas framework.
-It consists of the following Python packages:
+This is the public repository of the main library of the **compas** framework.
+The **compas** framework is an open-source, Python-based framework for computational
+research and collaboration in architecture, engineering and digital fabrication.
 
-* compas
-* compas_rhino
-* compas_blender
-* compas_maya
-* compas_grasshopper
-* compas_dynamo
+The main library consists of a core package (**compas**) and several additional
+packages for integration of the core functionality in CAD software (**compas_blender**,
+**compas_maya** and **compas_rhino**). The core package defines all *real* functionality.
+The CAD packages simply provide a unified framework for processing, visualising,
+and interacting with datastructures, and for building user interfaces in different
+CAD software.
+
+The complete documentation of the compas framework is available here: https://compas-dev.github.io/.
 
-The complete documentation of the compas framework is available here: 
-[compas-framework].
 
 ## Getting Started
 
-To get started with the compas framework, first clone or download this repository. Then modify your `PYTHONPATH` to make the packages available from the location of the download path, or use the `setup.py` script to install them globally.
+**compas** does not yet have an installer or setup script. A detailed description
+of how to get started by cloning the repository and configuring your system
+is available through the documentation: https://compas-dev.github.io/gettingstarted.html
 
-To modify your `PYTHONPATH` do something similar to the following:
+In short:
 
-```
-$ echo "export PYTHONPATH=/path/to/packages:$PYTHONPATH" >> ~/.bash_profile
+* clone the repository
+* add the compas source folder to your ``PYTHONPATH``
+* verify your setup
+
+For example, start Python from the command line, and try
+
+```python
+>>> import compas
+>>> compas.verify()
 ```
 
-To run the stup script, and install the compas framework packages into the site packages folder of your Python installation, do:
+
+This will produce something like the following:
 
 ```
-$ python setup.py install
+-------------------------------------------------------------------------------
+Checking required packages...
+
+All required packages are installed!
+
+Checking optional packages...
+
+The following optional packages are not installed:
+- pycuda
+- pyopengl
+- pyside
+
+-------------------------------------------------------------------------------
 ```
 
-For a complete overview of all installation instructions and options, and for further configuration possibilities, see the [Getting Started](https://compas-dev.github.io/gettingstarted.html) section of the main documentation website.
 
 ## Dependencies
 
+**compas** has very few dependencies and most of them are included in a scientific
+Python distribution such as Anaconda or EPD.
+
+| package               | dependencies             | exceptions
+| --------------------- | ------------------------ | -------------------------- 
+| compas.com            | -                        | matlab (``MatlabEngine``, ``MatlabSession``), paramiko (``ssh``)
+| compas.datastructures | -                        |
+| compas.files          | -                        |
+| compas.geometry       | -                        | NumPy, SciPy (all functions with a ``_numpy`` suffix)
+| compas.hpc            | Numba, PyCuda, PyOpenCL  | 
+| compas.interop        | -                        |
+| compas.numerical      | NumPy, SciPy             |
+| compas.plotters       | Matplotlib               |
+| compas.topology       | -                        | NumPy, SciPy (all functions with a ``_numpy`` suffix), planarity (``network_is_planar``), NetworkX (``network_embed_in_plane``)
+| compas.utilities      | -                        | imageio (``gif_from_images``)
+| compas.viewers        | PyOpenGL, PySide         |
+
+
 ## First Steps
 
-## Examples
+Some useful resources for first explorations:
+
+* https://compas-dev.github.io/main/examples.html
+* https://compas-dev.github.io/main/tutorial.html
+* https://compas-dev.github.io/main/reference.html
+
+
+## Questions and feedback
+
+The **compas** framework has a forum: http://forum.compas-framework.org/
+for questions and discussions.
+
+
+## Issue tracker
+
+If you find a bug, please [file a report](https://github.com/compas-dev/compas/issues).
+
+
+## License
+
+The main library of **compas** is [released under the MIT license](https://compas-dev.github.io/license.html).
+
+
+## Contact
+
+The **compas** framework is developed by the Block Research Group at ETH Zurich,
+with the support of the NCCR (National Centre for Competence in Research) in *Digital fabrication*.
+Main contributors are Tom Van Mele, Andrew Liew, Tomás Méndez and Matthias Rippmann.
 
-## Attribution
+For questions, comments, requests, ..., please [contact the main developers directly](mailto:[email protected],[email protected],[email protected],[email protected]).
 
-## Known Issues
 
-[compas-framework]: https://compas-dev.github.io/
-[compas-main]: https://compas-dev.github.io/compas/index.html
-[compas-packages]: https://compas-dev.github.io/packages/index.html

src/compas/__init__.py

@@ -145,7 +145,8 @@ def verify():
     ]
     current = installed()
 
-    print('Checking required packages...')
+    print('=' * 80)
+    print('Checking required packages...\n')
     issues = []
     for package in requirements:
         if package not in current:
@@ -157,7 +158,7 @@ def verify():
     else:
         print('All required packages are installed.')
 
-    print('\nChecking optional packages...')
+    print('\nChecking optional packages...\n')
     issues = []
     for package in optional:
         if package not in current:
@@ -168,6 +169,7 @@ def verify():
             print('- {}'.format(package))
     else:
         print('All optional packages are installed.')
+    print('=' * 80)
     print()
 
 

src/compas/com/__init__.py

@@ -7,6 +7,8 @@
 
 .. module:: compas.com
 
+:mod:`compas.com` provides functionality for communicating with external software.
+
 
 Matlab
 ======

src/compas/com/matlab_/client.py

@@ -23,15 +23,6 @@
 class MatlabClient(object):
     """Communicate with Matlab through Windows' COM interface.
 
-    Note
-    ----
-    This implementation uses Windows' COM interface to communicate with Matlab.
-    Therefore, it is obviously only available on Windows.
-    When an instance of this class is created, it automatically connects to Matlab,
-    and initializes a lease that keeps the interface alive for at least 5 minutes
-    such that subsequent calls can be executed immediately.
-    After every call, the lease is renewed...
-
     Parameters
     ----------
     verbose : bool
@@ -44,6 +35,15 @@ class MatlabClient(object):
         The name of the Matlab workspace.
         Default is ``'base'``.
 
+    Notes
+    -----
+    This implementation uses Windows' COM interface to communicate with Matlab.
+    Therefore, it is obviously only available on Windows.
+    When an instance of this class is created, it automatically connects to Matlab,
+    and initializes a lease that keeps the interface alive for at least 5 minutes
+    such that subsequent calls can be executed immediately.
+    After every call, the lease is renewed...
+
     Examples
     --------
     >>> matlab = MatlabClient(interactive=True)
@@ -61,9 +61,9 @@ class MatlabClient(object):
 
     See Also
     --------
-    * compas.com.mlab.MatlabEngine
-    * compas.com.mlab.MatlabSession
-    * compas.com.mlab.MatlabProcess
+    compas.com.mlab.MatlabEngine
+    compas.com.mlab.MatlabSession
+    compas.com.mlab.MatlabProcess
 
     """
 

src/compas/com/matlab_/engine.py

@@ -27,8 +27,7 @@ def __init__(self, message=None):
 
 
 class MatlabEngine(object):
-    """Communicate with Matlab through the MATLAB engine [mathworks2017a]_, [mathworks2017b]_,
-        [mathworks2017c]_, [mathworks2017d]_, [mathworks2017e]_.
+    """Communicate with Matlab through the MATLAB engine.
 
     Attributes
     ----------
@@ -38,6 +37,23 @@ class MatlabEngine(object):
     session_name : str
         The name of the current Matlab session.
 
+    Notes
+    -----
+    For more info, see [1]_, [2]_, [3]_, [4]_, [5]_.
+
+    References
+    ----------
+    .. [1] MathWorks, 2017. *MATLAB APY for Python*.
+           Available at: https://ch.mathworks.com/help/matlab/matlab-engine-for-python.html
+    .. [2] MathWorks, 2017. *Pass Data to MATLAB from Python*.
+           Available at: https://ch.mathworks.com/help/matlab/matlab_external/pass-data-to-matlab-from-python.
+    .. [3] MathWorks, 2017. *Use MATLAB Arrays in Python*.
+           Available at: https://ch.mathworks.com/help/matlab/matlab_external/use-matlab-arrays-in-python.html
+    .. [4] MathWorks, 2017. *Use MATLAB Engine Workspace in Python*.
+           Available at: https://ch.mathworks.com/help/matlab/matlab_external/use-the-matlab-engine-workspace-in-python.html
+    .. [5] MathWorks, 2017. *Call MATLAB Functions from Python*.
+           Available at: https://ch.mathworks.com/help/matlab/matlab_external/call-matlab-functions-from-python.html
+
     Examples
     --------
     >>> matlab = MatlabEngine()

src/compas/com/matlab_/process.py

@@ -35,35 +35,37 @@ def __init__(self, message=None):
 class MatlabProcess(object):
     """Communicate with Matlab through a subprocess.
 
-    Parameters:
-        matlab_exec (str, optional) : Path to the Matlab executable.
-            Defaults to `matlab`.
-        ws_data (dict, optional) : Workspace data to be loaded at startup.
-            Defaults to an empty dict.
-        ws_filename (str, optional) : Filename for workspace storage.
-            Defaults to `'./workspace.mat'`.
-
-    Examples:
-        >>> m = MatlabProcess()
-
-        >>> m.start()
-        >>> m.write_value('a', 37)
-        >>> m.run_command('tf = isprime(a);')
-        >>> m.read_workspace()
-        >>> m.stop()
-        >>> print(m.ws_data)
-
-        >>> m.write_value('a', 17)
-        >>> m.run_command('res = isprime(a);')
-        >>> m.read_value('res')
-        True
-
-        >>> m.run_command('res = isprime(a);', ivars={'a': 17})
-        >>> m.read_value('res')
-        True
-
-        >>> m.run_command('res = isprime(a);', ivars={'a': 17}, ovars={'res': None})
-        {'res': True}
+    Parameters
+    ----------
+    matlab_exec : str, optional
+        Path to the Matlab executable. Defaults to ``matlab``.
+    ws_data : dict, optional
+        Workspace data to be loaded at startup. Defaults to an empty dict.
+    ws_filename : str, optional
+        Filename for workspace storage. Defaults to ``'./workspace.mat'``.
+
+    Examples
+    --------
+    >>> m = MatlabProcess()
+
+    >>> m.start()
+    >>> m.write_value('a', 37)
+    >>> m.run_command('tf = isprime(a);')
+    >>> m.read_workspace()
+    >>> m.stop()
+    >>> print(m.ws_data)
+
+    >>> m.write_value('a', 17)
+    >>> m.run_command('res = isprime(a);')
+    >>> m.read_value('res')
+    True
+
+    >>> m.run_command('res = isprime(a);', ivars={'a': 17})
+    >>> m.read_value('res')
+    True
+
+    >>> m.run_command('res = isprime(a);', ivars={'a': 17}, ovars={'res': None})
+    {'res': True}
 
     """
 

src/compas/com/matlab_/session.py

@@ -24,27 +24,39 @@ def __init__(self, message=None):
 class MatlabSession(object):
     """Communicate with Matlab through a shared session.
 
+    Parameters
+    ----------
+    name : str
+        Name of a running Matlab session.
+
+    Notes
+    -----
     Note that the Matlab engine for Python is only available since R2014b.
     For earlier versions of Matlab, use ``MatlabProcess`` instead.
 
-    For more information,
-    see `Connect Python to Running MATLAB Session <https://ch.mathworks.com/help/matlab/matlab_external/connect-python-to-running-matlab-session.html>`_
+    For more information, see [1]_
+
+    References
+    ----------
+    .. [1] MathWorks, 2017. *Connect Python to Running MATLAB Session*.
+           Available at https://ch.mathworks.com/help/matlab/matlab_external/connect-python-to-running-matlab-session.html
 
-    Examples:
-        >>> m = MatlabSession()
-        >>> m.session_name
-        'MATLAB_13404'
-        >>> m.isprime(37)
-        True
+    Examples
+    --------
+    >>> m = MatlabSession()
+    >>> m.session_name
+    'MATLAB_13404'
+    >>> m.isprime(37)
+    True
 
-        .. code-block:: python
+    .. code-block:: python
 
-            # execute `matlab -nosplash -r "matlab.engine.shareEngine('MATLAB_xxx')"`
-            # to connect to an existing named session
+        # execute `matlab -nosplash -r "matlab.engine.shareEngine('MATLAB_xxx')"`
+        # to connect to an existing named session
 
-        >>> m = MatlabSession('MATLAB_xxx')
-        >>> m.isprime(37)
-        True
+    >>> m = MatlabSession('MATLAB_xxx')
+    >>> m.isprime(37)
+    True
 
     """
 

src/compas/com/rhino/client.py

@@ -29,17 +29,16 @@ class RhinoClientError(Exception):
 class RhinoClient(object):
     """Communicate with Rhino through Window's COM interface.
 
-    Warning:
-        This only works on Windows!
-
-    Parameters:
-        delay_start (bool, optional) : Delay the creation of a COM interface.
-            Default is ``False``.
-
-    Examples:
-        >>> r = RhinoApp()
-        >>> r.AddPoint(0, 0, 0)
-        <guid>
+    Parameters
+    ----------
+    delay_start : bool, optional
+        Delay the creation of a COM interface. Default is ``False``.
+
+    Examples
+    --------
+    >>> r = RhinoApp()
+    >>> r.AddPoint(0, 0, 0)
+    <guid>
 
     """