The QDK Python layer should have knowledge of its initialization state

[wavefunction91]

Is your feature request related to a problem? Please describe.

As the qsharp state is global and persistent, but must be initialized

from qdk import init as qdk_init
qdk_init(...)

Reinitialization effects the global state. For downstream applications and libraries which use QDK, this can be dangerous, as initializing the qdk in user code, and again in another library, could lead to unexpected behaviour.

Describe the solution you'd like

Some notion of whether QDK has been initialized, e.g. a global variable (as is canonical in many libraries that have stateful initialization):

from qdk import QDK_IS_INITIALIZED
from qdk import init as qdk_init
if NOT QDK_IS_INITIALIZED:
  qdk_init(...)

Describe alternatives you've considered

There is a workaround currently by checking the qdk profile

from qdk import init as qdk_init
from qsharp._qsharp import get_config as get_qdk_profile_config
qdk_config = get_qdk_profile_config()
_QDK_INTERPRETER_PROFILE = qdk_config.get_target_profile()
if _QDK_INTERPRETER_PROFILE == "unrestricted":  # Default by Q# if not set
    qdk_init(target_profile=TargetProfile.Base)

but I think we can all agree that is not great UX.

[minestarks]

IMO, this issue hints at a design problem that's been plaguing us for a little while - almost all the QDK APIs use a global state. While this is a good convenience for a user writing in, say, a Jupyter notebook, it makes library/utility code very challenging to write.

I think we're due for a holistic solution here. Here's my proposal (language is obviously Copilot, ideas are mine). Thoughts? @wavefunction91 @swernli @orpuente-MS @idavis

Root Cause

The underlying problem is architectural: the qsharp package stores a single global
_interpreter and _config. Every function — eval(), run(), compile(), etc. —
operates on this shared state via get_interpreter(). There is no mechanism for
multiple independent interpreter sessions to coexist.

This creates two classes of problems:

1. Initialization conflicts: Two libraries that both call init() silently clobber
   each other's configuration (target profile, project root, language features, etc.).

2. Stale callable hazards: After init() is called, callables registered from prior
   Q# compilations become silently invalid — they reference state from the old
   interpreter that no longer exists.

Our Solution: The QdkContext Class

Rather than adding an is_initialized() flag (which only detects the conflict), we
introduce a QdkContext class that lets callers avoid the conflict entirely by
creating isolated interpreter contexts.

What It Looks Like

Existing code is unchanged. Module-level functions work exactly as before:

import qsharp

qsharp.init(target_profile=qsharp.TargetProfile.Base)
qsharp.eval("Message('hello')")
results = qsharp.run("MyProgram()", shots=100)

Library code can now create isolated contexts that never touch global state:

import qsharp

# Each context has its own interpreter, configuration, and compiled code
ctx = qsharp.new_context(target_profile=qsharp.TargetProfile.Base)
ctx.eval("operation MyOp() : Result { use q = Qubit(); H(q); M(q) }")
results = ctx.run("MyOp()", shots=100)
estimate = ctx.estimate("MyOp()")

Two contexts are fully isolated — definitions in one don't leak into the other:

ctx1 = qsharp.new_context()
ctx2 = qsharp.new_context()

ctx1.eval("function Greet() : String { \"hello\" }")
ctx1.eval("Greet()")   # returns "hello"
ctx2.eval("Greet()")   # raises QSharpError — Greet is not defined in ctx2

Callables stay bound to their context, even when passed around:

ctx = qsharp.new_context(target_profile=qsharp.TargetProfile.Base)
ctx.eval("operation MyOp() : Result { use q = Qubit(); M(q) }")

my_op = ctx.code.MyOp
qir = ctx.compile(my_op)  # uses ctx's interpreter, not the global one

init() returns the global context, so callers can use it either way:

ctx = qsharp.init(target_profile=qsharp.TargetProfile.Base)

# These two are equivalent:
ctx.eval("1 + 1")
qsharp.eval("1 + 1")

get_context() returns the global context without reinitializing — useful when
library code needs to operate in the user's context without calling init():

ctx = qsharp.get_context()   # returns the existing global context (or lazily creates one)

context_of() retrieves the context that owns a callable — essential for library
code that receives a callable from the user and needs to operate on it correctly:

def estimate_user_op(op, noise_params):
    ctx = qsharp.context_of(op)       # get the context that compiled this callable
    return ctx.estimate(op, params={"qubitParams": noise_params})

Cross-context misuse is caught immediately — passing a callable to a different
context's method raises QSharpError with a clear message:

ctx_a = qsharp.new_context()
ctx_a.eval("operation Foo() : Unit {}")

ctx_b = qsharp.new_context()
ctx_b.compile(ctx_a.code.Foo)
# → QSharpError: "This callable belongs to a different QdkContext."

OpenQASM imports work on contexts too:

ctx = qsharp.new_context()
ctx.import_openqasm("""
    OPENQASM 3.0;
    include "stdgates.inc";
    qubit q;
    h q;
""")

How This Addresses the Issue

The issue asks three questions: (1) "How do I know if QDK is already initialized?"
(2) "How do I avoid clobbering someone else's initialization?" and (3) "The workaround
is not great UX."

With this change, question 1 becomes mostly irrelevant — get_context() gives library
code access to the existing global context without reinitializing, and init() now
returns a QdkContext whose .config property exposes the configuration cleanly.
Question 2 is solved directly: new_context() creates an isolated interpreter that
cannot interfere with anyone else's state. And question 3 is addressed by replacing the
multi-line internal-import workaround with a single public API call:

# Before (fragile workaround from the issue):
from qsharp._qsharp import get_config as get_qdk_profile_config
qdk_config = get_qdk_profile_config()
if qdk_config.get_target_profile() == "unrestricted":
    qdk_init(target_profile=TargetProfile.Base)

# After:
ctx = qsharp.new_context(target_profile=qsharp.TargetProfile.Base)

Best Practices for Library Authors

End users — someone writing a script or Jupyter notebook — can ignore contexts entirely.
The global context and module-level functions (qsharp.eval(), qsharp.run(), etc.)
work the same as always. %%qsharp cells evaluate in the global context and callables
appear in qsharp.code.*.

Library authors need to be more deliberate. The fundamental rule is:

Every QDK callable is bound to the context that created it.
Never use a callable with a different context.

A callable captures a reference to the interpreter that compiled it. Passing it to a
method on a different context raises QSharpError. This is enforced at runtime on
run(), compile(), circuit(), estimate(), and logical_counts().

Pattern 1 — Self-contained library (own Q# code, no user objects)

Create a private context. Never touch the global state.

# chemistry_lib/__init__.py
import qsharp

_ctx = qsharp.new_context(target_profile=qsharp.TargetProfile.Base)
_ctx.eval("operation SimulateMolecule(encoding : Int) : Double { ... }")

def simulate(molecule, shots=1000):
    return _ctx.run(f"SimulateMolecule({molecule.encoding})", shots=shots)

Pattern 2 — Function that takes a user's callable

Use context_of() to operate in the callable's own context.

def estimate_with_noise(op, noise_params):
    ctx = qsharp.context_of(op)
    return ctx.estimate(op, params={"qubitParams": noise_params})

Pattern 3 — Function that returns a callable to the user

Accept a ctx parameter defaulting to the global context via get_context().

def build_ansatz(params, ctx=None):
    ctx = ctx or qsharp.get_context()
    ctx.eval(f"operation Ansatz() : Result {{ use q = Qubit(); Ry({params.theta}, q); M(q) }}")
    return ctx.code.Ansatz

Pattern 4 — Function that transforms a callable

Everything happens in the input callable's context.

def add_error_correction(op):
    ctx = qsharp.context_of(op)
    ctx.eval("operation WithEC(op : () => Result) : Result { ... }")
    return ctx.code.WithEC

Anti-patterns

Don't do this	Why	Do this instead
Call qsharp.init() in library code	Destroys the user's global state	Use qsharp.new_context()
Use module-level qsharp.eval() etc. in library code	Mutates the user's global context	Use your own context's methods
Pass callables between different contexts	Callable is bound to its origin context	Use context_of() to stay in the right context
Store a context at import time	User might call init() later	Get the context when you need it

Backward Compatibility

These changes are fully backward compatible:

• All existing module-level functions (qsharp.eval(), qsharp.run(), etc.) work
  identically — they delegate to the global default context
• init() still works as before; its return type changes from Config to QdkContext,
  but QdkContext exposes .config and delegates __repr__ / _repr_mimebundle_
• Callables from the default context registered in qsharp.code.* still work
• After init(), old callables still raise QSharpError (preserved via _disposed)

Risks and Limitations

1. Memory: Each QdkContext holds its own Interpreter (which includes a
   simulator). Creating many contexts concurrently uses proportionally more memory.
   This is inherent to isolation and matches user expectations.

2. Thread safety: The architecture doesn't introduce new thread-safety concerns, but
   the Rust Interpreter is not inherently thread-safe. Using a single context from
   multiple threads concurrently is not supported (same as before).

3. init() return type: Code that relied on init() returning a Config object
   needs to use .config on the returned QdkContext. This is a minor breaking change,
   but the QdkContext proxies __repr__ and _repr_mimebundle_ from its config, so
   Jupyter notebook display is unchanged.