Update README and build instructions on Mac

.github/CONTRIBUTING.rst

@@ -62,9 +62,9 @@ The only required requisite is that the toolchain needs to support C++14.
 
 **Mac**
 
-On Mac we have various options depending on the compiler we wanted to use.
-If we want to use Apple's clang compiler, we need to install an extra library for
-supporting OpenMP: libomp. CMake build system will warn you otherwise.
+On Mac we have various options depending on the compiler we want to use.
+If we want to use Apple's Clang compiler, we need to install an extra library for
+supporting OpenMP: libomp. The CMake build system will warn you otherwise.
 To install it manually:
 you can type:
 
@@ -81,6 +81,13 @@ We do recommend installing OpenBLAS, which is our default choice:
 CMake build system will search for other BLAS implementation alternatives if
 OpenBLAS is not installed in the system.
 
+You further need to have Command Line Tools installed on MacOS:
+
+.. code::
+
+   $ xcode-select —install
+
+
 **Linux (Ubuntu >= 16.04)**
 
 Most of the major distributions come with a BLAS and LAPACK library implementation,
@@ -109,13 +116,15 @@ There are two ways of building Aer simulators, depending on our goal they are:
 1. Build Terra compatible addon.
 2. Build standalone executable
 
-Terra addon
+**Terra addon**
+
 For the former, we just need to call the ``setup.py`` script:
 
 .. code::
 
   qiskit-aer$ python ./setup.py bdist_wheel
 
+
 We are using `scikit-build <https://scikit-build.readthedocs.io/en/latest/>`_ as a substitute of `setuptools`.
 This is basically the glue between ``setuptools`` and ``CMake``, so there are various options to pass variables to ``CMake``, and 
 the undelying build system (depending on your platform). The way to pass variables is:
@@ -128,21 +137,29 @@ So a real example could be:
 
 .. code::
 
-    qiskit-aer$ python ./setup.py bdist_wheel -- -DSTATIC_LINKING=True -- -j8
+    qiskit-aer$ python ./setup.py bdist_wheel -- -j8
 
 This is setting the CMake variable ``STATIC_LINKING`` to value ``True`` so CMake will try to create an statically linked cython
 library, and is passing ``-j8`` flag to the underlaying build system, which in this case is Makefile, telling it that we want to
 build in parallel, using 8 processes.
 
+*N.B. on MacOS:*, you may need to turn off static linking and specify your platform name, e.g.:
+
+.. code::
+
+   python ./setup.py bdist_wheel --plat-name macosx-10.9-x86_64 -- -DSTATIC_LINKING=False -- -j8
+
+
 After this command is executed successfully, we will have a wheel package into the ``dist/`` directory, so next step is installing it:
 
 .. code::
 
   qiskit-aer/$ cd dist
-  qiskit-aer/dist$ pip install qiskit_aer-0.0.0-cp36-cp36m-linux_x86_64.whl
+  qiskit-aer/dist$ pip install qiskit_aer-<...>.whl
+
 
+**Standalone executable**
 
-Standalone executable
 If we want to build an standalone executable, we have to use CMake directly.
 The preferred way CMake is meant to be used, is by setting up an "out of source" build.
 So in order to build our standalone executable, we have to follow these steps:

README.md

@@ -1,42 +1,92 @@
-# Qiskit-Aer
+# Qiskit Aer
 
-This is a working draft for the Qiskit-Aer simulator framework for Qiskit-Terra. This is the development repository and has no guarantee of stability or correctness.
+[![PyPI](https://img.shields.io/pypi/v/qiskit.svg)](https://pypi.python.org/pypi/qiskit-aer)
 
+**Qiskit** is an open-source framework for working with noisy intermediate-scale quantum computers (NISQ) at the level of pulses, circuits, and algorithms.
 
-## Repository contents
+Qiskit is made up of elements that each work together to enable quantum computing. This element is **Aer**, which provides high-performance quantum computing simulators with realistic noise models.
 
-* The **qiskit_aer** folder contains the Qiskit-Aer python module for use with Qiskit-Terra.
-* The **cmake** folder contains cmake scripts for building the simulator
-* The **src** folder contains the C++ source files for building the simulator.
-* The **contrib** folder for external contributions.
-* The **test** folder contains simulator unit tests.
+## Installation
 
-## Documentation
+We encourage installing Qiskit via the PIP tool (a python package manager), which installs all Qiskit elements, including this one.
 
-There's a [contributing guide](https://github.ibm.com/IBMQuantum/qiskit-aer/blob/master/.github/CONTRIBUTING.rst)
-with more detailed information about the project.
+```bash
+pip install qiskit
+```
 
-For tutorials on using Qiskit Aer visit the [qiskit-tutorials](https://github.com/Qiskit/qiskit-tutorials/tree/master/qiskit/aer) Github repository.
+PIP will handle all dependencies automatically for us and you will always install the latest (and well-tested) version.
+
+To install from source, follow the instructions in the [contribution guidelines](.github/CONTRIBUTING.rst).
 
-## Installation
 
-Follow these steps for installing the **Qiskit Aer** package:
 
-```bash
-qiskit-aer$ pip install -r requirements-dev.txt
-qiskit-aer$ python ./setup.py bdist_wheel
+## Simulating your first quantum program with Qiskit Aer
+Now that you have Qiskit Aer installed, you can start simulating quantum circuits with noise. Here is a basic example:
+
+```
+$ python
 ```
 
-Once the build finishes, we just need to install the wheel package in our
-preferred python virtual environment:
+```python
+from qiskit import QuantumRegister, ClassicalRegister, QuantumCircuit, execute
+from qiskit import Aer, IBMQ  # import the Aer and IBMQ providers
+from qiskit.providers.aer import noise  # import Aer noise models
 
-```bash
-qiskit-aer$ pip install dist/qiskit_aer-0.1.0-cp36-cp36m-linux_x86_64.whl
+# Choose a real device to simulate
+IBMQ.load_accounts()
+device = IBMQ.get_backend('ibmq_16_melbourne')
+properties = device.properties()
+coupling_map = device.configuration().coupling_map
+
+# Generate an Aer noise model for device
+noise_model = noise.device.basic_device_noise_model(properties)
+basis_gates = noise_model.basis_gates
+
+# Generate a quantum circuit
+q = QuantumRegister(2)
+c = ClassicalRegister(2)
+qc = QuantumCircuit(q, c)
+
+qc.h(q[0])
+qc.cx(q[0], q[1])
+qc.measure(q, c)
+
+# Perform noisy simulation
+backend = Aer.get_backend('qasm_simulator')
+job_sim = execute(qc, backend,
+                  coupling_map=coupling_map,
+                  noise_model=noise_model,
+                  basis_gates=basis_gates)
+sim_result = job_sim.result()
+
+print(sim_result.get_counts(qc))
 ```
 
-We are all set! Now we ready to start using the simulator in our python code:
 ```python
-from qiskit import Aer  # Imports the Aer Provider
-
-Aer.backends() # List of the backends
+{'11': 412, '00': 379, '10': 117, '01': 116}
 ```
+
+
+## Contribution guidelines
+
+If you'd like to contribute to Qiskit Aer, please take a look at our
+[contribution guidelines](.github/CONTRIBUTING.rst). This project adheres to Qiskit's [code of conduct](.github/CODE_OF_CONDUCT.rst). By participating, you are expect to uphold this code.
+
+We use [GitHub issues](https://github.com/Qiskit/qiskit-aer/issues) for tracking requests and bugs. 
+Please use our [slack](https://qiskit.slack.com) for discussion. To join our Slack community use the [link](https://join.slack.com/t/qiskit/shared_invite/enQtNDc2NjUzMjE4Mzc0LTMwZmE0YTM4ZThiNGJmODkzN2Y2NTNlMDIwYWNjYzA2ZmM1YTRlZGQ3OGM0NjcwMjZkZGE0MTA4MGQ1ZTVmYzk).
+
+
+### Next Steps
+
+Now you're set up and ready to check out some of the other examples from our
+[Qiskit Tutorials](https://github.com/Qiskit/qiskit-tutorials/tree/master/qiskit/aer) repository.
+
+
+## Authors
+
+Qiskit Aer is the work of [many people](https://github.com/Qiskit/qiskit-aer/graphs/contributors) who contribute
+to the project at different levels.
+
+## License
+
+[Apache License 2.0](LICENSE.txt)