|
2 | 2 |
|
3 | 3 | This sample demonstrates the use of Python to call into Q# by using the [QInfer](http://qinfer.org/) and [QuTiP](http://qutip.org/) Python libraries to study the behavior of a Q# operation. |
4 | 4 |
|
5 | | -**NB**: This sample is currently a preview, and is supported on Windows only. |
6 | | - |
7 | 5 | ## Installation ## |
8 | 6 |
|
9 | | -As this sample demonstrates using Q# and Python together, we'll need to install a few more things than for Q# itself: |
10 | | - |
11 | | -- **Python 3.5** or later |
12 | | -- **Jupyter Notebook** |
13 | | -- Python packages used by this sample: **Python.NET**, **NumPy**/**SciPy**, **Matplotlib**, **QInfer**, and **QuTiP** |
14 | | -- **.NET Framework 4.7.1** or later is required for this sample. |
15 | | - This version of the .NET Framework is installed with Windows 10 Fall Creators Update (launched in October 2017), but you may need to install it separately if you are on an earlier version of Windows. |
16 | | - [See below](#net-framework-versions) to check your installed version, and how to update if needed. |
17 | | - |
18 | | -We recommend installing the [**Anaconda distribution**](https://www.anaconda.com/) of Python, as it includes NumPy, SciPy, Jupyter, and tools to make it easier to install and manage Python packages. |
19 | | - |
20 | | -### Installing Anaconda ### |
21 | | - |
22 | | -- Download the [latest version of Anaconda](https://www.anaconda.com/download/#windows), making sure to select the Python 3.5 or later version and not the version for Python 2.7. |
23 | | -- Run the Anaconda installer, and make sure to select *Add to PATH* during the installation. |
24 | | - |
25 | | -To check that Anaconda was installed correctly, run `python` from your favorite command line. |
26 | | -You should see something like the following: |
27 | | - |
28 | | -```powershell |
29 | | -PS> python |
30 | | -Python 3.6.2 |Anaconda custom (64-bit)| (default, Sep 19 2017, 08:03:39) [MSC v.1900 64 bit (AMD64)] on win32 |
31 | | -Type "help", "copyright", "credits" or "license" for more information. |
32 | | ->>> |
33 | | -``` |
34 | | -Type `exit()` and press *Enter* to quit Python and return to your command line. |
35 | | - |
36 | | -The Anaconda distribution installed above comes with Jupyter Notebook by default, but we recommend installing the `nb_conda` extension as well: |
37 | | - |
38 | | -```powershell |
39 | | -PS> conda install nb_conda |
40 | | -``` |
41 | | - |
42 | | -### Installing Required Python Packages ### |
| 7 | +As this sample demonstrates using Q# and Python together, make sure you have the `qsharp` package for Python installed first; see the [Getting Started with Python](https://docs.microsoft.com/quantum/install-guide/python) guide for details. |
43 | 8 |
|
44 | | -Once you have Anaconda installed, run the following from your favorite command line to install the environment for this sample: |
| 9 | +This sample also uses a couple extra Python packages to help out, so you'll need to have those ready as well. |
| 10 | +If you are using the [**Anaconda distribution**](https://www.anaconda.com/) of Python, this can be done automatically by using the `environment.yml` file provided with this sample: |
45 | 11 |
|
46 | | -```powershell |
47 | | -> cd Samples/PythonInterop |
48 | | -> conda env create -f environment.yml |
49 | 12 | ``` |
50 | | - |
51 | | -#### [Optional] Testing the New Conda Environment #### |
52 | | - |
53 | | -To use the new environment from the command line, we must activate it with the `activate` command. |
54 | | -For instance, to find the path at which the new environment was created, we can run the following commands: |
55 | | - |
56 | | -```powershell |
57 | | -PS> cmd |
58 | | -> activate qsharp-samples |
59 | | -(qsharp-samples) > python -c "import sys; print(sys.executable)" |
60 | | -C:\Users\<username>\AppData\Local\Continuum\anaconda3\envs\qsharp-samples\python.exe |
61 | | -``` |
62 | | - |
63 | | -Note that `cmd` is required as `activate` is not currently supported from within PowerShell; if the `(qsharp-samples)` prompt does not appear, you may need to run the above commands from within `cmd`. |
64 | | - |
65 | | -In any case, we will not be executing Jupyter inside this environment directly, but we will instead rely on `nb_conda` as installed above. |
66 | | -Thus, you must deactivate `qsharp-samples` to get back to the `root` environment. |
67 | | -This is done with the `deactivate` command: |
68 | | - |
69 | | -```powershell |
70 | | -(qsharp-samples) > deactivate |
| 13 | +cd Samples/src/PythonInterop |
| 14 | +conda env create -f environment.yml |
| 15 | +conda activate qsharp-samples |
71 | 16 | ``` |
72 | 17 |
|
73 | 18 | ### Running the Sample ### |
74 | 19 |
|
75 | | -Once everything is installed, from the command line build the PythonInterp project using dotnet: |
| 20 | +Once everything is installed, run `jupyter notebook` to start the Jupyter Notebook interface in your web browser: |
76 | 21 |
|
77 | | -```powershell |
78 | | -PS> cd Samples\PythonInterop |
79 | | -PS> dotnet build |
80 | 22 | ``` |
81 | | - |
82 | | -Then run `jupyter notebook` to start the Jupyter Notebook interface in your web browser: |
83 | | - |
84 | | -```powershell |
85 | 23 | PS> jupyter notebook |
86 | 24 | ``` |
87 | 25 |
|
88 | | -On the browser |
89 | | -- Select the `tomography-sample.ipynb` notebook in your browser to view the sample. |
90 | | -- From the `Kernel` menu, change to the `Python [conda env: qsharp-samples]` kernel. |
91 | | -- You are ready to start running the `tomography-sample` notebook. |
92 | | - |
93 | | -## Troubleshooting ## |
94 | | - |
95 | | -### `raw write() returned invalid length` ### |
96 | | - |
97 | | -You may see an error message similar to the one below: |
98 | | - |
99 | | -``` |
100 | | -File "C:\Users\<username>\AppData\Local\Continuum\anaconda3\envs\qsharp-samples\lib\site-packages\pip\_vendor\colorama\ansitowin32.py", line 141, in write |
101 | | - self.write_and_convert(text) |
102 | | - File "C:\Users\<username>\AppData\Local\Continuum\anaconda3\envs\qsharp-samples\lib\site-packages\pip\_vendor\colorama\ansitowin32.py", line 169, in write_and_convert |
103 | | - self.write_plain_text(text, cursor, len(text)) |
104 | | - File "C:\Users\<username>\AppData\Local\Continuum\anaconda3\envs\qsharp-samples\lib\site-packages\pip\_vendor\colorama\ansitowin32.py", line 175, in write_plain_text |
105 | | - self.wrapped.flush() |
106 | | -OSError: raw write() returned invalid length 134 (should have been between 0 and 67) |
107 | | - 9% |### | 348kB 2.7MB/s eta 0:00:02 |
108 | | -``` |
109 | | - |
110 | | -This is a known issue with running Python 3.5 from within VS Code. |
111 | | -If you encounter this error, run the sample from a PowerShell window outside of VS Code. |
112 | | - |
113 | | -### `ImportError: No module named 'Microsoft.Quantum.Samples'; 'Microsoft.Quantum' is not a package` ### |
114 | | - |
115 | | -If there is an error loading a .NET assembly into Python, this may manifest as an `ImportError` later in the notebook when you attempt to import namespaces exposed in that assembly. |
116 | | -This may happen because the assemblies defining your Q# operations and functions did not build properly. |
117 | | -To check this, run `dotnet build` again. |
118 | | - |
119 | | -The next most often cause of this problem is a version number mismatch between the version of the Quantum Development Kit expected by the Python interoperability package and the version referenced by the assembly that you are loading. |
120 | | -If the `qsharp` Python package successfully imports, you can check its version by running `print(qsharp.version)` from within Python. |
121 | | -To check if the `qsharp` package installed at all, please use the `conda list` command: |
122 | | - |
123 | | -```bash |
124 | | -$ conda list -n qsharp-samples qsharp |
125 | | -``` |
126 | | - |
127 | | -This version number should agree with the version listed in [`PythonInterop.csproj`](./PythonInterop.csproj), up to that Python packages do not use the `-preview` notation. |
128 | | - |
129 | | -If all else fails, you can see more detailed error messages by catching the exceptions raised by the .NET assembly loader: |
130 | | - |
131 | | -```python |
132 | | ->>> import sys |
133 | | ->>> sys.path.append('./bin/Debug/netstandard2.0') |
134 | | ->>> import qsharp |
135 | | - |
136 | | ->>> import clr |
137 | | ->>> asm = clr.AddReference('PythonInterop') |
138 | | ->>> try: |
139 | | -... print(asm.DefinedTypes) |
140 | | -... except Exception as ex: |
141 | | -... for loader_ex in ex.LoaderExceptions: |
142 | | -... print(loader_ex) |
143 | | -``` |
144 | | - |
145 | | -### .NET Framework Versions ### |
146 | | - |
147 | | -This sample uses *.NET Standard 2.0*, first supported by the .NET Framework as of version 4.7.1. |
148 | | -.NET Framework 4.7.1 can be installed on Windows 7 or later, and comes installed by default on Windows 10 Fall Creators Update and later. |
149 | | -To check if your installation of .NET Framework supports .NET Standard 2.0, run the following command in Windows PowerShell or PowerShell Core: |
150 | | - |
151 | | -```powershell |
152 | | -PS> Get-ChildItem "HKLM:SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full\" | Get-ItemPropertyValue -Name Release | ForEach-Object { $_ -ge 461308 } |
153 | | -``` |
154 | | - |
155 | | -If your installation of .NET Framework supports .NET Standard 2.0, you will see the word `True` printed to the console. |
156 | | -Otherwise, please [update your installation of the .NET Framework](https://www.microsoft.com/net/download/dotnet-framework-runtime). |
| 26 | +In the browser, select the `tomography-sample.ipynb` notebook in your browser to view the sample. |
0 commit comments