USAGE: qdyn_optimize [OPTIONS] RUNFOLDER
This program is part of QDYN.
Look for CONFIGFILE inside RUNFOLDER (or file "config" if no CONFIGFILE
is given). Initialize a system (dynamical generator, pulses, grid) from
the CONFIGFILE (using the default, empty label). Construct a set of
optimization targets based on the command line option, and further
information in CONFIGFILE, and optimize all pulses towards these
targets.
OPTIONS
-h, --help Print this help message and exit.
-v, --version Print version information and exit
--config=CONFIGFILE Name of the config file inside RUNFOLDER. Defaults
to "config"
--debug Write para.debug, grid.debug, gen.debug,
and targets.debug, containing ASCII dumps of the
config file data, the spatial grid, the (first)
dynamical generator, and the optimization targets.
The files are written in the RUNFOLDER.
--internal-units=UNITS_FILE
Specify a file containing conversion factors
between internal units and physical units. See
"Notes on the Units Systems" in the QDYN
documentation for details. The file must be located
in the current working directory, in the directory
specified by the QDYN_UNITS environment variable,
or the QDYN installation directory.
--J_T=J_T_NAME Name of the optimization functional to be used.
Possible values are "J_T_re" (default,
phase-sensitive), "J_T_sm" (up to global phase),
"J_T_ss" (phase-insensitive), "J_T_LI" (local
invariants), and "J_T_PE" (perfect entangler)
--initial-states=INITIAL_LABELS
If doing a state-to-state optimization, a
comma-separated list of labels for states in
the config file. That is, a `psi` section with
`label=<label>` must exist for every label in the
list. This option must be given together with the
--target-states option
--target-states=TARGET_LABELS
If doing a state-to-state optimization, a
comma-separated list of labels for the target
states of the optimization. The number of labels
must match those given by the --initial-states
option
--basis=BASIS_LABELS
If doing the optimization of a unitary gate, a
comma-separated list of labels for states in the
config file that define the canonical basis on
which the gate should be applied. This option must
be given together with the --gate option, unless
the perfect-entanglers functional is used
(`--J_T=J_T_PE`)
--gate=GATE_FILE If doing the optimization of a unitary gate, name
of the file from which the desired gate can be
read. The file must contain two columns (real and
imaginary part) and given the vectorized gate
matrix in column-major mode. This must be given
together with --basis unless `--J_T=J_T_PE` is used
--rwa-vector=RWA_VECTORFILE
If the Hamiltonian and the pulses are set up in a
rotating frame, but the targets (e.g. the desired
quantum gate) are defined in the lab frame, the
optimization needs to take this into account. The
--rwa-vector option specifies a file containing
a vector (the diagonal entries of the RWA
transformation matrix) that defines the conversion
between the rotating frame and the lab frame
--rho Perform the optimization in Liouville space. For a
state-to-state optimization, the initial and target
states are the pure-state density matrices of
the original wave functions. For a gate
optimization, a special set of density matrices is
constructed as the initial states, according to
the --lv-states-set setting.
--lv-states-set=SET Identifier of which states should be propagated to
support the optimization of a unitary gate in
Liouville space. Values for SET are "3states"
(default), "full", "d+1", and "2d"
--w-unitary=UNITARITY_WEIGHT
If using a local-invariants-based functional
(--J_T=J_T_LI, --J_T=J_T_PE) for a system in which
the logical subspace is embedded in a larger
Hilbert space, 0 <= UNITARITY_WEIGHT < 1 is a
weight for an additional term in the functional
that minimized loss from the logical subspace.
--target-weights=WEIGHTS
By default, all targets are weighted equally.
Alternatively, WEIGHTS can be a comma-separated
list of (relative) weights between the targets. A
weight must be given for each target (i.e., the
dimension of the gate for a gate dimension, or the
number of initial states in a state-to-state
optimization). Weighting the targets should
generally only be used in conjunction with
--lv-states-set
--n-trajs=N Number of MCWF trajectories to propagate. This
increases the number of targets by a factor of N
--seed=SEED Seed for the random number generator if using MCWF
trajectories
--write-final-state=STATESFILE
Write the final states, propagated with the
optimized pulse, to STATESFILE (in indexed format),
as STATESFILE.<N>, where <N> is the target index.
For a state-to-state propagation, this is the
result of propagating the respective initial
states, for a gate optimization, it is the result
of propagating the basis states (the Bell basis
if using an optimization functional based on local
invariants). The written states are always in the
lab frame.
--write-optimized-gate=OPT_GATE_FILE
If doing a gate optimization (--gate option), the
gate implemented under the dynamics of the
optimized pulses. The gate is always given in the
lab frame and in the canonical basis (i.e., not the
Bell basis even if using a local-invariants-based
functional. If using ensemble optimization or MCWF
trajectories, only the gate from the "main"
Hamiltonian / the first trajectory realization is
written.
--ensemble-gens=ENSEMBLE_GEN_LABELS
Comma-separated list of config file labels for
*additional* dynamic generators (usually
Hamiltonians). The optimization will be performed
for an ensemble that consists of the original
dynamic generator (empty label), plus a dynamic
generator initialized for each label in
ENSEMBLE_GEN_LABELS. The ensemble Hamiltonians must
reference the same pulses as the original
Hamiltonian. The total number of targets increases
by the factor of the total number of ensemble
Hamiltonians
NOTES
Optimization can be for (multiple) state-to-state transitions, or a
unitary gate.
For the former, --initial-states and --target-states must be specified.
If the optimization is done in Hilbert-space, --J_T=J_T_ss is an
appropriate choice of functional (relative phase between all targets is
ignored), but J_T_re or J_T_sm may also be appropriate if the relative
of global phase is important. For dissipative dynamics (--rho option),
the transition between the corresponding pure-state density matrices is
optimized. In this case --J_T=J_T_re should be used (it is equivalent
to J_T_sm, but numerically more stable.
For gate optimization, the optimization is characterized by specifying
the logical basis states must be specified (--basis) and the unitary
gate with respect to that basis (--gate). For unitary dynamics, The
functional should be "--J_T=J_T_sm", or "J_T_re" if the global phase is
important. Alternatively, "--J_T=J_T_LI" optimizes towards the local
invariants of the specified gates. Optimization towards a general
perfect entangler ("--J_T=J_T_PE") is a special case, in which the
--gate should not be given. If the dynamics are dissipative (--rho),
the number of targets and the state that is propagated in each target
depends on the value of the --lv-states-set option. For the default,
"--lv-states-set=3states", the optimization is expressed through three
targets (independent of the dimension of the gate). The values "full",
"d+1", and "2d" propagate d^2, d+1, and 2d states respectively, where d
is the dimension of the gate. See [New J. Phys. 16, 055012 (2014)] for
details. Using more states may lead to faster convergence. It can be
useful to use the --target-weights option to give different weights to
the individual states, according to their physical interpretation.
Specifically, by specifying a zero weight, a target may be dropped from
the optimization (e.g., the first state for in "--lv-states-set=3states"
if the Hamiltonian only allows for diagonal gates). It is strongly
recommended to use the "--J_T=J_T_PE" functional when optimizing for a
unitary gate in Liouville space.
There are two ways in which multiple "copies" of the system defined
as either a state-to-state or gate optimization may be optimized
simultaneously. The first is an ensemble optimization, where the same
system is optimized under a set of different Hamiltonians (with small
variations). This is set up using the --ensemble-gens option. This works
equally for dissipative and non-dissipative dynamics. Secondly, we may
optimize over multiple MCWF (quantum jump trajectories). In this case,
the optimization runs over several identical copies of the normal
targets, but in each copy, the dynamics are independently randomized
to account for quantum noise. Note that in this case, the dynamics are
modeled in Hilbert space (i.e., the --rho option must not be given). The
dissipators and use of MCWF propagation is set up in the CONFIGFILE. For
reproducibility, the random number generator my be initialized via
--seed. In principle (to the extent that is is numerically feasible,
both ensemble optimization and MCWF trajectories can be combined.
Most options may also be set in the config file as use-defined values.
The corresponding keyname replaces dashes with underscores. That is,
instead of specifying "--lv-states-set=3states" as a command line
option, the value "lv_states_set = 3states" may be added to the
"user_strings" section of the CONFIGFILE. Any filenames in this case
ase are relative to the CONFIGFILE, not the current working directory.