Usually this meant:
It’s a small thing, but it adds up.
So I made a simple extension that does it in one go.
Select one or more files in Solution Explorer, right-click, and copy them as Markdown with code fences and file paths.
That’s it.
You can find it here: Content Grabber on the Visual Studio Marketplace
]]>
According to this, more articles are now written by generative AI than by humans. Getting your message out there is sadly no longer about insight, originality, or effort. It’s about volume of output, and lots of it.
Articles are still produced, but they no longer appear to be meant for reading. They accumulate, existing only to be referenced.
Interesting, ground-breaking, nuanced articles, 100% human-written articles like this may still be produced, briefly admired by their author, and then politely ignored forever.
This over abundance of AI generated content has been dubbed AI slop.
Slop seems to drown out human produced content and this may not be entirely attributable to its volume. Slop produced by generative AI may be prefered by bots and content ranking systems. After all, if an LLM produces the content, it is likely to prefer the content produced by a similar model. Such a system becomes self-confirming and in a way, arrogant. It conflates familiarity (the things that it might output) with quality.
So, when an LLM tells you what makes for a good post or article, it’s right! But not for the reasons you’d think and not for the reasons it will tell you.
It is unclear whether the maintainers of bots and content ranking systems do, or will, try to favour posts that are less likely to be AI generated.
Yet, even if they do, an endless game of catch-up has begun: SEO versus detection, and detection versus masking of AI content. Slop may be made to look authentic through feigned human artefacts like deliberate typos and unorthodox document structures.
If you’re trying to get the word out about your idea, product, or service, and trying to compete solely as a human, the economics are no longer on your side.
Clearly, you need a slop generator.
In this mostly non-AI-generated article you’ll learn how to schedule an AI agent to periodically write and publish a blog post that intersects current trending topics with your company, product, or message. You’ll see how to push files from a private GitHub repo to a public GitHub Pages repo. You see how your AI agent can send you a tailored link for sharing to various social media sites.
So what makes for effective AI slop? As I see it, one simple recipe consists of: one part backstory (info on your product or service) and one part current affairs (related trending stories).
But before scheduling our agent to generate content, we need to find a host for the output.
Before anything can be published, we need somewhere for it to land, and a clear separation between where content is produced and where it is served from.
For this we’ll use a repo where markdown files are pushed, and from which a static site is generated. You can use whatever static site generator you like. Traditionally, GitHub Pages favours Jekyll. That’s what I’ve used in the past. But, I’ve found it to be brittle. Fortunately you can swap out your site generation with whatever you like using a GitHub workflow. So I opted for this nice BlazorStatic project instead. If, like me, you’re partial to .NET, I recommend it. If not, anything that reliably turns markdown into HTML will do.
NOTE: While Orpius has a built-in web publishing capability (all content placed in a directory named web in your isolated storage is viewable online) we shan’t be using it this time. Instead we place all slop in a GitHub repo.
Previously, when using Jekyll for static site generation, I placed the static site generation bits alongside the content. I never really liked that because having the unrelated generation code accessible via GitHub; people can browse those files too. There seems to be no easy and practical way to keep the stuff that isn’t output, private if it resides in the same repo.
Fortunately, the better way is to use a private repo for the static site generation, and a public repo to host the output from it. That’s the way I did things this time.
NOTE: When not using Jekyll for your site generation, you’ll need to place a file named
.nojekyllin the root of your output directory. I did this by creating awwwrootdirectory in the BlazorStatic template project.
GitHub gives you a one-to-one pairing with an organization and a static website. So, for a dedicated slop website create a new organization on GitHub. This is free. Inside that organisation, create a repository named:
{YourOrganization}.github.io
This will become the public-facing site.
Navigate to the repo’s Settings, configure GitHub Pages, and follow the instructions here:
Create a GitHub Pages Site
The setup is straightforward, and you can attach a custom domain if you wish. I’ll refer to this repository as the target repo.
I recommend skipping the static site generation steps described in those instructions. We want to keep the publishing surface simple and move all generation elsewhere.
In your *.github.io target repo:
gh-pages/ (root)Once the GitHub Pages site is configured, create a second repository in the same organisation. This will be the source repo. Make it private. This is where the AI agent will push markdown files, and where the static site generator will run.
A GitHub workflow will then copy the generated output from the source repo into the target repo. From this point on, the public site never sees the machinery behind it.
To make this work, we need credentials. You will create two Personal Access Tokens (PATs):
The first PAT that you’ll create is for authorizing the push from the source repo to the target repo. Here are the steps:
Contents: Read/Write.PAGES_DEPLOY_TOKEN)PAGES_DEPLOY_TOKENWhen your workflow runs the step ‘Deploy to GitHub Pages repo’ (shown in a later section) with the token:
token: ${{ secrets.PAGES_DEPLOY_TOKEN }}
the job will authenticate as you and allow the action to push to the target repo.
The second PAT is for authorizing the push from the source repo to the target repo. Here are the steps:
Contents: Read/Write.At this point, the responsibilities are cleanly separated into the following:
Here is the workflow template:
name: Build and publish to gh pages
on:
push:
branches: ["main"]
workflow_dispatch:
env:
ASPNETCORE_ENVIRONMENT: Production
WEBAPP_PATH: ./
WEBAPP_CSPROJ: YourStaticSiteProject.csproj
OUTPUT_PATH: ./output
PAGES_REPO: YourTargetRepo/yourtargetrepo.github.io
PAGES_BRANCH: gh-pages
CUSTOM_DOMAIN: example.com
jobs:
build-and-deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup .NET 10
uses: actions/setup-dotnet@v4
with:
dotnet-version: "10.0.x"
- name: Remove launchSettings.json (to not override ASPNETCORE_ENVIRONMENT)
run: rm -f ${{ env.WEBAPP_PATH }}Properties/launchSettings.json
- name: Ensure .nojekyll exists
run: mkdir -p "${{ env.WEBAPP_PATH }}wwwroot" && touch "${{ env.WEBAPP_PATH }}wwwroot/.nojekyll"
- name: Run webapp and generate static files
run: dotnet run --project ${{ env.WEBAPP_PATH }}${{ env.WEBAPP_CSPROJ }} --configuration Release
- name: Add CNAME for custom domain
run: echo "${{ env.CUSTOM_DOMAIN }}" > "${{ env.OUTPUT_PATH }}/CNAME"
- name: Deploy to GitHub Pages repo
uses: JamesIves/github-pages-deploy-action@v4.6.8
with:
token: ${{ secrets.PAGES_DEPLOY_TOKEN }}
repository-name: ${{ env.PAGES_REPO }}
branch: ${{ env.PAGES_BRANCH }}
folder: ${{ env.OUTPUT_PATH }}
clean: true
exclude: ".git,.github,.ssh"
With this in place, committing a markdown file to the source repo triggers the entire process automatically. 30 seconds later, the page appears on the public site. The system is ready to run unattended.
Setting up the GitHub repo was a bit laborious. Fortunately setting up an AI agent to complete our slop generator is much easier.
If you haven’t already, download and install the Orpius Console from https://orpius.com/get-started.html
Orpius is bring-your-own-model. For this task I used a free Gemini API Key and pointed the model at the gemini-3-flash-preview model.
NOTE: I’ve experienced some service unavailability errors recently using the Gemini 3 models. I guess demand can spike at times.
For the agent to push the slop to the source repo, we need to tell it the PAT. But, we don’t want the sensitive PAT to flow to the LLM model provider. So for this we leverage the Orpius Secrets feature. Orpius Secrets allow you to securely provide a value that is kept in secure storage. Your Orpius agent knows about Secrets and knows how they work. But it can’t ‘see’ their values. It understands that when you refer to one by name, it will use the Secret token format as a placeholder in the code that it writes or when it uses a tool.
Go to the Secrets tab in Orpius Console and use the Add button to create a new secret. Name it SilverfixBlogAgentWriter and set its value to the value of the second PAT you created above.
Here are the steps I wanted the agent to follow:
Here’s that translated to a prompt that I gave to Orpius:
Everyday at 12.10 pm please perform the following tasks to create a new blog post.
- Download the Orpius User Guide text from
https://raw.githubusercontent.com/Orpius/SDK/refs/heads/main/docs/UserGuide/index.mdThis will help you understand everything about Orpius.- Find out the names of the .md files in the ‘Content/Blog/’ directory in the github repo using the PAT secret:
<%=Key:SilverfixBlogAgentWriter%>- Find out the latest trending AI agentic topics that relate to Orpius in some way.
- Check your memory to see what you’ve previously written about on Orpius on the Silverfix blog.
- Write a short article (in markdown) on one of the latest trending AI agentic topics from step 3, using the following format (don’t include the title at the body of the content as that is rendered automatically using the front-matter title value):
--- title: {the title for the post} lead: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla nec purus feugiat, molestie ipsum et, consequat nibh. Etiam non elit dui. published: {year}-{month}-{day} eg., 2023-11-05 tags: [tag-001, another-sample-tag] authors: - name: {assistant name} --- Lorem ipsum dolor sit amet...- Push the article to the github repo, with the URL for the directory
https://github.com/SilverFixCom/SilverfixBlog/tree/main/> Content/Blogusing the PAT secret:<%=Key:SilverfixBlogAgentWriter%>- Send me a notification with a link that I can click on to create a new LinkedIn post that has a description and a link to the new article. The URL of the new post will be https://silverfix.com/blog/ {the name of the markdown file without the .md extension}
- Add the post title to your memory.
- If you can’t complete the tasks for whatever reason, send me a notification.
That was entered in the chat in the Orpius Console:
Upon entering the prompt, Orpius scheduled the new item with a re-interpretation of my instructions.
Perform the following steps to create and publish a new blog post:
- Download User Guide: Retrieve the text from
https://raw.githubusercontent.com/Orpius/SDK/refs/heads/main/docs/UserGuide/index.mdto understand Orpius capabilities.- Check Existing Posts: Use the GitHub API to list the
.mdfiles in theContent/Blog/directory of theSilverFixCom/> SilverfixBlogrepository. Use the PAT secret<%=Key:SilverfixBlogAgentWriter%>.- Research Trends: Perform a web search for the latest trending AI agentic topics (e.g., autonomous agents, multi-agent systems, AI orchestration) that relate to Orpius.
- Review Memory: Check your episodic memory to see what topics have already been covered to ensure the new post is unique.
- Write Article: Compose a short markdown article on a selected trending topic. Use the following format:
--- title: {Title} lead: {Lead summary} published: {YYYY-MM-DD} tags: [tag1, tag2] authors: - name: Orpius --- {Content}
- Publish to GitHub: Push the markdown file to
https://github.com/SilverFixCom/SilverfixBlog/tree/main/Content/Blogusing the PAT secret<%=Key:SilverfixBlogAgentWriter%>.- Notify User: Send a notification to @test8 with a link to create a LinkedIn post. The link should include a description and point to
https://silverfix.com/blog/{filename_without_extension}.- Update Memory: Record the title of the new post in your episodic memory.
- Error Handling: If any step fails, send a notification to @test8 with the details of the failure.
This schedule was created by @test8 (Daniel).
You may notice that step 9 provides instruction on error handling. I give an explicit instruction to notify me if an error occurs.
An agent should be capable of diagnosing its own failures. We should not need to debug agentic processes ourselves. When we do, it is a clear signal that the system is inadequate.
Ideally, if an agent cannot explain what went wrong and why, then the problem is not the failure itself, but the design of the system that produced it. A well-designed agentic system should surface its own diagnosis and only require human involvement when a decision, not a fault, needs escalation.
I like to think of the agent as a colleague: one who can summarise what went wrong, explain why it happened, and only escalate when human intervention is genuinely required.
Tip: You can change the instructions if you need to via the Scheduled Item view. Changes will affect any subsequent runs.
When 12.10 pm came around I received an email with a link to repost. Lovely! Slop generation successful.
The generated blog post over on silverfix.com (which is a domain name I had lying around):
In this article you saw how to schedule an AI agent to periodically write and publish a blog post that intersects current trending topics with your company, product, or message. You saw how to push files from a private GitHub repo to a public GitHub Pages repo. You also saw how your AI agent can send you a tailored link for sharing to various social media sites.
We walked through the manual setup of repos so we could see exactly what was happening at each step. In a follow-up article, I plan to show how most of this process can be automated by an agent once a GitHub credential is in place, turning the whole setup into a repeatable, hands-off workflow; even the fiddly bits.
I hope you enjoyed this article, and I welcome your feedback and questions.
]]>As frontier language models improve, AI agents are set to move further into the realm of scientific research. Multiple agents, working independenty, exploring scientific domains, offer the promise of greater speed of discovery. In addition, LLMs encode a vast amount of technical information that empowers humans to reach beyond the limits of their own education and experience.
I’m excited by this field of exploration in AI because it will accelerate scientific research and understanding, and lead to radical advances in health, material sciences, the list is endless. One such domain is quantum computing. Enabling agents to explore new research via browsing, to make hypotheses, and then test those hypotheses on a quantum simulator or an actual physical quantum computer, and then to publish the results, opens up amazing potential for discoveries.
In this article we look at how we might start this journey. You’ll see how we can schedule an AI agent to periodically write and execute OpenQASM code and publish the results on the web. Then we’ll deep-dive into the implementation and see how to:
The full source code for this article is downloadable from https://github.com/Orpius/SDK/tree/main/DotNet/Orpius.Platform.Sdk/Samples/Containerized
Orpius has two parts: a remote server and a local desktop application. The desktop application allows you to configure the server, schedule tasks, define events, create agents, and so forth. You can find more about Orpius over at the user-guide. If you want to try the ideas explored in this article, get a free-to-try copy of Orpius here https://orpius.com/get-started.html. Let’s jump straight in and see how to create a task to execute some quantum code.
Let’s begin by looking at the end result of this work. I began with a prompt to the Orpius interactive agent via the Orpius Console:
At 13:55 pm today perform the following verbatim: Design a minimal OpenQASM 3 circuit that demonstrates superposition and entanglement. Execute it with 2048 shots, evaluate whether the results match expectations, and publish the circuit and results to web/quantum.html. Don’t write any code now.
I told it to schedule the task rather than immediately execute it. You can schedule tasks to be run arbitrarily or based on an event.
NOTE: At present the Orpius interactive agent (the one you chat with in the Orpius Console) only has access to custom tools via Orpius Operations; it cannot call custom tools directly but this a planned feature for a future release.
After the prompt, a new scheduled item shows up in the Schedule tab of the Orpius Console. When scheduled items are actioned by an agent the Repetitions, count is incremented in the Console.
The Orpius agent broke the task into steps, as shown below:
When 13:55 came around, the task was actioned…and it failed. Examining the logs I could see that:
In Orpius, when a tool raises an error, that error propogates back to the agent. This is how agents are, for example, able to write managed code (using the built-in code execution tool) and to make corrections based on compilation errors. We needed to do the same thing with our OpenQASM code.
So, after some assistance from a model I made some error handling additions to my python code, which we’ll look at later in the article.
Likewise, I also updated the method description to better guide the agent in acceptable OpenQASM 3 code. (Again, we’ll dig into this later.)
The agent was then able to successfully write its own OpenQASM code, use the custom tool to execute it, then publish the results to a webpage.
In Orpius, the agents and files associated with the project you’re working on are termed a Space. And, by default, any files that are placed in your Space’s isolated storage under its web directory are browsable on the internet. That means you or your agent can do instant web publishing. Pretty neat. If you’re using the trial version of Orpius, then the content is browsable at https://trial.app.orpius.com/YOUR_ORG_NAME/YOUR_SPACE_NAME/pagename.html. This instant publishing feature is brand-new.
Orpius agents use the code execution tool to write, compile, and execute code within a fully isolated webassembly environment. The agent writes C# code to write the page to your web directory in isolated storage.
The generated page is barebones stylistically, but there is no reason why you can’t task the agent to jazz it up a bit. I leave that to the reader.
So, with the agent able to write and execute a basic OpenQASM program, it was time to push it a bit harder.
My next prompt was:
At 15:20 pm today perform the following verbatim: Design a small OpenQASM 3 experiment that demonstrates superposition and entanglement, and includes at least one simple variation (for example: with and without an entangling gate).
Execute each circuit with 2048 shots. Compare the results and explain what changes and why.
Publish the circuits and results to web/experiment.html. You may use basic HTML, inline CSS, and small amounts of JavaScript to make the page more engaging and easier to understand. Keep everything self-contained (no external libraries or network access).
The page should:
- briefly explain the experiment in plain language
- show each circuit as formatted code
- present results clearly (tables, simple bars, or percentages)
- include a short interpretation of the measurement distributions
- remain readable even if JavaScript is disabled
Do not write any code now.
Again, the Orpius interactive agent breaks down the task into sub-tasks. This is then interpreted by one or more agents when the schedule item comes round.
When the schedule came round, the agent was able to write and execute the OpenQasm code, and to create a web page that was immediately viewable.
We’ve looked at using the custom tool, now lets explore how the custom tool was put in place. Let’s begin with the docker sidecar that I needed to put in place to enable to quantum tool.
To bring in the quantum simulator functionality I chose to hook up a docker container with qiskit in it. I then call out to the sidecar from my ASP.NET Core tools hosting project. Below is the Dockerfile for the sidecar image that contains the quantum simulator.
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY app.py .
EXPOSE 5000
CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "5000"]
The qiskit bits are pulled in via the requirements.txt file:
fastapi==0.115.6
uvicorn[standard]==0.32.1
pydantic==2.10.3
qiskit==1.3.0
qiskit-aer==0.15.1
qiskit-qasm3-import==0.6.0
The sidecar contains a single app.py python file. It’s task is to call into qiskit to execute incoming OpenQasm code in the simulator. The excerpt below shows the run_job function, which compiles the code and runs it using the simulator.
def run_job(qasm_text: str, shots: int, queue: mp.Queue) -> None:
install_signal_handlers()
apply_limits()
try:
from qiskit import qasm3, transpile
from qiskit_aer import Aer
circuit = qasm3.loads(qasm_text)
validate_circuit(circuit)
simulator = Aer.get_backend("aer_simulator")
# Keep optimisation low to avoid expensive transpilation.
compiled = transpile(circuit, simulator, optimization_level=0)
result = simulator.run(compiled, shots=shots).result()
counts = result.get_counts()
queue.put({"ok": True, "counts": counts})
except Exception as ex:
queue.put({"ok": False, "error": build_error_payload(ex)})
Incoming requests to the sidecar are placed in a queue. During execution we ensure that each job does not exceed a timeout. We also surface any errors back to the caller.
@app.post("/execute")
async def execute(request: ExecuteRequest) -> Any:
if len(request.qasm) > MAX_QASM_CHARS:
raise HTTPException(status_code=413, detail="QASM program is too large.")
if request.shots < 1 or request.shots > MAX_SHOTS:
raise HTTPException(
status_code=400,
detail=f"Shots must be between 1 and {MAX_SHOTS}."
)
async with semaphore:
queue = mp.SimpleQueue()
process = mp.Process(
target=run_job,
args=(request.qasm, request.shots, queue),
daemon=True
)
start_time = time.monotonic()
process.start()
# Poll without blocking the event loop.
while process.is_alive():
elapsed = time.monotonic() - start_time
if elapsed > TIMEOUT_SECONDS:
process.terminate()
process.join(timeout=1.0)
if process.is_alive():
process.kill()
process.join()
exit_code = process.exitcode
signal_name = get_signal_name_from_exit_code(exit_code)
raise HTTPException(
status_code=408,
detail={
"type": "Timeout",
"message": f"Simulation exceeded time limit ({TIMEOUT_SECONDS}s).",
"elapsedSeconds": elapsed,
"exitCode": exit_code,
"signal": signal_name,
}
)
await asyncio.sleep(0.05)
process.join()
if queue.empty():
exit_code = process.exitcode
signal_name = get_signal_name_from_exit_code(exit_code)
raise HTTPException(
status_code=500,
detail={
"type": "WorkerCrashed",
"message": "Simulator worker exited without output."
"This usually indicates a hard kill "
"(CPU/memory limit) or a native crash.",
"exitCode": exit_code,
"signal": signal_name,
"elapsedSeconds": time.monotonic() - start_time,
}
)
payload = queue.get()
if not payload.get("ok", False):
error = payload.get("error") or {"type": "UnknownError", "message": "Unknown error."}
status_code = classify_http_status(error)
raise HTTPException(status_code=status_code, detail=error)
return {
"counts": payload["counts"],
"elapsedSeconds": time.monotonic() - start_time
}
My intention is to build out more custom tools that will probably require sidecars like the Quantum Simulator. To allow easy navigation between files I created an empty SupportingServices project in Visual Studio, into which I then placed the Dockerfile for the Qiskit sidecar and the python file to interact with it.
The csproj file is shown below. I explicitly exclude everything from compilation.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFramework>net8.0</TargetFramework>
<EnableDefaultItems>false</EnableDefaultItems>
</PropertyGroup>
<ItemGroup>
<None Include="Files\**\*"
Exclude="**\bin\**;**\obj\**;**\.vs\**" />
</ItemGroup>
</Project>
Recall that we have an ASP.NET Core project that hosts our custom tools. To bring in the quantum simulator sidecar, we include it in the docker-compose.yml file, as shown below:
services:
toolhosting_aspnetcore:
image: ${DOCKER_REGISTRY-}toolhostingaspnetcore
build:
context: ../../..
dockerfile: Samples/Containerized/ToolHosting_AspNetCore/ToolHosting_AspNetCore/Dockerfile
quantum-simulator:
build:
context: ../SupportingServices/Files/QuantumSimulator
dockerfile: Dockerfile
expose:
- "5000"
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:5000/health').read()"]
interval: 5s
timeout: 3s
retries: 20
Since I wish to re-use the supporting sidecars for multiple solutions, the sidecar sits in a directory outside of the main samples directory. Doing this meant that I had to change the context to be higher up in the directory tree. The dockerfile for the ToolHosting_AspNetCore project copies in the SDK projects.
# This stage is used when running from VS in fast mode (Default for Debug configuration)
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS base
USER $APP_UID
WORKDIR /app
EXPOSE 8080
EXPOSE 8081
# This stage is used to build the service project
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
ARG BUILD_CONFIGURATION=Release
WORKDIR /src
COPY ["Samples/Containerized/ToolHosting_AspNetCore/ToolHosting_AspNetCore/ToolHosting_AspNetCore.csproj", "Samples/Containerized/ToolHosting_AspNetCore/ToolHosting_AspNetCore/"]
COPY ["Orpius.Platform.ClientSdk.ProtobufNet/Orpius.Platform.ClientSdk.ProtobufNet.csproj", "Orpius.Platform.ClientSdk.ProtobufNet/"]
COPY ["Orpius.Platform.ClientSdk.ProtobufNet.Generators/Orpius.Platform.ClientSdk.ProtobufNet.Generators.csproj", "Orpius.Platform.ClientSdk.ProtobufNet.Generators/"]
RUN dotnet restore "Samples/Containerized/ToolHosting_AspNetCore/ToolHosting_AspNetCore/ToolHosting_AspNetCore.csproj"
COPY . .
WORKDIR "/src/Samples/Containerized/ToolHosting_AspNetCore/ToolHosting_AspNetCore"
RUN dotnet build "ToolHosting_AspNetCore.csproj" -c $BUILD_CONFIGURATION -o /app/build
# This stage is used to publish the service project to be copied to the final stage
FROM build AS publish
ARG BUILD_CONFIGURATION=Release
WORKDIR "/src/Samples/Containerized/ToolHosting_AspNetCore/ToolHosting_AspNetCore"
RUN dotnet publish "./ToolHosting_AspNetCore.csproj" -c $BUILD_CONFIGURATION -o /app/publish /p:UseAppHost=false
# This stage is used in production or when running from VS in regular mode (Default when not using the Debug configuration)
FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "ToolHosting_AspNetCore.dll"]
NOTE: When using the Orpius SDK NuGet packages, and not the actual SDK projects like I did here, there is no need to perform the copy operations in the dockerfile.
We communicate with the Qiskit sidecar over HTTP on the shared Docker network. The QuantumSimulatorClient class, in the ToolHosting_AspNetCore project, makes the calls.
We have two data transfer objects: an ExecuteRequest class that hold that qasm code; sent to the Qiskit quantum simulator in the sidecar, and the response received back from the sidecar.
The ExecuteResponse.Counts dictionary holds the resulting qubit states, or an error if execution failed.
sealed class ExecuteRequest
{
public required string Qasm { get; init; }
public int Shots { get; init; } = 1024;
}
sealed class ExecuteResponse
{
public Dictionary<string, int>? Counts { get; init; }
}
To call the sidecar the QuantumSimulatorClient has the following ExecuteAsync method:
public async Task<Dictionary<string, int>> ExecuteAsync(
string openQasm3Program,
int shots,
CancellationToken token)
{
var response = await httpClient.PostAsJsonAsync(
"/execute",
new ExecuteRequest
{
Qasm = openQasm3Program,
Shots = shots
},
cancellationToken: token);
if (!response.IsSuccessStatusCode)
{
var errorText = await response.Content.ReadAsStringAsync(token);
throw new InvalidOperationException(
$"Quantum simulator call failed: {(int)response.StatusCode} {errorText}");
}
var payload = await response.Content.ReadFromJsonAsync<ExecuteResponse>(
cancellationToken: token);
if (payload?.Counts is null)
{
throw new InvalidOperationException(
"Quantum simulator response was empty or invalid.");
}
return payload.Counts;
}
With the quantum simulator sidecar in place, the hard-lifting is done. The easy part is now exposing it via an Orpius custom tool. For this we create a class and decorate it with the [Tool], [ToolMethod], and [ToolProperty] attributes. A Roslyn IIncrementalGenerator takes care of the rest.
NOTE: The Orpius SDK takes care of generating the types needed for registration via a Roslyn
IIncrementalGeneratornamedToolRegistryItemGeneratorin the Orpius.Platform.ClientSdk.ProtobufNet.Generators project.
The QuantumQasm3Tool leverages the QuantumSimulatorClient, which is injected via the constructor, as shown:
[Tool]
public class QuantumQasm3Tool
{
readonly QuantumSimulatorClient quantumSimulatorClient;
public QuantumQasm3Tool(QuantumSimulatorClient quantumSimulatorClient)
{
this.quantumSimulatorClient = quantumSimulatorClient
?? throw new ArgumentNullException(nameof(quantumSimulatorClient));
}
...
TIP: If you wish, you could place the client code directly in the
Tool, but I chose to build this out in stages: client first, get that working, then expose it via a Tool class.
The tool has a single method ExecuteQasm3Program, shown below. ExecuteQasm3Program is the method that is ultimately called by your Orpius agent.
The API surface of this method and parameters is automatically provided to the Orpius server; it is stored, an LLM OpenAPI schema generated for it, and it is parsed into the context of the agent, along with the Descriptions to allow the agent to understand how to use it. Neat eh? You don’t need to do anything apart from decorate your class with a few attributes and follow to signature conventions: two parameters, last parameter ICombinedContext object. If you’ve ever used gRPC before, the signature format will look familiar.
[ToolMethod(Description
= "Executes an OpenQASM 3 program on the quantum simulator"
+ " and returns measurement counts. "
+ "'Shots' controls the number of samples taken.")]
public async Task<ExecuteQasm3ProgramResponse> ExecuteQasm3Program(
ExecuteQasm3ProgramRequest request,
ICombinedContext context)
{
if (request is null)
{
throw new ArgumentNullException(nameof(request));
}
if (string.IsNullOrWhiteSpace(request.OpenQasm3Program))
{
throw new RpcException(new Status(
StatusCode.InvalidArgument,
"OpenQasm3Program is required and cannot be empty."));
}
if (request.Shots <= 0)
{
throw new RpcException(new Status(
StatusCode.InvalidArgument,
"Shots must be greater than 0."));
}
CancellationToken token = GetCancellationToken(context);
Dictionary<string, int> counts
= await quantumSimulatorClient.ExecuteAsync(
request.OpenQasm3Program, request.Shots, token)
.ConfigureAwait(false);
return new ExecuteQasm3ProgramResponse
{
Counts = counts
};
}
The API surface for the parameter and return type are also sent to the server. Contained types are also included recursively, meaning that you can have arbitrarily complex data transfer objects.
Any business logic you’d like to have an agent be able to call into can be rolled into a tool like this. There’s very little else that needs to be done apart from some config in the Program class, which will get to at the end of the article.
public class ExecuteQasm3ProgramRequest
{
[ToolProperty(
Required = true,
Description
= """
OpenQASM 3 program text to execute.
(content trimmed for brevity)
""")]
public required string OpenQasm3Program { get; set; }
[ToolProperty(
Description = "Number of shots (samples) to run. Defaults to 1024.")]
public int Shots { get; set; } = 1024;
}
public class ExecuteQasm3ProgramResponse
{
[ToolProperty(
Description = "Measurement counts keyed by bitstring"
+ " outcome (for example, \"00\", \"01\", \"10\", \"11\").")]
public Dictionary<string, int>? Counts { get; init; }
}
Orpius has various internal tools, such as the isolated code compilation and execution, and many others, which allows Orpius agents to achieve a lot out-of-the-box, but to allow them to connect to well-defined external systems with authorization built-in you use ‘custom tools’. A custom tool is a GRPC endpoint that maps requests to a class in your project. The way it works is that would have your application notify Orpius via a GRPC call that your application provides one or more tools that agents in Orpius should be able to call.
On the Custom Tools view in the Orpius Console, we copy the External ID and Access Key 1. We need this information to register our ToolHosting_AspNetCore project as a tools provider.
NOTE: You can create a secure private channel to Orpius during development and production. See Creating a Secure Channel to Orpius
In the next section you’ll see how you can plug the External ID and Access Key to register the tool when your application starts.
All of the connecting with Orpius and registering tools is done automatically via some setup in the Program.cs file in the ASP.NET Core ToolHosting_AspNetCore project. The ToolHosting_AspNetCore project was generated with the Create New Project dialog, to which I added references to the Orpius.Platform.ClientSdk.ProtobufNet project and the Orpius.Platform.ClientSdk.ProtobufNet.Generators projects. Rather that do that, you may prefer to add NuGet package references to the Orpius SDK packages instead:
In Program.Main we use ASP.NET Core’s DI infrastructure to inject a pooled HttpClient instance to the QuantumSimulatorClient.
services.AddHttpClient<QuantumSimulatorClient>(
client =>
{
string? baseUrl = builder.Configuration["QuantumSimulator:BaseUrl"];
if (string.IsNullOrWhiteSpace(baseUrl))
{
throw new InvalidOperationException(
"QuantumSimulator:BaseUrl is not configured.");
}
client.BaseAddress = new Uri(baseUrl, UriKind.Absolute);
});
The HttpClient is passed to the QuantumSimulatorClient during construction:
readonly HttpClient httpClient;
public QuantumSimulatorClient(HttpClient httpClient)
{
this.httpClient = httpClient;
}
The Program.Main creates proxy object that provides the tool registration infrastructure what it needs to register with the Orpius server. It’s added to the ASP.NET Core IServiceCollection. You can add multiple IToolRegistrationParameters implementations, enabling your tools project to provide tools for multiple Orpius Spaces.
The getLocalUrl value needs to point the location of the tools server, and it needs to be resolvable by the Orpius server. It tells the Orpius server where to call for the tools you publish. Ordinarily this will be a production URL or a private channel URL
We parse the External ID and Access Key, which we obtained in the previous step, to the parameters object.
FuncRegistrationParameters toolRegistrationParameters
= new(getLocalUrl: () => new Uri("https://host.docker.internal:7190/"),
getExternalId: () => Guid.Parse("ee2b90ff-a4c6-44bf-93a7-a25b7e3271b0"),
getApiKey: () => Guid.Parse("72e1b1f1-414b-46d9-bcb1-1a736d7e6027"));
services.AddSingleton<IToolRegistrationParameters>(toolRegistrationParameters);
At the top of the Program.cs file we have an assembly-level GenerateToolRegistryItemAttribute:
[assembly: GenerateToolRegistryItem("ToolHosting_AspNetCore.ToolForOrpius.AllTools")]
The ToolRegistryItemGenerator in the Orpius.Platform.ClientSdk.ProtobufNet.Generators project looks for this attribute, and when it finds it, it generates the code describing the API service of the tools in the project.
We pull in the generated AllTools by registering it with the IServiceCollection:
services.AddSingleton<AllTools>();
We also register our quantum tool in the same manner. Note that both classes and interfaces types are supported, allowing you to switch our the implementation for testing and so forth.
services.AddSingleton<QuantumQasm3Tool>();
When the AllTools class is resolved from the container, it automatically registers itself with the IToolsRegistry. The ToolRegistry contains the mappings and forwards incoming tool requests to their respective custom tools.
_ = app.Services.GetRequiredService<AllTools>();
Finally, the Orpius SDK contains a gRPC service: IToolProviderService that allows Orpius to call your server to use tools.
We wire it up like so:
app.MapGrpcService<IToolProviderService>();
There are various headers you can use for authentication. You can use the IToolRegistrationParameters.Headers property, or the RegisterAsProviderRequest.Headers property directly, to provide headers back to your server during an IToolProviderService.UseTool call. The headers are encrypted and stored securely on the Orpius server. This gives you the peace of mind that only your Orpius agent can use your custom tool.
TIP: You can find other examples in the Orpius SDK samples that demonstrate how to set and read headers.
In this article we looked at how we can schedule an AI agent to periodically write and execute OpenQASM code and update a webpage based on the results. We then delved into the implementation and saw how to create a Docker sidecar for Qiskit, call that sidecar from our host tools ASP.NET Core application, and create a custom Tool for Orpius, which can be called by your Orpius AI agent. Finally, we looked at how authentication headers can be used to secure tool calls from Orpius to your server.
I hope you enjoyed this article, and I welcome your feedback and questions.
]]>The work shows how agents on separate Orpius deployments can cooperate through natural-language messages, without shared identifiers, schemas, or any centralised data store. A promising direction for organisations where data cannot move or be unified.
Read the paper on arXiv: Distributed Agent Reasoning Across Independent Systems With Strict Data Locality
]]>Orpius can download images, analyze them, perform activities based on what it sees. Combined with the scheduling capabilities of Orpius, it works even when you’re sleeping, making for one heck of a powerful tool.
I’ve also added an exciting feature revealed near the end of this post (hint: it changes how you’ll see things entirely).
Btw., in-case you’re reading this as a repost, my name’s Daniel, and my co-founder Katka and I are creating Orpius, an Autonomous Business Operations Platform (ABOP).
So, let’s take a look.
In this first screenshot, you see I ask Orpius to examine an image on the web.
The image is supplied to the language model, and also passed in a message to the Orpius Console application, so the user can see it too.
When I try this in ChatGPT, I see:
Next, I give it a more interesting thing to analyze. It’s another image retrieved via http, but this time from a video feed capture.
Orpius is able to leverage the analysis information across all its plugins; web search, web page downloading, scheduling, team management, notifications; and for anything we can’t think of up front, it can compile and execute its own code in an isolated environment.
In the next screenshot, I ask Orpius to analyze the image at 5-minute intervals. I ask it to email me the analysis each time. You see how the schedule item shows up in the Schedule view. When the schedule comes around, Orpius passes the task off to an AI agent, which will do its thing.
Btw, Orpius runs in the cloud, so there’s no need for Orpius Console to remain open.
With Orpius you can create various schedule types: interval, hourly, daily, monthly, yearly; with repetition limiting and schedule expiry, all with time-zone awareness for team scheduling.
In this case, when the interval duration is reached, Orpius shoots me an email (shown below). Look, it even got the makes of the cars. Splendid!
If we wanted to, we could also update a spreadsheet with the data, call an external system… you name it.
Live updates are sent to all team members using the Orpius Console. Orpius has team support. In the next screenshot you see the repetition count updated in real-time.
Team members can work on activities together; sharing files and tasks. Team members can also be AI agents. But more on that in a future post.
So, after I witnessed what Orpius could do with an image source, I got excited about the ability to hook it up to a real video feed. I was pacing back and forth, my mind alight with the possibilities. So, that’s what I did. I introduced real time streaming protocol support.
I found an old Amcrest camera, which I last used as a baby cam for my daughter a few years ago, and I set to work creating the Orpius plugin and infrastructure to make it all happen.
In the next screenshot you see that I tell Orpius to analyze the video from the rtsp://… stream. The camera is pointing out the window of my house.
Notice that I don’t specify a password directly. Orpius has a ‘secrets system’ that parses code and API calls allowing you (the user) to define secrets that are never sent to the LLM service, such as OpenAI or Claude. Which is a big deal if you’re concerned about security and privacy.
Orpius knows that it can use secret values encoded as <#=TokenKey:TokenValue%>, the system takes care of populating the values without passing them to the LLM service.
Btw., I chose that old-school ‘<#=’ funky syntax because its less common these days, and less likely to conflict with other styles.
I’m chuffed about these new Orpius features. I’m also currently adding event driven support, where webhooks can be used to trigger workflows within Orpius. This feature will bring in support for movement activation for cams. I knew that webhooks would be an eventuality down the track, but seeing how useful it would be with the real time streaming support, it motivated me to get it in place now. It could make for a great security/monitoring system. What do you think?
Want more info, add a comment below or visit Orpius.com. Feel free to reach out to me directly.
#AgenticAI #AgenticRAG #avaloniaui
]]>SELECT u.*, a.*
FROM [Bpm].User u
INNER JOIN [Bpm].Account a
ON u.Id = a.UserId
WHERE u.Username = 'foo@exammple.com'
Msg 156, Level 15, State 1, Line 2 Incorrect syntax near the keyword ‘User’.
Turns out ‘User’ is a keyword and I needed to enclose it in square brackets: FROM [Bpm].[User] ....
It’s probably best just to avoid naming things with keywords.
Here’s a query for SQL Server to detect if you have inadvertently named one of your tables with a keyword from one of the following DBMS’s:
-- Step 1: Create a temporary table for reserved keywords
CREATE TABLE #ReservedKeywords (
Keyword NVARCHAR(128) NOT NULL
);
-- Step 2: Insert the reserved keywords into the temporary table
INSERT INTO #ReservedKeywords (Keyword)
VALUES
('ABORT'), ('ABS'), ('ACCESS'), ('ADD'), ('ADMIN'), ('AFTER'), ('AGGREGATE'),
('ALL'), ('ALLOCATE'), ('ALTER'), ('ANALYZE'), ('AND'), ('ANY'), ('ARE'),
('ARRAY'), ('AS'), ('ASC'), ('ASSERTION'), ('AT'), ('AUTHORIZATION'), ('AVG'),
('BACKUP'), ('BEFORE'), ('BEGIN'), ('BETWEEN'), ('BIGINT'), ('BINARY'), ('BIT'),
('BLOB'), ('BOOLEAN'), ('BOTH'), ('BREAK'), ('BY'), ('BYTE'), ('CALL'),
('CASCADE'), ('CASE'), ('CAST'), ('CATALOG'), ('CHAR'), ('CHARACTER'), ('CHECK'),
('CLOSE'), ('CLUSTER'), ('COALESCE'), ('COLLATE'), ('COLUMN'), ('COMMIT'),
('CONNECT'), ('CONSTRAINT'), ('CONTAINS'), ('CONTINUE'), ('CONVERT'), ('COPY'),
('COUNT'), ('CREATE'), ('CROSS'), ('CUBE'), ('CURRENT'), ('CURRENT_DATE'),
('CURRENT_PATH'), ('CURRENT_ROLE'), ('CURRENT_TIME'), ('CURRENT_TIMESTAMP'),
('CURRENT_USER'), ('CURSOR'), ('CYCLE'), ('DATA'), ('DATABASE'), ('DATE'),
('DAY'), ('DBA'), ('DEALLOCATE'), ('DEC'), ('DECIMAL'), ('DECLARE'), ('DEFAULT'),
('DELETE'), ('DESCRIBE'), ('DESCRIPTOR'), ('DETERMINISTIC'), ('DIAGNOSTICS'),
('DISCONNECT'), ('DISTINCT'), ('DO'), ('DOMAIN'), ('DOUBLE'), ('DROP'),
('DYNAMIC'), ('EACH'), ('ELSE'), ('END'), ('END-EXEC'), ('ESCAPE'), ('EXCEPT'),
('EXCEPTION'), ('EXEC'), ('EXECUTE'), ('EXISTS'), ('EXIT'), ('EXTERNAL'),
('EXTRACT'), ('FALSE'), ('FETCH'), ('FIRST'), ('FLOAT'), ('FOR'), ('FOREIGN'),
('FOUND'), ('FREE'), ('FROM'), ('FULL'), ('FUNCTION'), ('GENERAL'), ('GET'),
('GLOBAL'), ('GO'), ('GOTO'), ('GRANT'), ('GROUP'), ('GROUPING'), ('HAVING'),
('HOST'), ('HOUR'), ('IDENTITY'), ('IF'), ('IGNORE'), ('IMMEDIATE'), ('IN'),
('INCREMENT'), ('INDEX'), ('INDICATOR'), ('INITIAL'), ('INITIALLY'), ('INNER'),
('INOUT'), ('INPUT'), ('INSERT'), ('INT'), ('INTEGER'), ('INTERSECT'),
('INTERVAL'), ('INTO'), ('IS'), ('ISOLATION'), ('JOIN'), ('KEY'), ('LANGUAGE'),
('LAST'), ('LEADING'), ('LEAVE'), ('LEFT'), ('LEVEL'), ('LIKE'), ('LIMIT'),
('LOCAL'), ('LOWER'), ('MATCH'), ('MAX'), ('MIN'), ('MINUTE'), ('MODULE'),
('MONTH'), ('NAMES'), ('NATIONAL'), ('NATURAL'), ('NCHAR'), ('NCLOB'), ('NEW'),
('NEXT'), ('NO'), ('NONE'), ('NOT'), ('NULL'), ('NUMERIC'), ('OBJECT'), ('OF'),
('OFF'), ('OFFSET'), ('OLD'), ('ON'), ('ONLY'), ('OPEN'), ('OPTION'), ('OR'),
('ORDER'), ('OUT'), ('OUTER'), ('OUTPUT'), ('OVER'), ('OVERLAPS'), ('PAD'),
('PARAMETER'), ('PARTIAL'), ('PARTITION'), ('PERCENT'), ('PLACING'), ('POSITION'),
('PRECISION'), ('PREPARE'), ('PRIMARY'), ('PRIOR'), ('PRIVILEGES'), ('PROCEDURE'),
('PUBLIC'), ('RANGE'), ('READ'), ('REAL'), ('REFERENCES'), ('RELATIVE'),
('REPLACE'), ('RESTRICT'), ('RETURN'), ('RETURNS'), ('REVOKE'), ('RIGHT'),
('ROLE'), ('ROLLBACK'), ('ROLLUP'), ('ROUTINE'), ('ROW'), ('ROWS'), ('SAVEPOINT'),
('SCHEMA'), ('SCROLL'), ('SEARCH'), ('SECOND'), ('SECTION'), ('SELECT'), ('SESSION'),
('SET'), ('SETS'), ('SHARE'), ('SHOW'), ('SIMILAR'), ('SIZE'), ('SMALLINT'),
('SOME'), ('SPACE'), ('SPECIFIC'), ('SQL'), ('SQLCODE'), ('SQLERROR'), ('SQLSTATE'),
('START'), ('STATEMENT'), ('STATIC'), ('SUBSTRING'), ('SUM'), ('SYSTEM'),
('TABLE'), ('TEMPORARY'), ('THEN'), ('TIME'), ('TIMESTAMP'), ('TO'), ('TRAILING'),
('TRANSACTION'), ('TRANSLATE'), ('TRANSLATION'), ('TRIGGER'), ('TRUE'), ('UNION'),
('UNIQUE'), ('UNKNOWN'), ('UNNEST'), ('UPDATE'), ('USAGE'), ('USER'), ('USING'),
('VALUE'), ('VALUES'), ('VARCHAR'), ('VARIABLE'), ('VARYING'), ('VIEW'), ('WHEN'),
('WHENEVER'), ('WHERE'), ('WITH'), ('WORK'), ('WRITE'), ('YEAR'), ('ZONE');
-- Step 3: Query to find tables with reserved keyword names
SELECT
TABLE_NAME
FROM
INFORMATION_SCHEMA.TABLES
WHERE
TABLE_TYPE = 'BASE TABLE'
AND TABLE_NAME COLLATE Latin1_General_CI_AS IN (SELECT Keyword FROM #ReservedKeywords);
-- Cleanup: Drop the temporary table after use
DROP TABLE #ReservedKeywords;
The list of keyword according to ChatGPT:
ABORT
ABS
ACCESS
ADD
ADMIN
AFTER
AGGREGATE
ALL
ALLOCATE
ALTER
ANALYZE
AND
ANY
ARE
ARRAY
AS
ASC
ASSERTION
AT
AUTHORIZATION
AVG
BACKUP
BEFORE
BEGIN
BETWEEN
BIGINT
BINARY
BIT
BLOB
BOOLEAN
BOTH
BREAK
BY
BYTE
CALL
CASCADE
CASE
CAST
CATALOG
CHAR
CHARACTER
CHECK
CLOSE
CLUSTER
COALESCE
COLLATE
COLUMN
COMMIT
CONNECT
CONSTRAINT
CONTAINS
CONTINUE
CONVERT
COPY
COUNT
CREATE
CROSS
CUBE
CURRENT
CURRENT_DATE
CURRENT_PATH
CURRENT_ROLE
CURRENT_TIME
CURRENT_TIMESTAMP
CURRENT_USER
CURSOR
CYCLE
DATA
DATABASE
DATE
DAY
DBA
DEALLOCATE
DEC
DECIMAL
DECLARE
DEFAULT
DELETE
DESCRIBE
DESCRIPTOR
DETERMINISTIC
DIAGNOSTICS
DISCONNECT
DISTINCT
DO
DOMAIN
DOUBLE
DROP
DYNAMIC
EACH
ELSE
END
END-EXEC
ESCAPE
EXCEPT
EXCEPTION
EXEC
EXECUTE
EXISTS
EXIT
EXTERNAL
EXTRACT
FALSE
FETCH
FIRST
FLOAT
FOR
FOREIGN
FOUND
FREE
FROM
FULL
FUNCTION
GENERAL
GET
GLOBAL
GO
GOTO
GRANT
GROUP
GROUPING
HAVING
HOST
HOUR
IDENTITY
IF
IGNORE
IMMEDIATE
IN
INCREMENT
INDEX
INDICATOR
INITIAL
INITIALLY
INNER
INOUT
INPUT
INSERT
INT
INTEGER
INTERSECT
INTERVAL
INTO
IS
ISOLATION
JOIN
KEY
LANGUAGE
LAST
LEADING
LEAVE
LEFT
LEVEL
LIKE
LIMIT
LOCAL
LOWER
MATCH
MAX
MIN
MINUTE
MODULE
MONTH
NAMES
NATIONAL
NATURAL
NCHAR
NCLOB
NEW
NEXT
NO
NONE
NOT
NULL
NUMERIC
OBJECT
OF
OFF
OFFSET
OLD
ON
ONLY
OPEN
OPTION
OR
ORDER
OUT
OUTER
OUTPUT
OVER
OVERLAPS
PAD
PARAMETER
PARTIAL
PARTITION
PERCENT
PLACING
POSITION
PRECISION
PREPARE
PRIMARY
PRIOR
PRIVILEGES
PROCEDURE
PUBLIC
RANGE
READ
REAL
REFERENCES
RELATIVE
REPLACE
RESTRICT
RETURN
RETURNS
REVOKE
RIGHT
ROLE
ROLLBACK
ROLLUP
ROUTINE
ROW
ROWS
SAVEPOINT
SCHEMA
SCROLL
SEARCH
SECOND
SECTION
SELECT
SESSION
SET
SETS
SHARE
SHOW
SIMILAR
SIZE
SMALLINT
SOME
SPACE
SPECIFIC
SQL
SQLCODE
SQLERROR
SQLSTATE
START
STATEMENT
STATIC
SUBSTRING
SUM
SYSTEM
TABLE
TEMPORARY
THEN
TIME
TIMESTAMP
TO
TRAILING
TRANSACTION
TRANSLATE
TRANSLATION
TRIGGER
TRUE
UNION
UNIQUE
UNKNOWN
UNNEST
UPDATE
USAGE
USER
USING
VALUE
VALUES
VARCHAR
VARIABLE
VARYING
VIEW
WHEN
WHENEVER
WHERE
WITH
WORK
WRITE
YEAR
ZONE
The major cloud providers: Microsoft, Amazon, Google, IBM, and Oracle are racing to bring quantum computing as a service to their offerings. In addition, companies, universities, and even nation states are investing heavily.
Why all the buzz?
Quantum computers offer the potential to bring parallelism to calculations on a scale that cannot be matched by classical computers. They may enable us to model the quantum world, bringing breakthroughs in material science, medicine, you name it.
There already exists actual multi-qubit quantum computers, such as IBM, that allow you to create and run quantum algorithms in the cloud.
Despite the general optimism, there are contrarians who argue that larger multi-qubit systems are not feasible and will never happen. But, the physics underpinning quantum computing has been widely validated experimentally and researches continue to make advances in improving the accuracy of multi-qubit systems.
For software engineers, it’s a field that is ripe for exploration.
In all likelihood, like me, you’re a software engineer looking to cut your teeth with the latest quantum tech. Unfortunately, nearly all of the resources online on the topic of quantum computing come from a mathematics or physics bent; much of the time written by physicists for physicists.
When I began learning quantum theory several months ago, my first step was to plunge head first into what, according to some, is the authoritative text on the subject: Quantum Computation and Quantum Information, by Nielsen and Chuang. Apparently this is the book used in many physics schools. I soon found myself struggling with the linear algebra and I knew I was going to need to take a step back and read up on that. Fortunately I had an old (8th) edition of Elementary Linear Algebra, by Anton sitting on my bookshelf; left over from my undergraduate days, nearly two decades ago. I worked my way through that, and thoroughly enjoyed it. Towards the end, after a few weeks of study, I had another crack at a quantum text. This time I chose Quantum Computing for Computer Scientists by Yanofsky and Mannucci. More and more came into focus now. The only thing noticeably missing from the linear algebra book was tensors. I turned to the web for that, and tensor products turned out to be dead simple.
So, armed with my newly acquired linear algebra, I pushed through the quantum computing book; turning to the web to increase clarity here and there. Eventually I found myself where I wanted to be from the beginning, understanding and constructing quantum circuits.
While the mathematics and notation underpinning quantum theory seems daunting at first, on my journey, I’ve been taken with the elegance by which it all fits together. I wrote this series of articles to provide you with a grounding in the fundamentals of quantum computation without spending a lot of time on quantum mechanics, which is a branch of physics heavy in theory that, while broadening comprehension, may deter a beginner. This series doesn’t spend much time on covering the relevant mathematics up front either, but rather introduces critical mathematics along the way. While there’s quite a bit of math and formulas littered throughout these articles, we work through them together.
Let’s dive in.
In quantum computing, a qubit is analogous to a bit in classical computing. I’m guessing you knew that already. As is a qubyte to a byte. As with classical computing, a qubit has two measurable states but there’s a little more to it.
When you measure a qubit, its quantum state is said to collapse; to a value that is either 0 or 1. Before you measure it, however, the two observable states have a certain probability. You can modify the probabilities of a quantum state, and what’s more, you can employ multiple qubits that affect one another.
A qubit is represented as a vector. The zero qubit state is represented by the single column matrix [1, 0]T. The one qubit state is represented by [0, 1]T. These are known as its basis states. The ‘T’ superscript denotes the transpose of the matrix, and allows the matrix to be presented horizontally. It’s used occasionally to save space.
These two basis states are orthonormal, which means they are orthogonal and normalized. Together they are called the computational basis. Let me explain these terms.
Orthogonal means that the inner product of the matrices is 0. To calculate the inner product (a.k.a. the dot product), we multiply each item in the first matrix with its counterpart in the second matrix and sum them all together, like so:
\[\begin{bmatrix}1 \\ 0\end{bmatrix} \cdot \begin{bmatrix}0 \\ 1\end{bmatrix} = 1 \times 0 + 0 \times 1 = 0\]Normalized means that the probabilities of the observable states add up to 1.
Determining the probability of quantum states is fundamental to quantum information theory, and we delve further into that later in the article. Firstly, however, we need to cover some basic math; complex numbers and matrix multiplication, then familiarize ourselves with Dirac notation.
Though it may appear otherwise skimming over this article, I’ve tried to keep the math simple. There are, however, just a couple operations you need under your belt to be able to follow along. In particular, you need to know how to multiply complex numbers and matrices. We look at those operations now.
In quantum computation, qubits are represented as vectors in 3 dimensional space. In quantum circuits, we rotate and combine them to perform computations. The vectors representing qubits’ state contain complex numbers, and complex numbers are also used to rotate qubits in this space.
A complex number consists of a real part $x$ and an imaginary part $y$, as shown:
\[x + yi\]where $i = \sqrt{-1}$ and $i^{2} = -1$.
When multiplying two complex numbers, you add together the products of the real and imaginary parts of both numbers. See Figure 1.
Multiplying this out gives us:
\[(x_1 + y_1 i)(x_2 + y_2 i) = x_1 x_2 + x_1 y_2 i + y_1 x_2 i + y_1 y_2 i^2\]Since $i^{2} = -1$, this simplifies to:
\[x_1 x_2 - y_1 y_2 + x_1 y_2 i + y_1 x_2 i\]The following is an example:
\[\begin{align} (3 + 2i)(4 + 3i) &= 12 + 9i + 8i + 6i^2 \\ &= 12 + 17i - 6 \\ &= 6 + 17i \end{align}\]When working with quantum states, there are three matrix by matrix multiplication operations that are commonly performed: matrix product, inner product, and tensor product (a.k.a. outer product). We look at the matrix product now and cover the inner and tensor products in later sections, as we need them.
The first thing to note is that calculation of the matrix product is only valid if the number of columns in the first matrix is equal to the number of rows in the second matrix. See Figure 2.
Also notice that the row count for the result equals the row count of the first matrix, and the column count of the result, equals the column count of the second matrix.
The matrix product is generally written without an operator as AB, where A and B are two matrices.
Let’s work through an example, where matrix A and B are presented below.
To calculate AB, we multiply each item in the first row of A by the item in the first column of B with same index, and sum the products. The result is 1×2 + 3×3 + 2×1 = 13. The value 13 is placed into the first cell of the result matrix.
We then stay on the first row of A, but we shift to the next column of B; repeating the process until we get to the end of the columns in B.
We then shift down to the second row of A, and back to the first column in B. After we complete the last row in A, we’re done.
By convention, a matrix is often given a capital letter as an identifier. An element within the matrix is specified using the name of the matrix in lowercase, with its row then column (in that order) shown as subscript. See the following example:
\[A = \begin{bmatrix} a_{00} & a_{01} \\ a_{10} & a_{11} \end{bmatrix}\]The process of multiplying a matrix by a scalar is a simple one: multiply every item in the matrix by the scalar.
If A is the matrix:
\[A = \begin{bmatrix} a_{00} & a_{01} & a_{02} \\ a_{10} & a_{11} & a_{12} \\ a_{20} & a_{21} & a_{22} \end{bmatrix}\]Then multiplying the matrix by a scalar produces:
\[\lambda A = \begin{bmatrix} \lambda a_{00} & \lambda a_{01} & \lambda a_{02} \\ \lambda a_{10} & \lambda a_{11} & \lambda a_{12} \\ \lambda a_{20} & \lambda a_{21} & \lambda a_{22} \end{bmatrix}\]For example, if the scalar multiplier is 2 and A’s values are:
\[A = \begin{bmatrix} 1 & 3 \\ 5 & 2 \end{bmatrix}, \quad \lambda = 2\]Then the result is as follows:
\[\lambda A = 2\begin{bmatrix}1 & 3 \\ 5 & 2\end{bmatrix} = \begin{bmatrix}2 & 6 \\ 10 & 4\end{bmatrix}\]If the scalar is a complex number and/or the matrix contains complex numbers, the procedure does not change. You calculate the products using the rules of complex number multiplication, which we looked at earlier.
Okay, so we’ve gone over some basic math operations that you need to know to follow along. Let’s move on to something more fun.
Dirac notation (also known as bra-ket notation) is everywhere in quantum theory. It’s used to describe quantum states. You can think of it as matrix shorthand.
A single qubit with the zero basis state can be written as a ket, like so:
\[\vert 0 \rangle\]This reads as “ket zero.”
Conversely, a qubit with a one basis state, can be written as:
\[\vert 1 \rangle\]NOTE: In some texts, |0〉 and |1〉 are presented as |↑〉 (spin-up) and |↓〉 (spin-down), respectively. When you visualize a qubit on a three dimensional sphere, |0〉 is up at the north pole and |1〉 is down at the south pole. I use |0〉 and |1〉 exclusively in this series.
Recall that |0〉 represents the column vector [1, 0]T, and 1 represent [0, 1]T.
In Dirac notation, the values within the ket—between the vertical line character ‘|’ and the angled bracket ‘〉’—are tensor products.
The symbol ‘⊗’ is used to denote the tensor product of two matrices. It is calculated by multiplying each item in the first matrix by all items in the second matrix, as illustrated:
\[\begin{alignedat}{2} \begin{bmatrix} a_{1} \\ a_{2} \end{bmatrix} \otimes \begin{bmatrix} b_{1} \\ b_{2} \end{bmatrix} &\!=\! \begin{bmatrix} a_{1}\begin{bmatrix} b_{1} \\ b_{2} \end{bmatrix} \\ a_{2}\begin{bmatrix} b_{1} \\ b_{2} \end{bmatrix} \end{bmatrix} &\!=\! \begin{bmatrix} a_{1} b_{1} \\ a_{1} b_{2} \\ a_{2} b_{1} \\ a_{2} b_{2} \end{bmatrix} \end{alignedat}\]Tensor products are condensed within Dirac notation, like so:
\[\vert 0 \rangle \otimes \vert 1 \rangle = \vert 01 \rangle\]For qubits, the Dirac notation lends itself beautifully to a binary representation. Notice below how entries in the matrix correspond to the binary, and in particular how the first entry in the matrix corresponds to 0 and not 1.
\[\vert 010 \rangle = \begin{bmatrix}0\\0\\1\\0\\0\\0\\0\\0\end{bmatrix} \;\;\longleftrightarrow\;\; \begin{array}{c c c} \text{Binary} & & \text{Decimal} \\ 000 & & 0 \\ 001 & & 1 \\ \color{red}{010} & & \color{red}{2} \\ 011 & & 3 \\ 100 & & 4 \\ 101 & & 5 \\ 110 & & 6 \\ 111 & & 7 \end{array}\]NOTE: In some texts, the leading 0’s within a ket are omitted and replaced with a subscript indicating the length. So that |0010⟩ becomes |104⟩. I don’t use that notation in this series, but you may see it elsewhere.
You can now see how |1⟩ ⊗ |0⟩ are combined by calculating the tensor product of the matrices, like so:
\[\vert 0 \rangle \otimes \vert 1 \rangle = \begin{bmatrix}1 \\ 0\end{bmatrix} \otimes \begin{bmatrix}0 \\ 1\end{bmatrix} = \begin{bmatrix}0 \\ 1 \\ 0 \\ 0\end{bmatrix} = \vert 01 \rangle\]In a quantum circuit, the inputs of the circuit are combined as tensor products. We explore this later in the series.
If the Dirac notation points to the left rather than the right, as in: 〉0|, this is called a bra. Together they form a bra-ket.
The bra is the conjugate transpose of the ket. The conjugate transpose is also known as the adjoint matrix, and yet another name is the Hermitian transpose.
To obtain the conjugate transpose, the matrix is rotated and each entry is complex conjugated. For a single column matrix, it just means we turn it horizontally and then take the complex conjugate of each entry. See Figure 3.
The complex conjugate simply means changing the sign of the imaginary part.
For example, if $z = 2 + 3i$, then the complex conjugate is $\overline{z} = 2 - 3i$.
Why Complex Numbers?
You may wonder why quantum theory relies so heavily on complex numbers. As Yanofsky and Mannucci point out [1], if you add two positive real numbers, the result will always increase. That is not the case with complex numbers. You can add two complex numbers and produce a smaller result. In fact, they may even cancel each other out. This is referred to as interference, and it is sometimes employed deliberately to eliminate unwanted states in quantum algorithms.
In the following examples we use the variables a and b, such that a,b ∈ Cd. In other words, a and b denote single column matrices of complex numbers with the number of rows equal to d. Most of the time when we are working with qubits, so the dimension count is 2.
In the following examples, we use the variables $a$ and $b$, such that $a, b \in \mathbb{C}^{d}$. In other words, $a$ and $b$ denote single-column matrices of complex numbers with the number of rows equal to $d$. Most of the time when we are working with qubits, the dimension count is 2.
The following illustrates obtaining a bra from a ket:
\[\langle a \rvert = \lvert a \rangle^{\dagger} = \begin{bmatrix}\overline{a}_{1} \\ \overline{a}_{2} \\ \vdots \\ \overline{a}_{d}\end{bmatrix}^{\mathsf{T}} = \begin{bmatrix}\overline{a}_{1} & \overline{a}_{2} & \cdots & \overline{a}_{d}\end{bmatrix}\]This process is reversible. To obtain a ket from a bra, do the same thing again: calculate the conjugate transpose.
When combined, a bra-ket ⟨b|a⟩ represents the inner product of b and a. It’s sometimes written as ⟨b,a⟩. The inner product is the sum of the products of corresponding items. This results in a complex scalar value (with or without an imaginary part). Scalar means that it’s not a vector; it’s a magnitude without direction.
\[\langle b \vert a \rangle = b \cdot a = a_{1} b_{1} + a_{2} b_{2} + \cdots + a_{d} b_{d}\]All quantum states are normalized. That is ⟨a|a⟩ = 1. This has important implications for the probability of states. We return to it in a later section.
We’ve seen that quantum theory relies on complex numbers and vectors to describe quantum states. This algebraic structure is termed a complex vector space and is also known as Hilbert Space.
Another combination of the Dirac notation, which I include for completeness, is the ket-bra. It’s written like this |a⟩⟨b| or sometimes |aXb|. A ket-bra is the tensor (or outer) product and is represented by a d × d matrix:
\[\lvert a \rangle \langle b \rvert = \begin{bmatrix} a_{1} b_{1} & a_{1} b_{2} & \cdots & a_{1} b_{d} \\ a_{2} b_{1} & a_{2} b_{2} & \cdots & a_{2} b_{d} \\ \vdots & \vdots & \ddots & \vdots \\ a_{d} b_{1} & a_{d} b_{2} & \cdots & a_{d} b_{d} \end{bmatrix}\]TIP: In quantum theory, it’s common to see the Greek characters φ (phi) and ψ (psi) used as variable names in bras and kets. For example, you often see a quantum state expressed as $\vert \psi \rangle = \dots$. Don’t be put off by the Greek characters, foreign notation, and seemingly complex algebra. It all appears far more complex than it actually is.
We learned in an earlier section that when you measure a qubit, its quantum state collapses to either 0 or 1. To which value it collapses depends on the way the qubit has been configured. You can change the probability of a qubit collapsing to a particular value. By doing so, you place the qubit into a superposition.
Now, for a qubit that is in a pure basis state, either |0⟩ or |1⟩, the result is predetermined. It has a 100% chance of collapsing to its respective value. In other words, if you measure a qubit that was placed in the |0⟩ state, for example, you always get 0 because the probability of collapsing to 0, is 1; and the probability of collapsing to 1, is 0.
But, if you employ a certain quantum gate in your quantum circuit, you can split the probability of the qubit collapsing to 0 or 1, to a 50/50 chance either way. In which case, it is said to be in a superposition of both states.
When a qubit is in a superposition, its value is undetermined until it’s measured. In this state, it is neither 0 nor 1 in the classical sense, but a superposition of both possibilities.
This is such an unusual phenomenon, physicists have been unable to explain it using classical physics. Yet, it has been widely observed experimentally. Remember the double slit experiment? A photon seemingly goes everywhere, interfering with itself, before landing on a spot. So to does our qubit exist in all observable states until it is measured.
Disambiguating the Term “State” When one or more qubits make up a quantum system, this system has an overall quantum state at any one time. However, the system also has a set of distinct states that it may collapse to when measured. We’ll call these states: observable states.
The quantum state of one or more qubits can be described using Dirac notation and simple algebra. Observable states and associated probabilities comprise the qubit’s superposition.
A single qubit can be described by a linear combination of |0〉 and |1〉, such that:
\[\vert \Psi \rangle = \alpha \vert 0 \rangle + \beta \vert 1 \rangle\]The coefficients $\alpha$ (alpha) and $\beta$ (beta) are known as complex amplitudes or probability amplitudes. As Yanofsky and Mannucci point out [1], the name amplitude comes from the fact that a quantum state is a wave, and a wave is characterised by its amplitudes.
NOTE: Probability amplitudes are not measurable. When a qubit is measured it collapses to one of its observable states. We can manipulate the probability amplitudes, but not observe their values directly.
To calculate the probability of qubit collapsing to a particular state, we take the square of the modulus of its coefficient. This is known as the Born rule.
So, for the $\vert \psi \rangle$ example shown above, the probability of $\vert 0 \rangle$ is $\lvert \alpha \rvert^{2}$.
The modulus of a complex number is calculated like so:
\[\lvert x + i y \rvert = \sqrt{x^{2} + y^{2}}\]To calculate the probability we square that number. All together this can be written succinctly as shown:
\[P(x_i) = \lvert \langle x_i \vert \psi \rangle \rvert^{2}\]This is saying that to calculate the probability of the observable state $x_i$ (which is either 0 or 1 for a qubit), you square the modulus of the dot product. In other words, you project the state you are interested in onto the superposition.
Don’t worry if the algebra doesn’t make sense yet. Next we look at an example, and then we further illustrate it using matrices.
Say our qubit superposition is given by the following:
\[\vert \psi \rangle = \frac{1}{\sqrt{3}} \vert 0 \rangle + \sqrt{\frac{2}{3}} \vert 1 \rangle\]Then the probability of collapsing to 0 is given by:
\[P(0) = \lvert \langle 0 \vert \left( \frac{1}{\sqrt{3}} \vert 0 \rangle + \sqrt{\frac{2}{3}} \vert 1 \rangle \right) \rvert^{2} = \left\lvert \frac{1}{\sqrt{3}} \langle 0 \vert 0 \rangle + \sqrt{\frac{2}{3}} \langle 0 \vert 1 \rangle \right\rvert^{2}\]Now, we can reduce ⟨0|0⟩ to 1 by calculating the dot product, as shown:
\[\langle 0 \vert 0 \rangle = \begin{bmatrix}1 \\ 0\end{bmatrix} \cdot \begin{bmatrix}1 \\ 0\end{bmatrix} = 1 \times 1 + 0 \times 0 = 1\]and because ⟨0| and |1〉 are orthogonal, there inner product is 0, as shown:
\[\langle 0 \vert 1 \rangle = \begin{bmatrix}1 \\ 0\end{bmatrix} \cdot \begin{bmatrix}0 \\ 1\end{bmatrix} = 1 \times 0 + 0 \times 1 = 0\]So, if we replace those brakets in our probability formula, we see that:
\[P(0) = \left\lvert \frac{1}{\sqrt{3}} \times 1 + \sqrt{\frac{2}{3}} \times 0 \right\rvert^{2} = \frac{1}{3}\]Alternatively, we can look at the same problem, but substitute matrices for our states and calculate the probability that way.
\[P(0) = \left\lvert \begin{bmatrix}1 \\ 0\end{bmatrix} \cdot \left( \frac{1}{\sqrt{3}} \begin{bmatrix}1 \\ 0\end{bmatrix} + \sqrt{\frac{2}{3}} \begin{bmatrix}0 \\ 1\end{bmatrix} \right) \right\rvert^{2} = \left\lvert \begin{bmatrix}1 \\ 0\end{bmatrix} \cdot \begin{bmatrix} \frac{1}{\sqrt{3}} \\ \sqrt{\frac{2}{3}} \end{bmatrix} \right\rvert^{2} = \left\lvert \frac{1}{\sqrt{3}} \right\rvert^{2} = \frac{1}{3}\]Hopefully the Dirac notation version makes a bit more sense now.
We know that the sum of the probabilities in a probability distribution is always $1$. We also learned earlier that all quantum states are normalised, i.e., $\langle a \vert a \rangle = 1$. For orthonormal bases, such as $[0, 1]^{\mathsf{T}}$ and $[1, 0]^{\mathsf{T}}$, the observable states form a probability distribution. If you sum the probabilities of all observable states, they come to $1$, as described by the formula:
\[\sum_{i} P(x_i) = 1\]Therefore, we can calculate the probability of the qubit collapsing to 1, by calculating the complement of P(0), like so:
\[P(1) = 1 - P(0) = \frac{2}{3}\]So far we’ve looked at the quantum states of single qubits. We can, of course, create quantum states with multiple qubits. These are known as multi-partite quantum states.
To do so, we combine states using tensor products. For example, if qubit A is in the state $\vert \psi \rangle_{A} = \vert 0 \rangle$ and qubit B is in the state $\vert \psi \rangle_{B} = \vert 1 \rangle$, then the total state is given by:
\[\vert \psi \rangle_{AB} = \vert 0 \rangle_{A} \otimes \vert 1 \rangle_{B} = \vert 01 \rangle_{AB}\]In this case, we can measure the state of qubit A without collapsing the state of qubit B. The individual states are said to be uncorrelated.
We can, however, place qubits into a state, where measuring one affects another. This is known as entanglement.
For instance, take a well known state (one of the Bell states, which we discuss later), this state describes two qubits in superposition:
\[\vert \phi \rangle = \frac{\vert 00 \rangle + \vert 11 \rangle}{\sqrt{2}}\]The state of the qubits when measured will have a 50% chance of being either 00 or 11.
If we were to measure just one of the qubits, it would cause the other’s state to immediately collapse to the same value. The qubits are said to be entangled. Even if the entangled qubits are far away from each other, possibly light years. This is what Einstein described as “spooky action at a distance.”
When we look at the mathematics governing entanglement, we can use the matrix representation to tell us if the qubits are entangled.
As Yanofsky and Mannucci point out [1], a vector that can be written as the tensor product of two vectors is called separable.
In contrast, if the tensor product state of two qubits cannot be factored, they are said to be entangled. This is pointed out in Andrew Helwer’s introductory video on quantum computing.
For example, if we take the state |01〉, and forget for a moment that we know what the tensor product representation is already.
\[\vert 01 \rangle = \begin{bmatrix}0 \\ 1 \\ 0 \\ 0\end{bmatrix} = \begin{bmatrix}a \\ b\end{bmatrix} \otimes \begin{bmatrix}c \\ d\end{bmatrix}\]We can see that ac = 0, ad = 1, bc = 0, and bd = 0.
If we solve for a, b, c, and d; we get a = 1, b = 0, c = 0, and d = 1. We can factor it, therefore we know |01〉 is separable and not entangled.
\[\vert 01 \rangle = \begin{bmatrix}0 \\ 1 \\ 0 \\ 0\end{bmatrix} = \begin{bmatrix}1 \\ 0\end{bmatrix} \otimes \begin{bmatrix}0 \\ 1\end{bmatrix}\]In contrast, if we look at the |φ+〉 state, it is a two qubits state in equal superposition. The matrix representation is calculated below:
\[\frac{\vert 00 \rangle + \vert 11 \rangle}{\sqrt{2}} = \frac{1}{\sqrt{2}}\left(\begin{bmatrix}1 \\ 0\end{bmatrix} \otimes \begin{bmatrix}1 \\ 0\end{bmatrix}\right) + \frac{1}{\sqrt{2}}\left(\begin{bmatrix}0 \\ 1\end{bmatrix} \otimes \begin{bmatrix}0 \\ 1\end{bmatrix}\right) = \frac{1}{\sqrt{2}}\begin{bmatrix}1 \\ 0 \\ 0 \\ 0\end{bmatrix} + \frac{1}{\sqrt{2}}\begin{bmatrix}0 \\ 0 \\ 0 \\ 1\end{bmatrix} = \begin{bmatrix}\frac{1}{\sqrt{2}} \\ 0 \\ 0 \\ \frac{1}{\sqrt{2}}\end{bmatrix}\]In this case, the matrix is not factorable. We have $ac = \tfrac{1}{\sqrt{2}}$, $ad = 0$, $bc = 0$, and $bd = \tfrac{1}{\sqrt{2}}$. There is no solution for $a$, $b$, $c$, and $d$. Therefore, the matrix is not separable and the qubits are entangled. In fact, because of the equal probability of the two states $\vert 00 \rangle$ and $\vert 11 \rangle$, the Bell state is said to be maximally entangled. They are as entangled as you can get.
But, how do we create a Bell state? We explore that in Part 2 of the series. Next, we look at visualizing single qubit states.
To recap, as quantum engineers, we have the opportunity to manipulate the probabilities using quantum gates in our quantum circuits. We can also combine qubits in such a way that they correlate with one another. We can even leverage quantum entanglement to instantly affect the shared state of multiple qubits, even if the qubits are far away from one another.
Many operations on single qubits can be neatly visualized on a 3 dimensional unit sphere, known as the Bloch sphere. See figure 4.
A qubit can be represented as a line of length 1 from the center of the sphere to the sphere’s surface.
At the north pole sits basis state |0⟩; at the south, |1⟩.
Before collapsing into a basis state, a qubit’s superposition may be located anywhere on the Bloch sphere. You can think of θ (theta) as latitude and φ (phi) as longitude. As we move vertically, north or south, the latitude changes (θ), and as we move horizontally the longitude (φ) changes.
While the latitude affects the probability of the qubit collapsing to a particular basis state, the longitude does not. The longitude is referred to as the qubit’s phase.
We saw earlier that a qubit’s superposition can be written:
\[\vert \psi \rangle = \alpha \vert 0 \rangle + \beta \vert 1 \rangle\]where α and β are its probability amplitudes, which are complex numbers.
Recall that a complex number consists of a real part $x$ and an imaginary multiplier $y$.
\[z = x + i y\]A complex number can be represented by just $x$ and $y$. The pair $(x, y)$ is called its Cartesian representation. It can be graphed on a two dimensional Cartesian plane. Such a graph is called an Argand diagram. See figure 5.
The arg function can be used to calculate $\theta$. In this case, $\operatorname{arg}$ is equivalent to $\operatorname{atan2}$, as shown:
\[\operatorname{arg}(x + i y) = \operatorname{atan2}(y, x) = \tan^{-1}\!\left(\frac{y}{x}\right)\]Later in this section you will see how to use the $\operatorname{arg}$ function to calculate the angles $(\theta, \phi)$ on the Bloch sphere.
We can convert the Cartesian coordinates to polar representation. The polar coordinates consist of the modulus $\rho$ and the angle $\theta$. Recall that to calculate the modulus we use:
\[\rho = \lvert x + i y \rvert = \sqrt{x^{2} + y^{2}}\]To calculate the angle, we use:
\[\theta = \tan^{-1}\!\left(\frac{y}{x}\right)\]To convert back from polar to Cartesian representation, use:
\[x = \rho \cos(\theta), \quad y = \rho \sin(\theta)\]Feel free to merely skim through this section. While its useful to understand how states are translated to the Bloch sphere, you can always return to this at a later stage.
The coefficients $\alpha$ and $\beta$ can be visualised on the Bloch sphere as a point corresponding to the two angles $(\theta, \phi)$.
It turns out that because $\lvert \alpha \rvert^{2} + \lvert \beta \rvert^{2} = 1$, we can calculate a qubit’s position on the Bloch sphere using the following:
\[\vert \psi \rangle = \cos\!\left(\frac{\theta}{2}\right) \vert 0 \rangle + e^{i\phi} \sin\!\left(\frac{\theta}{2}\right) \vert 1 \rangle\]where $0 \leq \theta \leq \pi$ and $0 \leq \phi \leq 2\pi$
That gives us
\[\alpha = \cos\!\left(\frac{\theta}{2}\right) \quad \text{and} \quad \beta = e^{i\phi} \sin\!\left(\frac{\theta}{2}\right).\]To find the angles, use
\[\theta = 2 \cos^{-1}(\lvert \alpha \rvert) \quad \text{and} \quad \phi = \operatorname{arg}(\beta) - \operatorname{arg}(\alpha).\]NOTE: You can also find these values via the state’s density matrix, which is calculated by its ket–bra: $\rho = \vert \psi \rangle \langle \psi \vert$. This is outside the scope of this article.
In this article, we explored the differences between qubits and classical bits. We looked at the computation basis for qubits. We saw how to describe quantum state using Dirac notation. We observed that qubits can be placed into superposition, and saw how to calculate the probability of observable states. We also saw how an entangled qubit can affect the quantum state of the pair. Finally we took a ride around the Block sphere, and saw how a qubit’s state can be visualized in 3 dimensions.
In the next part, we explore how quantum gates are used to build quantum circuits, which ultimately puts us on the road to materializing quantum algorithms. I hope you’ll join me.
Thanks for reading and I hope you found this article useful. If so, then I’d appreciate it if you would please rate it and/or leave feedback below.
The following sources were used in the preparation of this article:
Yanofsky, N., & Mannucci, M. (2008). Quantum Computing for Computer Scientists. Cambridge University Press.
Anton, H. (2000). Elementary Linear Algebra (8th ed.). Wiley.
Nielsen, M., & Chuang, I. (2010). Quantum Computation and Quantum Information (10th ed.). Cambridge University Press.
Glendinning, I. (2005). The Bloch Sphere.
https://www.vcpc.univie.ac.at/~ian/hotlist/qc/talks/bloch-sphere.pdf
Dutta, S. (2019). If quantum gates are reversible how can they possibly perform irreversible classical AND and OR operations?
https://quantumcomputing.stackexchange.com/questions/131/if-quantum-gates-are-reversible-how-can-they-possibly-perform-irreversible-class
Wolf, R. (n.d.). Quantum Computing: Lecture Notes.
https://homepages.cwi.nl/~rdewolf/qcnotes.pdf
Wikipedia contributors. (2019). Quantum logic gate.
https://en.wikipedia.org/wiki/Quantum_logic_gate
Glendinning, I. (2010). Rotations on the Bloch Sphere.
https://www.vcpc.univie.ac.at/~ian/hotlist/qc/talks/bloch-sphere-rotations.pdf
Hui, J. (2018). What are Qubits in Quantum Computing?
https://medium.com/@jonathan_hui/qc-what-are-qubits-in-quantum-computing-cdb3cb566595
This article was originally published on CodeProject, where reader comments available:
]]>Just about every app needs a settings screen. A lot of developers choose to simply build-out static UI; hard-wiring buttons and text fields to a setting backing store. If one does this, however, eventually, as the number of settings grows, technical debt increases; making refactoring your settings screen into categories, or changing how the settings are stored or displayed, evermore difficult.
That’s why I built an options system into CodonFX, which integrates with an settings system and an isolated storage backing store, which can be swapped out for a SQLite backing store. The options system in Codon has probably saved me months of development time, and allowed me to do some pretty neat things with little effort, such as exporting and importing options.
With the Codon options system, a single line of code can be used to materialize an option on an option screen that writes itself to a backing store. See the following:
generalOptions.Add(new BooleanUserOption(() => "Boolean 1 title", "Boolean1Key", () => false));
Here we create a BooleanUserOption, which is rendered as a switch on the options screen, and automatically writes its value to Codon’s ISettingsService using the specified string key. The title for the option is a lambda expression, which allows you to easily localize it, so that if the UI language changes the title will be displayed in the correct language.
There are a bunch of built-in option types, representing common setting types, including:
BooleanUserOptionDoubleUserOptionIntUserOptionObjectUserOptionStringUserOptionThere are others that are used to present settings in different ways, including:
CommandOptionCompositeOptionListOptionRangeUserOptionCommandOption is used to present a button, that when clicked/tapped executes and ICommand.
CompositeOption allows you to create your own custom behavior with potentially multiple options being rendered in custom UI.
ListOption allows you, for example, to present an enumeration of values that render as a drop down list.
RangeUserOption can be used to present a slider to the user, for writing a double or int value to the backing store.
You can, of course, create custom IUserOption classes, to suite the needs of your application.
I’ve put together a small sample for UWP to demonstrate it in a UWP app. Codon is cross-platform, and you can see the option’s system in action in apps such as Surfy Browser for Android.
In the sample you see the projects: a UWP app project and a .NET Standard class library. The user options system is located in the Codon.Extras.Core NuGet package, which is referenced by the class library. The UWP app project references the package NuGet Codon.Extras.Uwp.
The class library contains various classes including a Bootstrapper class, whose Run method is called when the app starts.
While not absolutely necessary, the AppSettings class has strongly typed properties representing settings, which gives you compile-time confidence that your settings are being referred to correctly.
The partial class located in AppSettings.UserOptions.cs is responsible for registering user options that are presented on the OptionsPage. Generally speaking, the user options represent a subset of the settings.
The ConfigureUserOptions method of the AppSettings class, requires the IUserOptionsService. See Listing 1.
The userRoles parameter is provided just to demonstrate how you might display a different set of options depending on the privileges of the user. This would be more applicable for an enterprise scenario. I do this in one of my apps, and you may not need it.
The IUserOptionsService implementation allows to register multiple option categories, via its Register method. It accepts an OptionCategory method and a list of options that should appear in the category. In some of my apps I display option categories in tabs or sometimes, expandable groups.
When you add an options to a category’s option collection, it is automatically displayed on the options page. Each UserOption object must have a unique key. Lambda expression are used for most of the properties to allow your app to switch languages without requiring a restart.
You can specify a template for the option by setting its TemplateFunc property.
For more information see the UserOptionBase implementations.
Listing 1. AppSettings.ConfigureUserOptions method.
partial class AppSettings
{
public void ConfigureUserOptions(IUserOptionsService userOptionsService, UserRoles userRoles)
{
OptionCategory defaultCategory = new OptionCategory(OptionCategoryIds.General, () => "General");
var generalOptions = new List<IUserOption>
{
new StringUserOption(() => "String 1", String1Key, () => string1DefaultValue),
new BooleanUserOption(() => "Boolean 1", Boolean1Key, () => boolean1DefaultValue)
};
userOptionsService.Register(generalOptions, defaultCategory);
}
}
I mentioned that the AppSettings class is not really necessary. But I like to use it so I can easily refactor the setting names without fear of breaking something.
For completeness I’d like to mention that I use a Resharper live template for defining a setting. See Listing 2. $SettingName$ and $Type$ are the only two editable values. $SettingName$ is defined as ‘Suggest name for a variable’ in the property grid for the template. $Type$ is set to ‘Guess type expected at this point.’
Depending on where you define your AppSettings class, you may want to alter the visibility of the setting name and setter from private to internal or public.
Listing 2. Resharper Live Template for a Setting
public const string $SettingName$Key = "$SettingName$";
static $Type$ $SettingNameLower$DefaultValue = $DefaultValue$;
public $Type$ $SettingName$
{
get => settingsService.GetSetting($SettingName$Key, $SettingNameLower$DefaultValue);
private set => settingsService.SetSetting($SettingName$Key, value);
}
When the app starts up, the Bootstrapper class’s Run method is called via the App class in the UWP app project, as shown in the following excerpt:
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
...
if (!bootstrapperRan)
{
bootstrapperRan = true;
var bootstrapper = new Bootstrapper();
bootstrapper.Run();
}
...
}
Sometimes your bootstrapper may need to go off and perform some asynchronous activity, in which case you’ll want to make the Run method async, and handle errors appropriately.
The Bootstrapper class, registers the AppSettings class as a singleton. See Listing 3.
TIP:Depending on the needs of your app, you may need to implement a platform specific bootstrapper, for each of your platforms. I usually do that, and have the platform-specific bootstrappers call Run on the non-platform-specific bootstrapper.
You may notice in the code that the AppSettings class requires an ISettingsService instance as a constructor parameter. Dependency injection is used to resolve the default instance, using the Codon frameworks default IoC container, the FrameworkContainer class.
In case you’re interested in the Codon framework’s internals, FrameworkContainer locates default type mappings using interface attributes, using Codon’s DefaultType and DefaultTypeName attributes; or the .NET Standard DefaultValueAttribute. If you take a look at the ISettingsService source, you see how it’s decorated with both a DefaultType and a DefaultTypeName attribute. DefaultTypeName takes precedence, and is used to locate a platform specific implementation of the interface, if it exists. If a type identified by DefaultTypeName can’t be located, the container falls back to DefaultType.
We could configure the user options when the AppSettings class is instantiated, which would allow us to pass the IUserOptionsService using DI, but I chose to use an explicit method call since we might wish to postpone configuring the user options to optimize app start time.
Listing 3. Bootstrapper class.
public class Bootstrapper
{
public void Run()
{
Dependency.Register<AppSettings, AppSettings>(true);
var appSettings = Dependency.Resolve<AppSettings>();
appSettings.ConfigureUserOptions(Dependency.Resolve<IUserOptionsService>(), UserRoles.User);
}
}
The OptionsViewModel class, in the class library project, contains a Groupings property, which retrieves the UserOptionGroupings from the IUserOptionsService, like so:
public IUserOptionGroupings Groupings =>
Dependency.Resolve<IUserOptionsService>().UserOptionGroupings;
The OptionsPage class exposes an instance of the OptionsViewModel via the IoC container, as shown in Listing 4.
We use both x:Bind and x:Binding expression on the XAML page, and thus the OptionsViewModel instance is exposed both as a property and set as the DataContext of the page. In case you’re not aware, the context of x:Bind is a property of the Page, whereas the good old x:Binding expression uses the Page’s DataContext when resolving properties.
Listing 4. OptionsPage class
public sealed partial class OptionsPage : Page
{
public OptionsPage()
{
this.InitializeComponent();
DataContext = Dependency.Resolve<OptionsViewModel, OptionsViewModel>(true);
}
public OptionsViewModel ViewModel
{
get => DataContext as OptionsViewModel;
set => DataContext = value;
}
}
Within the OptionsPage.xaml file, you see that the page resources include a CollectionViewSource declaration, whose Source property is bound to the view-model’s Groupings property. See Listing 5.
We use a custom template selector to determine the DataTemplate to use for each option in the CollectionViewSource.
Listing 5. OptionsPage Resources element
<Page.Resources>
<CollectionViewSource x:Key="optionsViewSource"
IsSourceGrouped="True" Source="{x:Bind ViewModel.Groupings}" />
<local:OptionTemplateSelector
x:Key="optionTemplateSelector"
Templates="{StaticResource OptionTemplateCollection}">
</local:OptionTemplateSelector>
</Page.Resources>
The OptionTemplateSelector has a Templates property that is bound to a resource located in App.xaml. See Listing 6.
The NamedTemplateCollection includes all the templates, used to display each user option. There is a String template and a Boolean template. The names String and Boolean map to the TemplateName properties of the StringUserOption and the BooleanUserOption class respectively.
NOTE: You can override the template used by a user option by setting its
TemplateNameproperty.
Listing 6. NamedTemplateCollection element
<local:NamedTemplateCollection x:Key="OptionTemplateCollection">
<local:NamedTemplate Name="String">
<local:NamedTemplate.DataTemplate>
<DataTemplate>
<TextBox
Header="{Binding UserOption.Title, Mode=OneWay}"
Text="{Binding Setting, Mode=TwoWay}"
Style="{StaticResource OptionBox}" />
</DataTemplate>
</local:NamedTemplate.DataTemplate>
</local:NamedTemplate>
<local:NamedTemplate Name="Boolean">
<local:NamedTemplate.DataTemplate>
<DataTemplate>
<ToggleSwitch
Header="{Binding UserOption.Title, Mode=OneWay}"
IsOn="{Binding Setting, Mode=TwoWay}"
Margin="{StaticResource OptionItemMargin}" />
</DataTemplate>
</local:NamedTemplate.DataTemplate>
</local:NamedTemplate>
</local:NamedTemplateCollection>
The custom template selector is named OptionTemplateSelector and it sub-classes Windows.UI.Xaml.Controls.DataTemplateSelector. See Listing 7.
The SelectTemplateCore method attempts to retrieve a template whose name matches that of the TemplateName property of the IUserOption. A cache, which is a Dictionary<string, NamedTemplate> is used for efficient O(1) retrieval of templates.
Listing 7. OptionTemplateSelector class
public class OptionTemplateSelector : DataTemplateSelector
{
public NamedTemplateCollection Templates { get; set; }
IDictionary<string, NamedTemplate> cache { get; set; }
void InitTemplateCollection()
{
cache = Templates?.ToDictionary(x => x.Name)
?? new Dictionary<string, NamedTemplate>();
}
protected override DataTemplate SelectTemplateCore(
object item, DependencyObject container)
{
if (cache == null)
{
InitTemplateCollection();
}
if (item != null)
{
var readerWriter = (IUserOptionReaderWriter)item;
var templateName = readerWriter.UserOption.TemplateName;
cache.TryGetValue(templateName, out NamedTemplate keyedTemplate);
if (keyedTemplate != null)
{
return keyedTemplate.DataTemplate;
}
}
DataTemplate result = base.SelectTemplateCore(item, container);
return result;
}
}
Back in the OptionsPage.xml file we see that options are rendered within a ListView. See Listing 8. The ListView is bound to the CollectionViewSource to retrieve its option groupings, and OptionTemplateSelector retrieves the DataTemplate objects for each option.
Listing 8. Options are rendered in a ListView
<ListView ItemsSource="{Binding Source={StaticResource optionsViewSource}}"
ItemTemplateSelector="{StaticResource optionTemplateSelector}"
SelectionMode="None">
<ListView.ItemContainerStyle>
<Style TargetType="ListViewItem">
<Setter Property="HorizontalContentAlignment" Value="Stretch" />
</Style>
</ListView.ItemContainerStyle>
</ListView>
The sample app displays its options as shown in the following figure:
An app’s functionality grows and changes over time. When building a settings screen for your app, it’s prudent to engineer it so that you can easily add settings from the screen without having to spend time re-working the user interface. One way to achieve that is by using a third-party framework like Codon FX, which allows you to add a new user option to your app with a single line of code.
In this article you’ve seen how to configure a .NET Standard project and a UWP app to use Codon FX. You looked at defining an AppSettings class containing settings used throughout your app, and at exposing a subset of those settings as user options.
You saw how to create DataTemplate elements for user options, and at consuming a collection of data templates to render each user option on a settings screen.
I hope you find this article useful. If so, then I’d appreciate it if you would leave feedback below.
]]>Have you ever created a view-model for your app that contains an ICommand that needs to perform some asynchronous activity? Such as calling a web API or saving data to a file? If you have, you’ll know that the synchronous ICommand interface doesn’t lend itself easily to asynchronous operations. You end up having to build a mini-state-machine to disable and re-enable the command target when the command completes. Wouldn’t it be nice if commands could function asynchronously? Well, in Codon, they can.
Codon FX is a cross-platform framework for building maintainable applications. Codon comes with rich commanding infrastructure. As you’d expect there is a basic ICommand implementation: ActionCommand, that allows you to supply delegates that are called during command execution or when evaluating the command’s Enabled property. There is also a UICommand class that, in addition to the features of the ActionCommand class, provides text, icon, and visibility support.
Now, you’d be forgiven for thinking that these ICommand implementations, residing in Codon’s core .NET Standard library, are all that Codon has to offer as far as commanding goes. But they’re not. In Codon’s Extras package there exists a number of other commands, which are analogous to those in the core library, but offer async support. AsyncActionCommand brings in asynchronous method support, yet also implements ICommand seamlessly, making it compatible with the built-in commanding infrastructure of UWP, WPF, Xamarin Forms, and Codon’s Xamarin Android binding system.
In this post you look at using the AsyncActionCommand. You see how to create a view-model with an asynchronous command that kicks of a potentially long running operation. You also explore how to globally handle exceptions that occur during the execution of an asynchronous operation.
Codon is built on .NET Standard. It has platform specific packages to support its dialog service and a number of other services. But, if you don’t need the IDialogService implementation, page navigation, or any of the other platform specific features, then a NuGet reference to Codon or Codon.Extras.Core will suffice.
The sample UWP app makes use of Codon’s IDialogService. For that reason, I’ve added a reference to the Codon.Extras.Uwp package.
The MainViewModel class in the sample contains a single ICommand named DoWorkCommand. See Listing 1.
DoWorkCommand is created with the following two parameters:
DoWorkAsync,CanDoWorkAsync.There isn’t a traditional getter or setter for the DoWorkCommand property. Instead I’ve used a C# 7.0 expression bodied getter to lazy-load the command. You don’t need to do it this way, I just happen to like the conciseness of this syntax.
Listing 1. The Asynchronous DoWorkCommand
public class MainViewModel : ViewModelBase, IExceptionHandler
{
...
AsyncActionCommand doWorkCommand;
public ICommand DoWorkCommand => doWorkCommand
?? (doWorkCommand = new AsyncActionCommand(
DoWorkAsync, CanDoWorkAsync));
...
}
MainViewModel extends Codon’s ViewModelBase class. The Codon.UIModel.ViewModelBase class extends ObservableBase, which implements INotifyPropertyChanged (and INotifyPropertyChanging) via a PropertyChangeNotifier object.
The MainViewModel contains a boolean Busy property, which, as we shall see, is used to display a busy progress ring on a page. The property is defined in the view-model as shown:
bool busy;
public bool Busy
{
get => busy;
private set => Set(ref busy, value);
}
Before we look at the DoWorkCommands delegates, lets briefly examine Codon’s property setter infrastructure and at the way property change notification happens behind the scenes.
The ViewModelBase class’s Set method updates the field only if it has changed, and ensures that the update occurs on the UI thread so no cross-thread exceptions are thrown.
The Set method returns one of the following AssignmentResult enum values:
Success indicates that the field was not equal to the value being applied and that the field is now set to the specified value.
Cancelled may be returned if a subscriber to the view-model’s INotifyPropertyChanging method, marks the PropertyChangingEventArgs as Cancelled, which prevents the field value from being updated.
If AlreadyAssigned is returned, then the field is equal to the value being applied. Neither the PropertyChanging event nor the PropertyChanged event is raised in this case.
ViewModelBase extends ObservableBase, which makes use of a PropertyChangeNotifier object. The PropertyChangeNotifier class allows you to aggregate the INPC (INotifyPropertyChanged) behavior, and alleviates the need to inherit from a base class implementing INotifyPropertyChanged.
FUN FACT: You can use
PropertyChangeNotifierto enable INPC on any class.
If you’re interested in the inner workings of Codon’s INPC infrastructure please see the Codon.ComponentModel.ObservableBase class.
In this part of the post we look at the two method delegates passed to the AsyncActionCommand’s constructor. The first is a the command’s execution func DoWorkAsync, the second, CanDoWorkAsync, is a func that determines the Enabled state of the command and whether it can be executed.
The CanDoWorkAsync method relies on the busy flag, as shown in the following excerpt:
Task<bool> CanDoWorkAsync(object arg)
{
return Task.FromResult(!busy);
}
When the view-model’s Busy property is set to true, the CanDoWorkAsync method returns a Task<bool> equal to false, which sets the Enabled state of the command to false. There’s some magic that happens behind the scenes to make all this happen asynchronously. Please see the source of AsyncActionCommand if you’re interested.
Did you know? Codon commands also support parameter type coercion. Codon’s generic support means that if, for example, a command expects a
boolparameter, then a parameter specified in XAML astrueis automatically converted to abool. This mechanism is also extensible; you can add your own type coercion capabilities by creating a customIImplicitTypeConverterclass which you then add to the IoC container, like so:
Dependency.Register<IImplicitTypeConverter, MyImplicitTypeConverter>();
Let’s return to the command’s DoWorkAsync method.
The DoWorkAsync method is called when the DoWorkCommand is executed. See Lising 2. This method is marked async, which means we can await other async methods within its body.
It begins by setting a Busy flag to true. It then signals to the doWorkCommand that it should re-evaluate its Enabled property. Because busy is true at that point, the command’s Enabled property is set to false.
NOTE: In contrast to traditional synchronous
ICommandimplementations,RaiseCanExecuteChangedmay occur asynchronously, and so theEnabledstate may not have necessarily changed after the call to itsRaiseCanExecuteChangedmethod. To wait for the command to update itsEnabledproperty, await itsRefreshAsyncmethod.
You’ll notice that there is a if (raiseException) block within the method. We explore its purpose in a moment.
We use a Task.Delay call to prevent the method from completing for a few seconds, after which we use Codon’s IDialogService to display an Activity Complete message to the user.
The finally block sets the Busy flag to false and once again calls the command’s RaiseCanExecuteChanged method, which updates the command’s Enabled property to true.
Listing 2. DoWorkAsync Method
async Task DoWorkAsync(object arg)
{
try
{
Busy = true;
doWorkCommand.RaiseCanExecuteChanged();
if (raiseException)
{
throw new Exception(
"This exception is handled by the ShouldRethrowException method.");
}
/* Wait for a few seconds before completion. */
await Task.Delay(5000);
await Dependency.Resolve<IDialogService>().ShowMessageAsync(
"The command has finished processing asynchronously.", "Activity Complete");
}
finally
{
Busy = false;
doWorkCommand.RaiseCanExecuteChanged();
}
}
So, what’s with the if (raiseException) block? The view-model contains a RaiseException property that when set to true causes an exception to be thrown when the command executes. The purpose of this is to demonstrate the commanding infrastructure’s global exception handling.
Exceptions thrown from a non-UI thread are notoriously difficult to handle properly. Especially if your code is running on different platforms. Codon attempts to alleviate that fact by providing a exception handling extensibility point. This is true for the commanding infrastructure, the decoupled messaging system, and the application settings system.
For example, to be notified of, and have the opportunity to handle, exception that are thrown during command execution, we can register a custom IExceptionHandler with the IoC container. We can do this globally, using a service that is separate from any particular view-model (an approach I favor), or we can take the easy road and implement IExceptionHandler in a view-model and register that view-model with the IoC container, as I did in this example. See Listing 3.
Listing 3. Registering an IExceptionHandler
public class MainViewModel : ViewModelBase, IExceptionHandler
{
public MainViewModel()
{
/* If an exception occurs during the execution of a command,
* the ShouldRethrowException method is called. */
Dependency.Register<IExceptionHandler>(this);
}
}
When an exception is thrown during the executeAsync or the canExecuteAsync funcs, then the IExceptionHandler implementation has the opportunity to handle (disregard/log etc.) the exception. See Listing 4.
The MainViewModel’s ShouldRethrowException method displays the exception in a dialog using the IDialogService. It could just as easily log the exception using Codon’s ILog and evaluate some rules to determine if the exception should be rethrown or not; as indicated by the return value. If the method returns true, the commanding infrastructure re-throws the exception.
Now, if you’re as old as I am, you may be thinking: Oh, this reminds me of that awfully complicated Exception Handling Application Block of the Enterprise Library from Patterns and Practices. And yes, it is a little bit like that. But, its real purpose, rather than being a way of applying policies to application errors, is to give your app the opportunity to handle exceptions raised by first or third-party components that might occur on a different thread and crash your app. When using Xamarin Android, for example, there isn’t a way to globally handle exceptions.
Listing 4. MainViewModel ShouldRethrowException Method
bool IExceptionHandler.ShouldRethrowException(Exception exception, object owner,
[CallerMemberName]string memberName = null,
[CallerFilePath]string filePath = null,
[CallerLineNumber]int lineNumber = 0)
{
Dependency.Resolve<IDialogService>().ShowMessageAsync(
"Exception thrown: " + exception.Message);
return false;
}
Let’s now explore how the view-model is wired-up to the view. The MainPage class of the app sports a ViewModel property of type MainViewModel. See Listing 5.
We expose the MainViewModel as a property to allow the use of x:Bind binding expressions in XAML. The page’s DataContext property is also set to the MainViewModel for good measure. I find it useful to do this for cases where I need the flexibility of old style Binding expressions.
Listing 5. MainPage.xaml.cs
public sealed partial class MainPage : Page
{
public MainPage()
{
this.InitializeComponent();
DataContext = Dependency.Resolve<MainViewModel>();
}
public MainViewModel ViewModel => (MainViewModel)DataContext;
}
The MainPage.xaml file is bound to the view-model’s DoWorkCommand. See Listing 6.
The ProgressRing and the StackPanel both share row 0 of the parent Grid. The ProgressRing sits on top of the other elements.
Listing 6. MainPage.xaml Excerpt
<Page x:Class="AsyncCommandsExample.MainPage"
...>
<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
<StackPanel>
<Button Command="{x:Bind ViewModel.DoWorkCommand}"
Content="Show Dialog with Timer" />
<ToggleSwitch IsOn="{x:Bind ViewModel.RaiseException, Mode=TwoWay}"
Header="Raise Exception during Command Execution" />
</StackPanel>
<ProgressRing IsActive="{x:Bind ViewModel.Busy, Mode=OneWay}" />
</Grid>
</Page>
A ProgressRing control is shown when the view-model’s Busy property is set to true, which occurs for 5 seconds when the button is clicked. See Figure 1.
When the DoWorkCommand completes a dialog is presented and the busy state is restored to false. See Figure 2.
A ToggleSwitch is bound to the view-model’s RaiseException property. When IsOn is set to true,
and the button is clicked, an exception is raised in the DoWorkAsync method of the view-model. See Figure 3.
In this post you’ve seen how Codon comes with rich commanding infrastructure. As you’d expect there is a basic ICommand implementation: ActionCommand, that allows you to supply delegates that are called during command execution or when evaluating the command’s Enabled property. There is also a UICommand class that, in addition to the features of the ActionCommand class, provides text, icon, and visibility support. However, in Codon’s Extras package there exists a number asynchronous commands, which are analogous to those in the core library, and offer async support. AsyncActionCommand brings in asynchronous method support, yet also implements the ICommand interface seamlessly, making it compatible with the built-in commanding infrastructure of UWP, WPF, Xamarin Forms, and Codon’s Xamarin Android binding system.
You saw how to create a view-model with an asynchronous command that kicks of a potentially long running operation. You also explored how to globally handle exceptions that occur during the execution of an asynchronous operation.
Download or View the Sample Code on GitHub
I hope you find this post useful. Have a great day!
]]>Codon FX is a cross-platform framework for building maintainable applications. I use it for all of my .NET based applications.
Codon is built on .NET Standard and uses platform specific assemblies to support various platforms including UWP. Codon has no references to third-party libraries, keeping it light-weight and free from version conflicts. There is, however, nothing preventing you from enriching Codon with your own custom services tailored for a particular platform.
There are various services that can be easily swapped out using Codon’s IoC infrastructure. One such service is Codon’s dialog service (Codon.Services.IDialogService), which is used to display various dialogs to the user, or to ask the user a question, or to display toast notifications. Currently, there’s an implementation of IDialogService for UWP, WPF, and Xamarin Android/iOS/Forms.
There are several Codon services that I find indispensable when building apps. IDialogService is one of these. Being able to quickly ask the user a question or display a message is such a common use case. I couldn’t bear not having a cross-platform dialog service at my fingertips; having to rely on building a platform specific dialog for each interaction would slow down development considerably.
The UWP implementation of the IDialogService, however, relies on the UWP toast API, which places toast notifications adjacent to the Windows Status bar. This isn’t optimal considering that the notification is not front and center while your app is in the foreground, and displaying toasts down in the status area while your app is in the foreground is generally frowned upon.
We can improve the way toasts are displayed for UWP apps by creating a custom IDialogService, inheriting from the UWP DialogService, and overriding its toast related methods. In this article you see how to achieve that, along with leveraging the UWP Community Toolkit’s InAppNotification API to display in-app notifications.
All of Codon’s services and many of its other components are designed to be replaceable. If you don’t like the way something works, or you want to provide enhancements to a component, there’s nothing stopping you from swapping it out with your own implementation. For example, want to change how logging is performed? Substitute in your own ILog implementation. All of Codon’s logging will utilize your ILog implementation.
To create a custom UWP IDialogService implementation, begin by using the NuGet package manager to reference the package Codon.Uwp. This package brings in Codon’s .NET Standard core library and a UWP platform specific library.
While you’re at it, use the NuGet package manager to reference the UWP Community Toolkit package named Microsoft.Toolkit.Uwp.UI.Controls.
Once you’ve referenced Codon, you can take the default IDialogService implementation for a spin by using the following:
bool userHitOkay = await Dependency.Resolve<IDialogService>()
.AskOkayCancelQuestionAsync("Would you like to continue?");
Here we resolve the IDialogService from the IoC container using the static Dependency.Resolve method.
The IDialogService implementation has an awaitable AskOkayCancelQuestion method that returns true
if the user clicks/taps okay; false otherwise. There are a bunch of other useful methods that I use a lot
when I’m building apps. The most frequently used is the good ol’ ShowMessageAsync method. Though, I especially like the AskQuestionAsync method, that lets you pass in a question object. For example, here’s one I use in Surfy Browser for Windows Mobile and Android:
var question = new TextQuestion(string.Empty)
{
DefaultResponse = string.Empty,
Caption = AppResources.AppBar_MenuItem_FindOnPage,
InputScope = InputScopeNameValue.Text
};
var questionResponse = await DialogService.AskQuestionAsync(question);
Here I create a TextQuestion object that defines a caption to display on a dialog (“Find on Page”), a default value to place in the text box, and even an input scope value, which determines the soft input panel keyboard. Figure 1. shows the dialog displayed within Surfy Browser on Android.
Let’s turn our attention back at the task at hand: changing the toast notification behavior of the IDialogService implementation.
The UWP Community Toolkit contains an in-app notification component. You use it by placing an instance of Windows.UI.Xaml.Controls.ContentControl.InAppNotification on your page or control, as shown in Listing 1.
Listing 1. Using the InAppNotification on a Page
<Page
x:Class="Outcoder.Foo.MainPage"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
xmlns:controls="using:Microsoft.Toolkit.Uwp.UI.Controls"
mc:Ignorable="d">
...
<controls:InAppNotification x:Name="InAppNotification" />
...
</Page>
While I’m not so keen on the approach that InAppNotification takes, in that I’d prefer to see the control live independently from the page, placed dynamically in the visual tree, for this example I’m going to live with it.
With the InAppNotification element on the page you can then call the InAppNotification’s Show method; passing in the text to display and the duration before it is hidden again.
What we are going to do is pass the InAppNotification object to a custom IDialogService.
The next step is to subclass Codon’s UWP DialogService. See Listing 2.
We override the ShowToastAsync method of the base DialogService class. Our new CustomDialogService depends on an instance of the InAppNotification class. Without it, it can’t display notifications and the CustomDialogService falls back to the default behavior.
Listing 2. CustomDialogService Class
public class CustomDialogService : DialogService
{
public InAppNotification InAppNotification { get; set; }
public uint ToastHideMS { get; set; } = 3000;
public override Task<object> ShowToastAsync(ToastParameters toastParameters)
{
if (InAppNotification != null)
{
int hiddenMS = 0;
if (toastParameters.MillisecondsUntilHidden.HasValue)
{
hiddenMS = toastParameters.MillisecondsUntilHidden.Value;
}
InAppNotification.Show(toastParameters.Caption?.ToString(),
hiddenMS > 0 ? hiddenMS : (int)ToastHideMS);
return Task.FromResult(new object());
}
return base.ShowToastAsync(toastParameters);
}
}
The CustomDialogService InAppNotification property is populated in the MainPage’s code-beside file. See Listing 3.
Listing 3. MainPage Excerpt
public sealed partial class MainPage : Page
{
public MainPage()
{
this.InitializeComponent();
DataContext = ViewModel = Dependency.Resolve<MainViewModel, MainViewModel>(true);
Loaded += HandleLoaded;
var dialogService = (CustomDialogService)Dependency.Resolve<IDialogService>();
dialogService.InAppNotification = InAppNotification;
}
...
}
NOTE: If you’re concerned about testability because we are tying the
InAppNotificationcomponent to theIDialogServiceimplementation, set your mind at ease. There exists aCodon.DialogModel.MockDialogServiceclass within the Codon’s core library, specifically designed for testing purposes. You can register it with the IoC container, instead of yourCustomDialogServicewhen your unit-test project is launching, as demonstrated:
Dependency.Register<IDialogService>(new MockDialogService());
Likewise, to register your CustomDialogService for non-unit-testing configurations, place the following somewhere in your app’s startup code:
Dependency.Register<IDialogService>(new CustomDialogService());
Passing an instance of the CustomDialogService class to the Register method causes a singleton mapping to be created; that instance will be returned from all requests to Resolve<IDialogService>.
NOTE: If you have multiple pages or views, you’ll need to assign the
InAppNotificationobject to theCustomDialogServicewhen the view becomes visible. I’m not happy with that approach. As I mentioned above, I’d like to see theInAppNotificationcomponent placed dynamically in the visual tree so it is not dependent on being explicitly defined for each page or control.
In this post you’ve seen how to supplant Codon’s IDialogService implementation, with a custom implementation that leverages the UWP Community Toolkit’s InAppNotification component, to display in-app toast messages. You also saw how Codon’s services and components can be replaced to provide new capabilities. Codon is a zero-dependency framework. There are no references to third party libraries, keeping it light-weight and free from version conflicts. There is, however, nothing preventing you from enriching Codon with your own custom services tailored for a particular platform.
You can download the source code for this article from the Codon Samples repository on GitHub.
I hope you find this post useful. Have a great day!
]]>