public QuotaMagic(IAzureClient azureClient, ILogger <QuotaMagic> logger)
: base(
azureClient,
"azure.quotas",
new Microsoft.Jupyter.Core.Documentation
{
Summary = "Displays a list of quotas for the current Azure Quantum workspace.",
Description = $@"
This magic command allows for displaying quota information for the current
Azure Quantum workspace.
The Azure Quantum workspace must have been previously initialized
using the [`%azure.connect` magic command]({KnownUris.ReferenceForMagicCommand("azure.connect")}).
#### Possible errors
- {AzureClientError.NotConnected.ToMarkdown()}
".Dedent(),
Examples = new[]
{
@"
Get the list of quotas:
```
In []: %azure.quotas
Out[]: <quota information for the workspace>
```
".Dedent()
},
}, logger)
{
}
/// <summary>
/// Given a given snippets collection, constructs a new magic command
/// that queries callables defined in that snippets collection.
/// </summary>
public LsMagicMagic(IMagicSymbolResolver resolver, IExecutionEngine engine, ILogger <LsMagicMagic> logger) : base(
"lsmagic",
new Microsoft.Jupyter.Core.Documentation
{
Summary = "Returns a list of all currently available magic commands.",
Description = $@"
This magic command lists all of the magic commands available in the IQ# kernel,
as well as those defined in any packages that have been loaded in the current
session via the [`%package` magic command]({KnownUris.ReferenceForMagicCommand("package")}).
".Dedent(),
Examples = new []
{
@"
Display the list of available magic commands:
```
In []: %lsmagic
Out[]: <detailed list of all available magic commands>
```
".Dedent(),
}
}, logger)
{
this.resolver = resolver;
if (engine is IQSharpEngine iQSharpEngine)
{
iQSharpEngine.RegisterDisplayEncoder(new MagicSymbolSummariesToHtmlEncoder());
iQSharpEngine.RegisterDisplayEncoder(new MagicSymbolSummariesToTextEncoder());
}
else
{
throw new Exception($"Expected execution engine to be an IQ# engine, but was {engine.GetType()}.");
}
}
public SimulateNoiseMagic(IExecutionEngine engine, ISymbolResolver resolver, IConfigurationSource configurationSource, INoiseModelSource noiseModelSource, ILogger <SimulateNoiseMagic> logger) : base(
"experimental.simulate_noise",
new Microsoft.Jupyter.Core.Documentation
{
Summary = "Runs a given function or operation on the OpenSystemsSimulator target machine.",
Description = $@"
> **⚠ WARNING:** This magic command is **experimental**,
> is not supported, and may be removed from future versions without notice.
This magic command allows executing a given function or operation
on the OpenSystemsSimulator target, simulating how that function or operation
will perform when run on noisy quantum hardware.
#### See also
- [`%config`]({KnownUris.ReferenceForMagicCommand("config")})
- [`%experimental.noise_model`]({KnownUris.ReferenceForMagicCommand("experimental.noise_model")})
#### Required parameters
- Q# operation or function name. This must be the first parameter, and must be a valid Q# operation
or function name that has been defined either in the notebook or in a Q# file in the same folder.
- Arguments for the Q# operation or function must also be specified as `key=value` pairs.
#### Remarks
The behavior of this magic command can be controlled through the `%experimental.noise_model` magic command,
and the `opensim.nQubits` and `opensim.representation` configuration settings.
".Dedent(),
Examples = new string[]
{
@"
Simulate a Q# operation defined as `operation MyOperation() : Result`:
```
In []: %simulate MyOperation
Out[]: <return value of the operation>
```
".Dedent(),
@"
Simulate a Q# operation defined as `operation MyOperation(a : Int, b : Int) : Result`:
```
In []: %simulate MyOperation a=5 b=10
Out[]: <return value of the operation>
```
".Dedent(),
}
})
{
this.SymbolResolver = resolver;
this.ConfigurationSource = configurationSource;
this.Logger = logger;
this.NoiseModelSource = noiseModelSource;
if (engine is IQSharpEngine iQSharpEngine)
{
iQSharpEngine.RegisterDisplayEncoder(new MixedStateToHtmlDisplayEncoder());
iQSharpEngine.RegisterDisplayEncoder(new StabilizerStateToHtmlDisplayEncoder(configurationSource));
}
}
public JobsMagic(IAzureClient azureClient, ILogger <JobsMagic> logger)
: base(
azureClient,
"azure.jobs",
new Microsoft.Jupyter.Core.Documentation
{
Summary = "Displays a list of jobs in the current Azure Quantum workspace.",
Description = $@"
This magic command allows for displaying the list of jobs in the current
Azure Quantum workspace, optionally filtering the list to jobs which
have an ID, name, or target containing the provided filter parameter.
The Azure Quantum workspace must have been previously initialized
using the [`%azure.connect` magic command]({KnownUris.ReferenceForMagicCommand("azure.connect")}).
#### Optional parameters
- A string to filter the list of jobs. Jobs which have an ID, name, or target
containing the provided filter parameter will be displayed. If not specified,
no job is filtered.
- `{ParameterNameCount}=<integer>` (default={CountDefaultValue}): The max number of jobs to return.
#### Possible errors
- {AzureClientError.NotConnected.ToMarkdown()}
".Dedent(),
Examples = new[]
{
@"
Get the list of jobs:
```
In []: %azure.jobs
Out[]: <detailed status of all recent jobs in the workspace>
```
".Dedent(),
@"
Get the list of jobs whose ID, name, or target contains ""My job"":
```
In []: %azure.jobs ""My job""
Out[]: <detailed status of matching jobs in the workspace>
```
".Dedent(),
@"
Get the list of jobs whose ID, name, or target contains ""My job"", limit it to at most 100 jobs:
```
In []: %azure.jobs ""My job"" count=100
Out[]: <detailed status of at most 100 matching jobs in the workspace>
```
".Dedent(),
},
}, logger)
{
}
public OutputMagic(IAzureClient azureClient, ILogger <OutputMagic> logger)
: base(
azureClient,
"azure.output",
new Microsoft.Jupyter.Core.Documentation
{
Summary = "Displays results for a job in the current Azure Quantum workspace.",
Description = $@"
This magic command allows for displaying results for a job in the current
Azure Quantum workspace.
The job execution must already be completed in order to display
results.
The Azure Quantum workspace must have been previously initialized
using the [`%azure.connect` magic command]({KnownUris.ReferenceForMagicCommand("azure.connect")}.
#### Optional parameters
- The job ID for which to display results. If not specified, the job ID from
the most recent call to [`%azure.submit`]({KnownUris.ReferenceForMagicCommand("azure.submit")}
or [`%azure.execute`]({KnownUris.ReferenceForMagicCommand("azure.execute")} will be used.
#### Possible errors
- {AzureClientError.NotConnected.ToMarkdown()}
- {AzureClientError.JobNotFound.ToMarkdown()}
- {AzureClientError.JobNotCompleted.ToMarkdown()}
- {AzureClientError.JobOutputDownloadFailed.ToMarkdown()}
- {AzureClientError.JobFailedOrCancelled.ToMarkdown()}
".Dedent(),
Examples = new[]
{
@"
Get results of a specific job:
```
In []: %azure.output JOB_ID
Out[]: <detailed results of specified job>
```
".Dedent(),
@"
Get results of the most recently submitted job:
```
In []: %azure.output
Out[]: <detailed results of most recently submitted job>
```
".Dedent(),
},
}, logger)
{
}
public TargetMagic(IAzureClient azureClient, ILogger <TargetMagic> logger)
: base(
azureClient,
"azure.target",
new Microsoft.Jupyter.Core.Documentation
{
Summary = "Sets or displays the active execution target for Q# job submission in an Azure Quantum workspace.",
Description = $@"
This magic command allows for specifying or displaying the execution target for Q# job submission
in an Azure Quantum workspace.
The Azure Quantum workspace must have been previously initialized
using the [`%azure.connect` magic command]({KnownUris.ReferenceForMagicCommand("azure.connect")})
magic command. The specified execution target must be available in the workspace and support execution of Q# programs.
#### Optional parameters
- The target ID to set as the active execution target for Q# job submission. If not specified,
the currently active execution target is displayed.
#### Possible errors
- {AzureClientError.NotConnected.ToMarkdown()}
- {AzureClientError.InvalidTarget.ToMarkdown()}
- {AzureClientError.NoTarget.ToMarkdown()}
".Dedent(),
Examples = new[]
{
@"
Set the current target for Q# job submission to `provider.qpu`:
```
In []: %azure.target provider.qpu
Out[]: Loading package Microsoft.Quantum.Providers.Provider and dependencies...
Active target is now provider.qpu
<detailed properties of active execution target>
```
".Dedent(),
@"
Display the current target and all available targets in the current Azure Quantum workspace:
```
In []: %azure.target
Out[]: Current execution target: provider.qpu
Available execution targets: provider.qpu, provider.simulator
<detailed properties of active execution target>
```
".Dedent(),
},
},
logger)
{
}
public ExecuteMagic(IAzureClient azureClient, ILogger <ExecuteMagic> logger)
: base(
azureClient,
"azure.execute",
new Microsoft.Jupyter.Core.Documentation
{
Summary = "Submits a job to an Azure Quantum workspace and waits for completion.",
Description = $@"
This magic command allows for submitting a Q# operation or function
to be run on the specified target in the current Azure Quantum workspace.
The command waits a specified amount of time for the job to complete before returning.
The Azure Quantum workspace must have been previously initialized
using the [`%azure.connect` magic command]({KnownUris.ReferenceForMagicCommand("azure.connect")}),
and an execution target for the job must have been specified using the
[`%azure.target` magic command]({KnownUris.ReferenceForMagicCommand("azure.target")}).
#### Required parameters
- Q# operation or function name. This must be the first parameter, and must be a valid Q# operation
or function name that has been defined either in the notebook or in a Q# file in the same folder.
- Arguments for the Q# operation or function must also be specified as `key=value` pairs.
#### Optional parameters
- `{AzureSubmissionContext.ParameterNameJobName}=<string>`: Friendly name to identify this job. If not specified,
the Q# operation or function name will be used as the job name.
- `{AzureSubmissionContext.ParameterNameJobParams}=<JSON key:value pairs>`: Provider-specific job parameters
expressed in JSON as one or more `key`:`value` pairs to be passed to the execution target. Values must be strings.
- `{AzureSubmissionContext.ParameterNameShots}=<integer>` (default=500): Number of times to repeat execution of the
specified Q# operation or function.
- `{AzureSubmissionContext.ParameterNameTimeout}=<integer>` (default=30): Time to wait (in seconds) for job completion
before the magic command returns.
- `{AzureSubmissionContext.ParameterNamePollingInterval}=<integer>` (default=5): Interval (in seconds) to poll for
job status while waiting for job execution to complete.
#### Possible errors
- {AzureClientError.NotConnected.ToMarkdown()}
- {AzureClientError.NoTarget.ToMarkdown()}
- {AzureClientError.NoOperationName.ToMarkdown()}
- {AzureClientError.InvalidTarget.ToMarkdown()}
- {AzureClientError.UnrecognizedOperationName.ToMarkdown()}
- {AzureClientError.InvalidEntryPoint.ToMarkdown()}
- {AzureClientError.JobSubmissionFailed.ToMarkdown()}
- {AzureClientError.JobNotCompleted.ToMarkdown()}
- {AzureClientError.JobOutputDownloadFailed.ToMarkdown()}
- {AzureClientError.JobFailedOrCancelled.ToMarkdown()}
".Dedent(),
Examples = new[]
{
@"
Run a Q# operation defined as `operation MyOperation(a : Int, b : Int) : Result`
on the active target in the current Azure Quantum workspace:
```
In []: %azure.execute MyOperation a=5 b=10
Out[]: Submitting MyOperation to target provider.qpu...
Job successfully submitted for 500 shots.
Job name: MyOperation
Job ID: <Azure Quantum job ID>
Waiting up to 30 seconds for Azure Quantum job to complete...
[1:23:45 PM] Current job status: Waiting
[1:23:50 PM] Current job status: Executing
[1:23:55 PM] Current job status: Succeeded
<detailed results of completed job>
```
".Dedent(),
@"
Run a Q# operation defined as `operation MyOperation(a : Int, b : Int) : Result`
on the active target in the current Azure Quantum workspace,
specifying a custom job name, number of shots, timeout, polling interval, and provider-specific job parameters:
```
In []: %azure.submit MyOperation a=5 b=10 jobName=""My job"" shots=100 timeout=60 poll=10 jobParams={""Key1"":""Val1"",""Key2"":""Val2""}
Out[]: Submitting MyOperation to target provider.qpu...
Job successfully submitted for 100 shots.
Job name: My job
Job ID: <Azure Quantum job ID>
Waiting up to 60 seconds for Azure Quantum job to complete...
[1:23:45 PM] Current job status: Waiting
[1:23:55 PM] Current job status: Waiting
[1:24:05 PM] Current job status: Executing
[1:24:15 PM] Current job status: Succeeded
<detailed results of completed job>
```
".Dedent(),
},
}, logger)
{
}
public SubmitMagic(IAzureClient azureClient, ILogger <SubmitMagic> logger)
: base(
azureClient,
"azure.submit",
new Microsoft.Jupyter.Core.Documentation
{
Summary = "Submits a job to an Azure Quantum workspace.",
Description = $@"
This magic command allows for submitting a Q# operation or function
to be run on the specified target in the current Azure Quantum workspace.
The command returns immediately after the job is submitted.
The Azure Quantum workspace must have been previously initialized
using the [`%azure.connect` magic command]({KnownUris.ReferenceForMagicCommand("azure.connect")}),
and an execution target for the job must have been specified using the
[`%azure.target` magic command]({KnownUris.ReferenceForMagicCommand("azure.target")}).
#### Required parameters
- Q# operation or function name. This must be the first parameter, and must be a valid Q# operation
or function name that has been defined either in the notebook or in a Q# file in the same folder.
- Arguments for the Q# operation or function must also be specified as `key=value` pairs.
#### Optional parameters
- `{AzureSubmissionContext.ParameterNameJobName}=<string>`: Friendly name to identify this job. If not specified,
the Q# operation or function name will be used as the job name.
- `{AzureSubmissionContext.ParameterNameJobParams}=<JSON key:value pairs>`: Provider-specific job parameters
expressed in JSON as one or more `key`:`value` pairs to be passed to the execution target. Values must be strings.
- `{AzureSubmissionContext.ParameterNameShots}=<integer>` (default=500): Number of times to repeat execution of the
specified Q# operation or function.
#### Possible errors
- {AzureClientError.NotConnected.ToMarkdown()}
- {AzureClientError.NoTarget.ToMarkdown()}
- {AzureClientError.NoOperationName.ToMarkdown()}
- {AzureClientError.InvalidTarget.ToMarkdown()}
- {AzureClientError.UnrecognizedOperationName.ToMarkdown()}
- {AzureClientError.InvalidEntryPoint.ToMarkdown()}
- {AzureClientError.JobSubmissionFailed.ToMarkdown()}
".Dedent(),
Examples = new[]
{
@"
Submit a Q# operation defined as `operation MyOperation(a : Int, b : Int) : Result`
for execution on the active target in the current Azure Quantum workspace:
```
In []: %azure.submit MyOperation a=5 b=10
Out[]: Submitting MyOperation to target provider.qpu...
Job successfully submitted for 500 shots.
Job name: MyOperation
Job ID: <Azure Quantum job ID>
<detailed properties of submitted job>
```
".Dedent(),
@"
Submit a Q# operation defined as `operation MyOperation(a : Int, b : Int) : Result`
for execution on the active target in the current Azure Quantum workspace,
specifying a custom job name, number of shots, and provider-specific job parameters:
```
In []: %azure.submit MyOperation a=5 b=10 jobName=""My job"" shots=100 jobParams={""Key1"":""Val1"",""Key2"":""Val2""}
Out[]: Submitting MyOperation to target provider.qpu...
Job successfully submitted for 100 shots.
Job name: My job
Job ID: <Azure Quantum job ID>
<detailed properties of submitted job>
```
".Dedent(),
},
},
logger)
{
}
