diff --git a/previews/PR49/.documenter-siteinfo.json b/previews/PR49/.documenter-siteinfo.json index 820cff0..4476c89 100644 --- a/previews/PR49/.documenter-siteinfo.json +++ b/previews/PR49/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-17T15:48:22","documenter_version":"1.1.1"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.3","generation_timestamp":"2023-10-17T16:01:32","documenter_version":"1.1.1"}} \ No newline at end of file diff --git a/previews/PR49/gallery/index.html b/previews/PR49/gallery/index.html index 092179e..9864ecb 100644 --- a/previews/PR49/gallery/index.html +++ b/previews/PR49/gallery/index.html @@ -1,5 +1,5 @@ -Citation Style Gallery · DocumenterCitations.jl
GitHub

Citation Style Gallery

The citation style is determined when instantiating the CitationBibliography, via the style argument.

The built-in styles are:

Numeric style

This is the default style (style=:numeric) used throughout the other pages of this documentation, cf. the Syntax examples.

References:

[1]
C. Brif, R. Chakrabarti and H. Rabitz. Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008 (2010).
[2]
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).
[4]
P. Brumer and M. Shapiro. Principles and Applications of the Quantum Control of Molecular Processes. Wiley Interscience (2003).
[5]
M. Shapiro and P. Brumer. Quantum Control of Molecular Processes. Wiley and Sons (2012).
[6]
C. P. Koch. Controlling open quantum systems: tools, achievements, and limitations. J. Phys.: Condens. Matter 28, 213001 (2016).
[7]
G. von Winckel and A. Borzì. Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007 (2008).
[14]
H. A. Fürst, M. H. Goerz, U. G. Poschinger, M. Murphy, S. Montangero, T. Calarco, F. Schmidt-Kaler, K. Singer and C. P. Koch. Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007 (2014). Special issue on coherent control of complex quantum systems.

Author-year style

The author-year style (style=:authoryear) formats citations with the author name and publication year. This is the citation style used, e.g., in Rev. Mod. Phys. (rmp option in REVTeX). The bibliography is sorted alphabetically by author name. The default @cite command is parenthetical (@cite and @citep are equivalent) which is different from the authoryear style in natbib.

References:

  • Brif, C.; Chakrabarti, R. and Rabitz, H. (2010). Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008.
  • Brumer, P. and Shapiro, M. (2003). Principles and Applications of the Quantum Control of Molecular Processes. Wiley Interscience.
  • Fürst, H. A.; Goerz, M. H.; Poschinger, U. G.; Murphy, M.; Montangero, S.; Calarco, T.; Schmidt-Kaler, F.; Singer, K. and Koch, C. P. (2014). Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007. Special issue on coherent control of complex quantum systems.
  • Goerz, M. H.; Carrasco, S. C. and Malinovsky, V. S. (2022). Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871.
  • Koch, C. P. (2016). Controlling open quantum systems: tools, achievements, and limitations. J. Phys.: Condens. Matter 28, 213001.
  • Shapiro, M. and Brumer, P. (2012). Quantum Control of Molecular Processes. Wiley and Sons.
  • von Winckel, G. and Borzì, A. (2008). Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007.

Alphabetic style

The style=:alpha formats citations and references like :numeric, except that it uses labels derived from the author names and publication year and sorts the references alphabetically.

References:

[BCR10]
C. Brif, R. Chakrabarti and H. Rabitz. Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008 (2010).
[BS03]
P. Brumer and M. Shapiro. Principles and Applications of the Quantum Control of Molecular Processes. Wiley Interscience (2003).
[FGP+14]
H. A. Fürst, M. H. Goerz, U. G. Poschinger, M. Murphy, S. Montangero, T. Calarco, F. Schmidt-Kaler, K. Singer and C. P. Koch. Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007 (2014). Special issue on coherent control of complex quantum systems.
[GCM22]
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).
[Koc16]
C. P. Koch. Controlling open quantum systems: tools, achievements, and limitations. J. Phys.: Condens. Matter 28, 213001 (2016).
[SB12]
M. Shapiro and P. Brumer. Quantum Control of Molecular Processes. Wiley and Sons (2012).
[vWB08]
G. von Winckel and A. Borzì. Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007 (2008).

Note that the :alpha style is able to automatically disambiguate labels:

[GBR+07a]
M. Grace, C. Brif, H. Rabitz, I. A. Walmsley, R. L. Kosut and D. A. Lidar. Optimal control of quantum gates and suppression of decoherence in a system of interacting two-level particles. J. Phys. B 40, S103 (2007), arXiv:quant-ph/0702147.
[GBR+07b]
M. D. Grace, C. Brif, H. Rabitz, D. A. Lidar, I. A. Walmsley and R. L. Kosut. Fidelity of optimally controlled quantum gates with randomly coupled multiparticle environments. J. Mod. Opt. 54, 2339 (2007), arXiv:0712.2935.

This works because the DocumenterCitations plugin automatically upgrades style=:alpha to the internal

DocumenterCitations.AlphaStyle — Type

"Smart" alphabetic citation style (relative to the "dumb" :alpha).

style = AlphaStyle()

instantiates a style for CitationBibliography that avoids duplicate labels. Any of the entries that would result in the same label will be disambiguated by appending the suffix "a", "b", etc.

Any bibliography that cites a subset of the given entries is guaranteed to have unique labels.

source

Custom styles

In the following, we show two examples for user-defined styles. See the notes on customization on how to generally define a custom style.

Custom style: enumerated author-year

In this example, the :authoryear style is used, but the references are shown in an enumerated list.

import DocumenterCitations
+Citation Style Gallery · DocumenterCitations.jl
GitHub
Citation Style Gallery
The citation style is determined when instantiating the CitationBibliography, via the style argument.
The built-in styles are:
Numeric style
This is the default style (style=:numeric) used throughout the other pages of this documentation, cf. the Syntax examples.
References:
[1]
C. Brif, R. Chakrabarti and H. Rabitz. Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008 (2010).
[2]
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).
[4]
P. Brumer and M. Shapiro. Principles and Applications of the Quantum Control of Molecular Processes. Wiley Interscience (2003).
[5]
M. Shapiro and P. Brumer. Quantum Control of Molecular Processes. Wiley and Sons (2012).
[6]
C. P. Koch. Controlling open quantum systems: tools, achievements, and limitations. J. Phys.: Condens. Matter 28, 213001 (2016).
[7]
G. von Winckel and A. Borzì. Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007 (2008).
[14]
H. A. Fürst, M. H. Goerz, U. G. Poschinger, M. Murphy, S. Montangero, T. Calarco, F. Schmidt-Kaler, K. Singer and C. P. Koch. Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007 (2014). Special issue on coherent control of complex quantum systems.
Author-year style
The author-year style (style=:authoryear) formats citations with the author name and publication year. This is the citation style used, e.g., in Rev. Mod. Phys. (rmp option in REVTeX). The bibliography is sorted alphabetically by author name. The default @cite command is parenthetical (@cite and @citep are equivalent) which is different from the authoryear style in natbib.
References:
  • Brif, C.; Chakrabarti, R. and Rabitz, H. (2010). Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008.
  • Brumer, P. and Shapiro, M. (2003). Principles and Applications of the Quantum Control of Molecular Processes. Wiley Interscience.
  • Fürst, H. A.; Goerz, M. H.; Poschinger, U. G.; Murphy, M.; Montangero, S.; Calarco, T.; Schmidt-Kaler, F.; Singer, K. and Koch, C. P. (2014). Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007. Special issue on coherent control of complex quantum systems.
  • Goerz, M. H.; Carrasco, S. C. and Malinovsky, V. S. (2022). Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871.
  • Koch, C. P. (2016). Controlling open quantum systems: tools, achievements, and limitations. J. Phys.: Condens. Matter 28, 213001.
  • Shapiro, M. and Brumer, P. (2012). Quantum Control of Molecular Processes. Wiley and Sons.
  • von Winckel, G. and Borzì, A. (2008). Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007.
Alphabetic style
The style=:alpha formats citations and references like :numeric, except that it uses labels derived from the author names and publication year and sorts the references alphabetically.
References:
[BCR10]
C. Brif, R. Chakrabarti and H. Rabitz. Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008 (2010).
[BS03]
P. Brumer and M. Shapiro. Principles and Applications of the Quantum Control of Molecular Processes. Wiley Interscience (2003).
[FGP+14]
H. A. Fürst, M. H. Goerz, U. G. Poschinger, M. Murphy, S. Montangero, T. Calarco, F. Schmidt-Kaler, K. Singer and C. P. Koch. Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007 (2014). Special issue on coherent control of complex quantum systems.
[GCM22]
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).
[Koc16]
C. P. Koch. Controlling open quantum systems: tools, achievements, and limitations. J. Phys.: Condens. Matter 28, 213001 (2016).
[SB12]
M. Shapiro and P. Brumer. Quantum Control of Molecular Processes. Wiley and Sons (2012).
[vWB08]
G. von Winckel and A. Borzì. Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007 (2008).
Note that the :alpha style is able to automatically disambiguate labels:
[GBR+07a]
M. Grace, C. Brif, H. Rabitz, I. A. Walmsley, R. L. Kosut and D. A. Lidar. Optimal control of quantum gates and suppression of decoherence in a system of interacting two-level particles. J. Phys. B 40, S103 (2007), arXiv:quant-ph/0702147.
[GBR+07b]
M. D. Grace, C. Brif, H. Rabitz, D. A. Lidar, I. A. Walmsley and R. L. Kosut. Fidelity of optimally controlled quantum gates with randomly coupled multiparticle environments. J. Mod. Opt. 54, 2339 (2007), arXiv:0712.2935.
This works because the DocumenterCitations plugin automatically upgrades style=:alpha to the internal
DocumenterCitations.AlphaStyle — Type
"Smart" alphabetic citation style (relative to the "dumb" :alpha).
style = AlphaStyle()
instantiates a style for CitationBibliography that avoids duplicate labels. Any of the entries that would result in the same label will be disambiguated by appending the suffix "a", "b", etc.
Any bibliography that cites a subset of the given entries is guaranteed to have unique labels.
source
Custom styles
In the following, we show two examples for user-defined styles. See the notes on customization on how to generally define a custom style.
Custom style: enumerated author-year
In this example, the :authoryear style is used, but the references are shown in an enumerated list.
import DocumenterCitations
 
 function DocumenterCitations.format_bibliography_reference(
     style::Val{:enumauthoryear},
@@ -44,4 +44,4 @@
 DocumenterCitations.bib_sorting(::Val{:keylabels}) = :nyt  # name, year, title
 
 DocumenterCitations.bib_html_list_style(::Val{:keylabels}) = :dl
-
References:
[BrifNJP2010]
C. Brif, R. Chakrabarti and H. Rabitz. Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008 (2010).
[BrumerShapiro2003]
P. Brumer and M. Shapiro. Principles and Applications of the Quantum Control of Molecular Processes. Wiley Interscience (2003).
[FuerstNJP2014]
H. A. Fürst, M. H. Goerz, U. G. Poschinger, M. Murphy, S. Montangero, T. Calarco, F. Schmidt-Kaler, K. Singer and C. P. Koch. Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007 (2014). Special issue on coherent control of complex quantum systems.
[GoerzQ2022]
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).
[KochJPCM2016]
C. P. Koch. Controlling open quantum systems: tools, achievements, and limitations. J. Phys.: Condens. Matter 28, 213001 (2016).
[Shapiro2012]
M. Shapiro and P. Brumer. Quantum Control of Molecular Processes. Wiley and Sons (2012).
[WinckelIP2008]
G. von Winckel and A. Borzì. Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007 (2008).

+

References:

[BrifNJP2010]
C. Brif, R. Chakrabarti and H. Rabitz. Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008 (2010).
[BrumerShapiro2003]
P. Brumer and M. Shapiro. Principles and Applications of the Quantum Control of Molecular Processes. Wiley Interscience (2003).
[FuerstNJP2014]
H. A. Fürst, M. H. Goerz, U. G. Poschinger, M. Murphy, S. Montangero, T. Calarco, F. Schmidt-Kaler, K. Singer and C. P. Koch. Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007 (2014). Special issue on coherent control of complex quantum systems.
[GoerzQ2022]
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).
[KochJPCM2016]
C. P. Koch. Controlling open quantum systems: tools, achievements, and limitations. J. Phys.: Condens. Matter 28, 213001 (2016).
[Shapiro2012]
M. Shapiro and P. Brumer. Quantum Control of Molecular Processes. Wiley and Sons (2012).
[WinckelIP2008]
G. von Winckel and A. Borzì. Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007 (2008).
diff --git a/previews/PR49/index.html b/previews/PR49/index.html index 208cb5c..cb108c2 100644 --- a/previews/PR49/index.html +++ b/previews/PR49/index.html @@ -42,4 +42,4 @@ ], plugins=[bib], ) -deploydocs(; repo="github.com/JuliaDocs/DocumenterCitations.jl.git")

Bibliographies are also supported in PDFs generated via LaTeX. All that is required is to replace format=Documenter.HTML(…) in the above code with format=Documenter.LaTeX(). See docs/makepdf.jl for an example. The resulting PDF files for the DocumenterCitations package are available as attachments to the Releases.

The rendering of the documentation may be fine-tuned using the DocumenterCitations.set_latex_options function. Note that the bibliography in LaTeX is directly rendered for the different styles from the same internal representation as the HTML version. In particular, bibtex/biblatex is not involved in producing the PDF.

How to cite references in your documentation

You can put citations anywhere in your docs, both in the markdown pages and in the docstrings of any functions that are shown as part of the API documentation: The basic syntax is, e.g., [GoerzQ2022](@cite), for a BibTeX key GoerzQ2022 in refs.bib, which will be rendered in the default numeric style as "[2]". See Syntax for Citations for more details.

Clicking on the citations takes you to the bibliography ("References").

Examples

The following is a list of some projects that use DocumenterCitations:

Home References

This page cites the following references:

[1]
C. Brif, R. Chakrabarti and H. Rabitz. Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008 (2010).
[2]
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).

Also see the full bibliography for further references cited throughout this documentation.

+deploydocs(; repo="github.com/JuliaDocs/DocumenterCitations.jl.git")

Bibliographies are also supported in PDFs generated via LaTeX. All that is required is to replace format=Documenter.HTML(…) in the above code with format=Documenter.LaTeX(). See docs/makepdf.jl for an example. The resulting PDF files for the DocumenterCitations package are available as attachments to the Releases.

The rendering of the documentation may be fine-tuned using the DocumenterCitations.set_latex_options function. Note that the bibliography in LaTeX is directly rendered for the different styles from the same internal representation as the HTML version. In particular, bibtex/biblatex is not involved in producing the PDF.

How to cite references in your documentation

You can put citations anywhere in your docs, both in the markdown pages and in the docstrings of any functions that are shown as part of the API documentation: The basic syntax is, e.g., [GoerzQ2022](@cite), for a BibTeX key GoerzQ2022 in refs.bib, which will be rendered in the default numeric style as "[2]". See Syntax for Citations for more details.

Clicking on the citations takes you to the bibliography ("References").

Examples

The following is a list of some projects that use DocumenterCitations:

Home References

This page cites the following references:

[1]
C. Brif, R. Chakrabarti and H. Rabitz. Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008 (2010).
[2]
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).

Also see the full bibliography for further references cited throughout this documentation.

diff --git a/previews/PR49/internals/index.html b/previews/PR49/internals/index.html index 49bbfa2..551a946 100644 --- a/previews/PR49/internals/index.html +++ b/previews/PR49/internals/index.html @@ -1,5 +1,5 @@ -Internals · DocumenterCitations.jl
GitHub

Internals

DocumenterCitations.CitationBibliography — Type

Plugin for enabling bibliographic citations in Documenter.jl.

bib = CitationBibliography(bibfile; style=:numeric)

instantiates a plugin object that must be passed as an element of the plugins keyword argument to Documenter.makedocs.

Arguments

  • bibfile: the name of the BibTeX file from which to read the data.
  • style: the style to use for the bibliography and all citations. The available built-in styles are :numeric (default), :authoryear, and :alpha. With user-defined styles, this may be an arbitrary name or object.

Internal fields

The following internal fields are used by the citation pipeline steps. These should not be considered part of the stable API.

  • entries: dict of citation keys to entries in bibfile
  • citations: ordered dict of citation key to citation number
  • page_citations: dict of page file name to set of citation keys cited on page.
  • anchor_map: an AnchorMap object that keeps track of the link anchors for references in bibliography blocks
source

Citation Pipeline

The DocumenterCitations.CitationBibliography plugin hooks into the Documenter.Builder.DocumentPipeline[1] between ExpandTemplates (which expands @docs blocks) and CrossReferences. The plugin adds the following three steps:

  1. CollectCitations
  2. ExpandBibliography
  3. ExpandCitations
DocumenterCitations.ExpandBibliography — Type

Pipeline step to expand all @bibliography blocks.

Runs after CollectCitations but before ExpandCitations.

Each bibliography is rendered into HTML as a a definition list, a bullet list, or an enumeration depending on bib_html_list_style.

For a definition list, the label for each list item is rendered via format_bibliography_label and the full bibliographic reference is rendered via format_bibliography_reference.

For bullet lists or enumerations, format_bibliography_label is not used and format_bibliography_reference fully determines the entry.

The order of the entries in the bibliography is determined by the bib_sorting method for the chosen citation style.

The ExpandBibliography step runs init_bibliography! before expanding the first @bibliography block.

source

Customization

A custom style can be created by defining methods for the functions listed below that specialize for a user-defined style argument to CitationBibliography. If the style is identified by a simple name, e.g. :mystyle, the methods should specialize on Val{:mystyle}, see the examples for custom styles. Beyond that, e.g., if the style needs to implement options or needs to maintain internal state to manage unique citation labels, style can be an object of a custom type. The builtin DocumenterCitations.AlphaStyle is an example for such a "stateful" style, initialized via a custom init_bibliography! method.

DocumenterCitations.format_bibliography_label — Function

Format the label for an entry in a @bibliography block.

mdstr = format_bibliography_label(style, entry, citations)

produces a plain text (technically, markdown) string for the label in the bibliography for the given Bibliography.Entry. The citations argument is a dict that maps citation keys (entry.id) to the order in which citations appear in the documentation, i.e., a numeric citation key.

For the default style=:numeric, this returns a label that is the numeric citation key in square brackets, cf. format_citation. In general, this function is used only if bib_html_list_style returns :dl for the given style.

source
DocumenterCitations.format_bibliography_reference — Function

Format the full reference for an entry in a @bibliography block.

mdstr = format_bibliography_reference(style, entry)

produces a markdown string for the full reference of a Bibliography.Entry. For the default style=:numeric, the result is formatted like in REVTeX and APS journals. That is, the full list of authors with initials for the first names, the italicized tile, and the journal reference (linking to the DOI, if available), ending with the publication year in parenthesis.

source
DocumenterCitations.format_citation — Function

Expand a CitationLink into style-specific markdown code.

md_text = format_citation(style, cit, entries, citations)

returns a string of markdown code that replaces the original citation link, rendering it for the given style. The resulting markdown code should make use of direct citation links (cf. DirectCitationLink).

For example, for the default style,

using DocumenterCitations: format_citation, CitationLink, example_bibfile
+Internals · DocumenterCitations.jl
GitHub
Internals
DocumenterCitations.CitationBibliography — Type
Plugin for enabling bibliographic citations in Documenter.jl.
bib = CitationBibliography(bibfile; style=:numeric)
instantiates a plugin object that must be passed as an element of the plugins keyword argument to Documenter.makedocs.
Arguments
  • bibfile: the name of the BibTeX file from which to read the data.
  • style: the style to use for the bibliography and all citations. The available built-in styles are :numeric (default), :authoryear, and :alpha. With user-defined styles, this may be an arbitrary name or object.
Internal fields
The following internal fields are used by the citation pipeline steps. These should not be considered part of the stable API.
  • entries: dict of citation keys to entries in bibfile
  • citations: ordered dict of citation key to citation number
  • page_citations: dict of page file name to set of citation keys cited on page.
  • anchor_map: an AnchorMap object that keeps track of the link anchors for references in bibliography blocks
source
Citation Pipeline
The DocumenterCitations.CitationBibliography plugin hooks into the Documenter.Builder.DocumentPipeline[1] between ExpandTemplates (which expands @docs blocks) and CrossReferences. The plugin adds the following three steps:
  1. CollectCitations
  2. ExpandBibliography
  3. ExpandCitations
DocumenterCitations.ExpandBibliography — Type
Pipeline step to expand all @bibliography blocks.
Runs after CollectCitations but before ExpandCitations.
Each bibliography is rendered into HTML as a a definition list, a bullet list, or an enumeration depending on bib_html_list_style.
For a definition list, the label for each list item is rendered via format_bibliography_label and the full bibliographic reference is rendered via format_bibliography_reference.
For bullet lists or enumerations, format_bibliography_label is not used and format_bibliography_reference fully determines the entry.
The order of the entries in the bibliography is determined by the bib_sorting method for the chosen citation style.
The ExpandBibliography step runs init_bibliography! before expanding the first @bibliography block.
source
Customization
A custom style can be created by defining methods for the functions listed below that specialize for a user-defined style argument to CitationBibliography. If the style is identified by a simple name, e.g. :mystyle, the methods should specialize on Val{:mystyle}, see the examples for custom styles. Beyond that, e.g., if the style needs to implement options or needs to maintain internal state to manage unique citation labels, style can be an object of a custom type. The builtin DocumenterCitations.AlphaStyle is an example for such a "stateful"  style, initialized via a custom init_bibliography! method.
DocumenterCitations.format_bibliography_label — Function
Format the label for an entry in a @bibliography block.
mdstr = format_bibliography_label(style, entry, citations)
produces a plain text (technically, markdown) string for the label in the bibliography for the given Bibliography.Entry. The citations argument is a dict that maps citation keys (entry.id) to the order in which citations appear in the documentation, i.e., a numeric citation key.
For the default style=:numeric, this returns a label that is the numeric citation key in square brackets, cf. format_citation. In general, this function is used only if bib_html_list_style returns :dl for the given style.
source
DocumenterCitations.format_bibliography_reference — Function
Format the full reference for an entry in a @bibliography block.
mdstr = format_bibliography_reference(style, entry)
produces a markdown string for the full reference of a Bibliography.Entry. For the default style=:numeric, the result is formatted like in REVTeX and APS journals. That is, the full list of authors with initials for the first names, the italicized tile, and the journal reference (linking to the DOI, if available), ending with the publication year in parenthesis.
source
DocumenterCitations.format_citation — Function
Expand a CitationLink into style-specific markdown code.
md_text = format_citation(style, cit, entries, citations)
returns a string of markdown code that replaces the original citation link, rendering it for the given style. The resulting markdown code should make use of direct citation links (cf. DirectCitationLink).
For example, for the default style,
using DocumenterCitations: format_citation, CitationLink, example_bibfile
 using Bibliography
 
 cit = CitationLink("[BrifNJP2010, Shapiro2012; and references therein](@cite)")
@@ -10,24 +10,24 @@
 
 # output
 
-"[[1](@cite BrifNJP2010), [2](@cite Shapiro2012), and references therein]"
Arguments
  • style: The style  to render the citation in, as passed to CitationBibliography
  • cit: A CitationLink instance representing the original citation link
  • entries: A dict mapping citations keys to a Bibliography.Entry
  • citations: A dict mapping that maps citation keys to the order in which citations appear in the documentation, i.e., a numeric citation index.
source
DocumenterCitations.init_bibliography! — Function
Initialize any internal state for rendering the bibliography.
init_bibliography!(style, bib)
is called at the beginning of the ExpandBibliography pipeline step. It may mutate internal fields of style or bib to prepare for the rendering of bibliography blocks.
For the default style, this does nothing.
For, e.g., AlphaStyle, the call to init_bibliography! determines the citation labels, by generating unique suffixed labels for all the entries in the underlying .bib file (bib.entries), and storing the result in an internal attribute of the style object.
Custom styles may implement a new method for init_bibliography! for similar purposes. It can be assumed that all the internal fields of the CitationBibliography bib object are up-to-date according to the citations seen by the earlier CollectCitations step.
source
Auxiliary customization routines
The following routines are used by the default styles to implement specific formatting. They may be reused by custom styles.
DocumenterCitations.format_labeled_citation — Function
Format a citation as in a "labeled" style.
md = format_labeled_citation(
+"[[1](@cite BrifNJP2010), [2](@cite Shapiro2012), and references therein]"
Arguments
  • style: The style  to render the citation in, as passed to CitationBibliography
  • cit: A CitationLink instance representing the original citation link
  • entries: A dict mapping citations keys to a Bibliography.Entry
  • citations: A dict mapping that maps citation keys to the order in which citations appear in the documentation, i.e., a numeric citation index.
source
DocumenterCitations.init_bibliography! — Function
Initialize any internal state for rendering the bibliography.
init_bibliography!(style, bib)
is called at the beginning of the ExpandBibliography pipeline step. It may mutate internal fields of style or bib to prepare for the rendering of bibliography blocks.
For the default style, this does nothing.
For, e.g., AlphaStyle, the call to init_bibliography! determines the citation labels, by generating unique suffixed labels for all the entries in the underlying .bib file (bib.entries), and storing the result in an internal attribute of the style object.
Custom styles may implement a new method for init_bibliography! for similar purposes. It can be assumed that all the internal fields of the CitationBibliography bib object are up-to-date according to the citations seen by the earlier CollectCitations step.
source
Auxiliary customization routines
The following routines are used by the default styles to implement specific formatting. They may be reused by custom styles.
DocumenterCitations.format_labeled_citation — Function
Format a citation as in a "labeled" style.
md = format_labeled_citation(
     style, cit, entries, citations;
     sort_and_collapse=true,
     brackets="[]",
     names=:lastonly,
     notfound="?",
-)
may be used when implementing format_citation for custom styles, to render the given CitationLink object cit in a format similar to the built-in :numeric and :alpha styles.
Options
  • sort_and_collapse: whether to sort and collapse combined citations, e.g. [1-3] instead of [2,1,3]. Not applicable to @citet.
  • brackets: characters to use to enclose citation labels
  • namesfmt: How to format the author names in @citet (:full, :last, :lastonly)
  • notfound: citation label to use for a citation to a non-existing entry
Beyond the above options, defining a custom citation_label method for the style controls the label to be used (e.g., the citation number for the default :numeric style.)
source
DocumenterCitations.format_authoryear_citation — Function
Format a citation as in the :authoryear style.
md = format_authoryear_citation(
+)
may be used when implementing format_citation for custom styles, to render the given CitationLink object cit in a format similar to the built-in :numeric and :alpha styles.
Options
  • sort_and_collapse: whether to sort and collapse combined citations, e.g. [1-3] instead of [2,1,3]. Not applicable to @citet.
  • brackets: characters to use to enclose citation labels
  • namesfmt: How to format the author names in @citet (:full, :last, :lastonly)
  • notfound: citation label to use for a citation to a non-existing entry
Beyond the above options, defining a custom citation_label method for the style controls the label to be used (e.g., the citation number for the default :numeric style.)
source
DocumenterCitations.format_authoryear_citation — Function
Format a citation as in the :authoryear style.
md = format_authoryear_citation(
     style, cit, entries, citations;
     empty_names="Anonymous",
     empty_year="undated",
     parenthesis="()",
     notfound="???",
-)
may be used when implementing format_citation for custom styles, to render the given CitationLink object cit in a format similar to the built-in :authoryear style.
Options
  • namesfmt: How to format the author names (:full, :last, :lastonly)
  • empty_names: String to use as "author" when the entry defines no author
  • empty_year: String to use as "year" when the entry defines no year
  • parenthesis: The parenthesis symbols to use for @cite/@citep
  • notfound: How to render a citation without a corresponding entry
source
DocumenterCitations.citation_label — Function
Return a citation label.
label = citation_label(style, entry, citations; notfound="?")
returns the label used in citations and the bibliography for the given entry in the given style. Used by format_labeled_citation, and thus by the built-in styles :numeric and :alpha.
For the default :numeric style, this returns the citation number (as found by looking up entry.id in the citations dict) as a string.
May return notfound if the citation label cannot be determined.
source
DocumenterCitations.format_authoryear_bibliography_reference — Function
Format a bibliography reference as for the :authoryear style.
mdstr = format_authoryear_bibliography_reference(
+)
may be used when implementing format_citation for custom styles, to render the given CitationLink object cit in a format similar to the built-in :authoryear style.
Options
  • namesfmt: How to format the author names (:full, :last, :lastonly)
  • empty_names: String to use as "author" when the entry defines no author
  • empty_year: String to use as "year" when the entry defines no year
  • parenthesis: The parenthesis symbols to use for @cite/@citep
  • notfound: How to render a citation without a corresponding entry
source
DocumenterCitations.citation_label — Function
Return a citation label.
label = citation_label(style, entry, citations; notfound="?")
returns the label used in citations and the bibliography for the given entry in the given style. Used by format_labeled_citation, and thus by the built-in styles :numeric and :alpha.
For the default :numeric style, this returns the citation number (as found by looking up entry.id in the citations dict) as a string.
May return notfound if the citation label cannot be determined.
source
DocumenterCitations.format_authoryear_bibliography_reference — Function
Format a bibliography reference as for the :authoryear style.
mdstr = format_authoryear_bibliography_reference(
     style, entry; namesfmt=:lastfirst, empty_names="—"
-)
Options
  • namesfmt: How to format the author names (:full, :last, :lastonly)
  • empty_names: String to use in place of the authors if there are no authors
source
Customizing LaTeX output
DocumenterCitations.set_latex_options — Function
Set options for how bibliographies are written via Documenter.LaTeXWriter.
DocumenterCitations.set_latex_options(; options...)
Valid options that can be passed as keyword arguments are:
  • ul_as_hanging: If true (default), format unordered bibliography lists (:ul returned by DocumenterCitations.bib_html_list_style) as a list of paragraphs with hanging indent. This matches the recommended CSS styling for HTML :ul bibliographies, see CSS Styling. If false, the bibliography will be rendered as a standard bulleted list.
  • ul_hangindent: If ul_as_hanging=true, the amount of hanging indent. Must  be a string that specifies a valid  LaTeX length,  e.g., "0.33in"
  • dl_hangindent : Bibliographies that should render as "definition lists" (:dl returned by DocumenterCitations.bib_html_list_style) are emulated as a list of paragraphs with a fixed label width and hanging indent. The amount of hanging indent is specified with dl_hangindent, cf. ul_hangindent.
  • dl_labelwidth : The minimum width to use for the "label" in a bibliography rendered in the :dl style.
  • bib_blockformat: A LaTeX format command to apply for a bibliography block.  Defaults to "\raggedright", which avoids hyphenation within the  bibliography. If set to an empty string, let LaTeX decide the default, which  will generally result in fully justified text, with hyphenation.
These should be considered experimental and not part of the the stable API.
Options that are not specified remain unchanged from the defaults, respectively a previous call to set_latex_options.
For bibliography blocks rendered in a :dl style, setting dl_hangindent and dl_labelwidth to the same value (slightly larger than the width of the longest label) produces results similar to the recommended styling in HTML, see CSS Styling. For very long citation labels, it may look better to have a smaller dl_hangindent.
Throws an ArgumentError if called with invalid options.
The defaults can be reset with DocumenterCitations.reset_latex_options.
source
DocumenterCitations.reset_latex_options — Function
Reset the options for how bibliographies are written in LaTeX.
DocumenterCitations.reset_latex_options()
is equivalent to the following call to set_latex_options:
set_latex_options(;
+)
Options
  • namesfmt: How to format the author names (:full, :last, :lastonly)
  • empty_names: String to use in place of the authors if there are no authors
source
Customizing LaTeX output
DocumenterCitations.set_latex_options — Function
Set options for how bibliographies are written via Documenter.LaTeXWriter.
DocumenterCitations.set_latex_options(; options...)
Valid options that can be passed as keyword arguments are:
  • ul_as_hanging: If true (default), format unordered bibliography lists (:ul returned by DocumenterCitations.bib_html_list_style) as a list of paragraphs with hanging indent. This matches the recommended CSS styling for HTML :ul bibliographies, see CSS Styling. If false, the bibliography will be rendered as a standard bulleted list.
  • ul_hangindent: If ul_as_hanging=true, the amount of hanging indent. Must  be a string that specifies a valid  LaTeX length,  e.g., "0.33in"
  • dl_hangindent : Bibliographies that should render as "definition lists" (:dl returned by DocumenterCitations.bib_html_list_style) are emulated as a list of paragraphs with a fixed label width and hanging indent. The amount of hanging indent is specified with dl_hangindent, cf. ul_hangindent.
  • dl_labelwidth : The minimum width to use for the "label" in a bibliography rendered in the :dl style.
  • bib_blockformat: A LaTeX format command to apply for a bibliography block.  Defaults to "\raggedright", which avoids hyphenation within the  bibliography. If set to an empty string, let LaTeX decide the default, which  will generally result in fully justified text, with hyphenation.
These should be considered experimental and not part of the the stable API.
Options that are not specified remain unchanged from the defaults, respectively a previous call to set_latex_options.
For bibliography blocks rendered in a :dl style, setting dl_hangindent and dl_labelwidth to the same value (slightly larger than the width of the longest label) produces results similar to the recommended styling in HTML, see CSS Styling. For very long citation labels, it may look better to have a smaller dl_hangindent.
Throws an ArgumentError if called with invalid options.
The defaults can be reset with DocumenterCitations.reset_latex_options.
source
DocumenterCitations.reset_latex_options — Function
Reset the options for how bibliographies are written in LaTeX.
DocumenterCitations.reset_latex_options()
is equivalent to the following call to set_latex_options:
set_latex_options(;
     ul_as_hanging=true,
     ul_hangindent="0.33in",
     dl_hangindent="0.33in",
     dl_labelwidth="0.33in",
     bib_blockformat="\raggedright",
-)
source
The standard citation links described in Syntax are internally parsed into the DocumenterCitations.CitationLink data structure:
DocumenterCitations.CitationLink — Type
Data structure representing a general (non-direct) citation link.
cit = CitationLink(link)
parses the given link string, e.g. "[GoerzQ2022](@cite)".
Attributes
  • node: The MarkdownAST.Node that link parses into
  • keys: A list of BibTeX keys being cited. e.g., ["BrumerShapiro2003", "BrifNJP2010"] for the citation "[BrumerShapiro2003,BrifNJP2010; and references therein][@cite]"
  • cmd: The citation command, one of :cite, :citet, :citep, or (unsupported in the default styles) :citealt, :citealp, :citenum. Note that, e.g., "[Goerz@2022](@Citet*)" results in cite_cmd=:citet
  • note: A citation note, e.g. "Eq. (1)" in [GoerzQ2022; Eq. (1)](@cite)
  • capitalize: Whether the citation should be formatted to appear at the start of a sentence, as indicated by a capitalized @Cite... command, e.g., "[GoerzQ2022](@Citet)"
  • starred: Whether the citation should be rendered in "extended" form, i.e., with the full list of authors, as indicated by a * in the citation, e.g., "[Goerz@2022](@Citet*)"
See also
  • DirectCitationLink – data structure for direct citation links of the form [text](@cite key).
source
Note the this does not include direct citation links such as [the Semi-AD paper](@cite GoerzQ2022), which are instead parsed into DocumenterCitations.DirectCitationLink:
DocumenterCitations.DirectCitationLink — Type
Data structure representing a direct citation link.
cit = DirectCitationLink(link)
parses the given link string of the form [text](@cite key).
Attributes
  • node: The MarkdownAST.Node that link parses into
  • key: The BibTeX key being cited. Note that unlike CitationLink, a DirectCitationLink can only reference a single key
See also
  • CitationLink – data structure for non-direct citation links.
source
Debugging
Set the environment variable JULIA_DEBUG=Documenter,DocumenterCitations before generating the documentation.

+)
source

The standard citation links described in Syntax are internally parsed into the DocumenterCitations.CitationLink data structure:

DocumenterCitations.CitationLink — Type

Data structure representing a general (non-direct) citation link.

cit = CitationLink(link)

parses the given link string, e.g. "[GoerzQ2022](@cite)".

Attributes

  • node: The MarkdownAST.Node that link parses into
  • keys: A list of BibTeX keys being cited. e.g., ["BrumerShapiro2003", "BrifNJP2010"] for the citation "[BrumerShapiro2003,BrifNJP2010; and references therein][@cite]"
  • cmd: The citation command, one of :cite, :citet, :citep, or (unsupported in the default styles) :citealt, :citealp, :citenum. Note that, e.g., "[Goerz@2022](@Citet*)" results in cite_cmd=:citet
  • note: A citation note, e.g. "Eq. (1)" in [GoerzQ2022; Eq. (1)](@cite)
  • capitalize: Whether the citation should be formatted to appear at the start of a sentence, as indicated by a capitalized @Cite... command, e.g., "[GoerzQ2022](@Citet)"
  • starred: Whether the citation should be rendered in "extended" form, i.e., with the full list of authors, as indicated by a * in the citation, e.g., "[Goerz@2022](@Citet*)"

See also

  • DirectCitationLink – data structure for direct citation links of the form [text](@cite key).
source

Note the this does not include direct citation links such as [the Semi-AD paper](@cite GoerzQ2022), which are instead parsed into DocumenterCitations.DirectCitationLink:

DocumenterCitations.DirectCitationLink — Type

Data structure representing a direct citation link.

cit = DirectCitationLink(link)

parses the given link string of the form [text](@cite key).

Attributes

  • node: The MarkdownAST.Node that link parses into
  • key: The BibTeX key being cited. Note that unlike CitationLink, a DirectCitationLink can only reference a single key

See also

  • CitationLink – data structure for non-direct citation links.
source

Debugging

Set the environment variable JULIA_DEBUG=Documenter,DocumenterCitations before generating the documentation.

diff --git a/previews/PR49/references/index.html b/previews/PR49/references/index.html index eef7067..bcd6663 100644 --- a/previews/PR49/references/index.html +++ b/previews/PR49/references/index.html @@ -2,4 +2,4 @@ References · DocumenterCitations.jl
GitHub

References

Cited References

The following references are cited in the documentation. The bibliography is produced with

```@bibliography
 ```
[1]
C. Brif, R. Chakrabarti and H. Rabitz. Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008 (2010).
[2]
M. H. Goerz, S. C. Carrasco and V. S. Malinovsky. Quantum Optimal Control via Semi-Automatic Differentiation. Quantum 6, 871 (2022).
[3]
D. J. Tannor. Introduction to Quantum Mechanics: A Time-Dependent Perspective. University Science Books, Sausalito, California (2007).
[4]
P. Brumer and M. Shapiro. Principles and Applications of the Quantum Control of Molecular Processes. Wiley Interscience (2003).
[5]
M. Shapiro and P. Brumer. Quantum Control of Molecular Processes. Wiley and Sons (2012).
[6]
C. P. Koch. Controlling open quantum systems: tools, achievements, and limitations. J. Phys.: Condens. Matter 28, 213001 (2016).
[7]
G. von Winckel and A. Borzì. Computational techniques for a quantum control problem with H$^1$-cost. Inverse Problems 24, 034007 (2008).
[8]
M. Goerz. Optimization of a Controlled Phasegate for Ultracold Calcium Atoms in an Optical Lattice. Diplomarbeit, Freie Universität Berlin (2010).
[9]
M. Goerz. Optimizing Robust Quantum Gates in Open Quantum Systems. Phd thesis, Universität Kassel (2015).
[10]
F. K. Wilhelm, S. Kirchhoff, S. Machnes, N. Wittler and D. Sugny. An introduction into optimal control for quantum technologies, arXiv:2003.10132 (2020).
[11]
E. A. Katrukha, M. Mikhaylova, H. X. van Brakel, P. M. van Bergen en Henegouwen, A. Akhmanova, C. C. Hoogenraad and L. C. Kapitein. Probing cytoskeletal modulation of passive and active intracellular dynamics using nanobody-functionalized quantum dots. Nat. Commun. 8, 14772 (2017), biorXiv:089284.
[12]
F. Sauvage and F. Mintert. Optimal Quantum Control with Poor Statistics. PRX Quantum 1, 020322 (2020). HAL:hal-03612955.
[13]
E. Brion. Contrôle Quantique et Protection de la Cohérence par effet Zénon, Applications à l'Informatique Quantique. Phd thesis, Université Pierre et Marie Curie - Paris VI (2014). HAL:tel-00007910v2.
[14]
H. A. Fürst, M. H. Goerz, U. G. Poschinger, M. Murphy, S. Montangero, T. Calarco, F. Schmidt-Kaler, K. Singer and C. P. Koch. Controlling the transport of an ion: Classical and quantum mechanical solutions. New J. Phys. 16, 075007 (2014). Special issue on coherent control of complex quantum systems.

Other References

The following are non-cited references (everything in the .bib file), included here to show how bibliographies are rendered for various types of materials. The list of references is produced with

```@bibliography
 *
-```
[15]
I. R. Sola, B. Y. Chang, S. A. Malinovskaya and V. S. Malinovsky. Quantum Control in Multilevel Systems. In: Advances In Atomic, Molecular, and Optical Physics, editors, Ennio Arimondo, Louis F. DiMauro and Susanne F. Yelin, 151-256. Academic Press (2018).
[16]
O. V. Morzhin and A. N. Pechen. Krotov method for optimal control of closed quantum systems. Russ. Math. Surv. 74, 851 (2019).
[17]
M. H. Goerz, T. Calarco and C. P. Koch. The quantum speed limit of optimal controlled phasegates for trapped neutral atoms. J. Phys. B 44, 154011 (2011), arXiv:1103.6050. Special issue on quantum control theory for coherence and information dynamics.
[18]
M. Tomza, M. H. Goerz, M. Musiał, R. Moszynski and C. P. Koch. Optimized production of ultracold ground-state molecules: Stabilization employing potentials with ion-pair character and strong spin-orbit coupling. Phys. Rev. A 86, 043424 (2012), arXiv:1208.4331.
[19]
M. H. Goerz, D. M. Reich and C. P. Koch. Optimal control theory for a unitary operation under dissipative evolution. New J. Phys. 16, 055012 (2014). Special issue on coherent control of complex quantum systems.
[20]
M. H. Goerz, E. J. Halperin, J. M. Aytac, C. P. Koch and K. B. Whaley. Robustness of high-fidelity Rydberg gates with single-site addressability. Phys. Rev. A 90, 032329 (2014), arXiv:1401.1858. Editor's suggestion.
[21]
G. Jäger, D. M. Reich, M. H. Goerz, C. P. Koch and U. Hohenester. Optimal quantum control of Bose-Einstein condensates in magnetic microtraps: Comparison of GRAPE and Krotov optimization schemes. Phys. Rev. A 90, 033628 (2014), arXiv:1409.2976.
[22]
M. H. Goerz, G. Gualdi, D. M. Reich, C. P. Koch, F. Motzoi, K. B. Whaley, J. Vala, M. M. Müller, S. Montangero and T. Calarco. Optimizing for an arbitrary perfect entangler. II. Application. Phys. Rev. A 91, 062307 (2015), arXiv:1412.7350.
[23]
P. Watts, J. Vala, M. M. Müller, T. Calarco, K. B. Whaley, D. M. Reich, M. H. Goerz and C. P. Koch. Optimizing for an arbitrary perfect entangler: I. Functionals. Phys. Rev. A 91, 062306 (2015), arXiv:1412.7347.
[24]
M. H. Goerz, K. B. Whaley and C. P. Koch. Hybrid Optimization Schemes for Quantum Control. EPJ Quantum Technol. 2, 21 (2015).
[25]
M. H. Goerz, F. Motzoi, K. B. Whaley and C. P. Koch. Charting the circuit QED design landscape using optimal control theory, npj Quantum Inf 3, 37 (2017).
[26]
A. A. Setser, M. H. Goerz and J. P. Kestner. Local gradient optimization of modular entangling sequences. Phys. Rev. A 97, 062339 (2018), arXiv:1804.08783.
[27]
M. H. Goerz and K. Jacobs. Efficient optimization of state preparation in quantum networks using quantum trajectories. Quantum Sci. Technol. 3, 045005 (2018), arXiv:1801.04382.
[28]
M. H. Goerz, D. Basilewitsch, F. Gago-Encinas, M. G. Krauss, K. P. Horn, D. M. Reich and C. P. Koch. Krotov: A Python implementation of Krotov's method for quantum optimal control. SciPost Phys. 7, 080 (2019).
[29]
[30]
G. Raithel, A. Duspayev, B. Dash, S. C. Carrasco, M. H. Goerz, V. Vuletić and V. S. Malinovsky. Principles of tractor atom interferometry. Quantum Sci. Technol. 8, 014001 (2022).
[31]
S. C. Carrasco, M. H. Goerz, Z. Li, S. Colombo, V. Vuletić and V. S. Malinovsky. Extreme Spin Squeezing via Optimized One-Axis Twisting and Rotations. Phys. Rev. Applied 17, 064050 (2022), arXiv:2201.01744.
[32]
M. H. Goerz, M. A. Kasevich and V. S. Malinovsky. Robust Optimized Pulse Schemes for Atomic Fountain Interferometry. Atoms 11, 36 (2023), arXiv:2212.12602. Special issue on Advances in and Prospects for Matter Wave Interferometry.
[33]
D. J. Tannor and Y. Jin. Design of Femtosecond Pulse Sequences to Control Photochemical Products. In: Mode Selective Chemistry, editors, J. Jortner, R. D. Levine and B. Pullman, 333–345. Springer (1991).
[34]
M. B. Giles. An extended collection of matrix derivative results for forward and reverse mode automatic differentiation. Technical Report NA-08-01, Oxford University Computing Laboratory (2008).
[35]
C.-H. Huang and H.-S. Goan. Robust quantum gates for stochastic time-varying noise. Phys. Rev. A 95, 062325 (2017), arXiv:1705.06150.
[36]
A. İmamoğlu and K. B. Whaley. Photoactivated biological processes as quantum measurements. Phys. Rev. E 91, 022714 (2015), arXiv:1408.5798.
[37]
L. C. Evans. An Introduction to Mathematical Optimal Control Theory (1983). Lecture Notes, University of California, Berkeley.
[38]
MATLAB, version 8.4 (R2014a). The MathWorks Inc., Natick, Massachusetts (2014).
[39]
E. Jones, T. Oliphant, P. Peterson and others. SciPy: Open source scientific tools for Python (2001–).
[40]
M. Lapert, R. Tehini, G. Turinici and D. Sugny. Monotonically Convergent Optimal Control Theory of Quantum Systems with Spectral Constraints on the Control Field. Phys. Rev. A 79, 063411 (2009), arXiv:0906.1051.
[41]
M. D. Grace, C. Brif, H. Rabitz, D. A. Lidar, I. A. Walmsley and R. L. Kosut. Fidelity of optimally controlled quantum gates with randomly coupled multiparticle environments. J. Mod. Opt. 54, 2339 (2007), arXiv:0712.2935.
[42]
M. Grace, C. Brif, H. Rabitz, I. A. Walmsley, R. L. Kosut and D. A. Lidar. Optimal control of quantum gates and suppression of decoherence in a system of interacting two-level particles. J. Phys. B 40, S103 (2007), arXiv:quant-ph/0702147.
[43]
J. Grond, G. von Winckel, J. Schmiedmayer and U. Hohenester. Optimal control of number squeezing in trapped Bose-Einstein condensates. Phys. Rev. A 80, 053625 (2009), arXiv:0908.1634.
[44]
J. Grond, J. Schmiedmayer and U. Hohenester. Optimizing number squeezing when splitting a mesoscopic condensate. Phys. Rev. A 79, 021603 (2009), arXiv:0806.3877.
[45]
E. Luc-Koenig, M. Vatasescu and F. Masnou-Seeuws. Optimizing the photoassociation of cold atoms by use of chirped laser pulses. Eur. Phys. J. D 31, 239 (2004), arXiv:physics/0407112 [physics.atm-clus].
[46]
C. P. Koch, U. Boscain, T. Calarco, G. Dirr, S. Filipp, S. J. Glaser, R. Kosloff, S. Montangero, T. Schulte-Herbrüggen, D. Sugny and F. K. Wilhelm. Quantum optimal control in quantum technologies. Strategic report on current status, visions and goals for research in Europe. EPJ Quantum Technol. 9, 19 (2022).
[47]
G. Turinici. Quantum control. HAL:hal-00640217 (2012).
[48]
A. Larrouy, S. Patsch, R. Richaud, J.-M. Raimond, M. Brune, C. P. Koch and S. Gleyzes. Fast Navigation in a Large Hilbert Space Using Quantum Optimal Control. Phys. Rev. X 10, 021058 (2020). HAL:hal-02887773.
[49]
A. M. Vecheck, C. McNamee, R. R. Pera and R. J. Usselman. Quantum Biology in Cellular Migration, bioRxiv:2022.09.09.507322 (2022).
[50]
Quantum Computation Roadmap (2004). Version 2.0; April 2, 2004.
[51]
T. Corcovilos and D. S. Weiss. Rydberg Calculations. Private communication.
[52]
J. Bradbury, R. Frostig, P. Hawkins, M. J. Johnson, C. Leary, D. Maclaurin, G. Necula, A. Paszke, J. VanderPlas, S. Wanderman-Milne and Q. Zhang. JAX: composable transformations of Python+NumPy programs.
+```
[15]
I. R. Sola, B. Y. Chang, S. A. Malinovskaya and V. S. Malinovsky. Quantum Control in Multilevel Systems. In: Advances In Atomic, Molecular, and Optical Physics, editors, Ennio Arimondo, Louis F. DiMauro and Susanne F. Yelin, 151-256. Academic Press (2018).
[16]
O. V. Morzhin and A. N. Pechen. Krotov method for optimal control of closed quantum systems. Russ. Math. Surv. 74, 851 (2019).
[17]
M. H. Goerz, T. Calarco and C. P. Koch. The quantum speed limit of optimal controlled phasegates for trapped neutral atoms. J. Phys. B 44, 154011 (2011), arXiv:1103.6050. Special issue on quantum control theory for coherence and information dynamics.
[18]
M. Tomza, M. H. Goerz, M. Musiał, R. Moszynski and C. P. Koch. Optimized production of ultracold ground-state molecules: Stabilization employing potentials with ion-pair character and strong spin-orbit coupling. Phys. Rev. A 86, 043424 (2012), arXiv:1208.4331.
[19]
M. H. Goerz, D. M. Reich and C. P. Koch. Optimal control theory for a unitary operation under dissipative evolution. New J. Phys. 16, 055012 (2014). Special issue on coherent control of complex quantum systems.
[20]
M. H. Goerz, E. J. Halperin, J. M. Aytac, C. P. Koch and K. B. Whaley. Robustness of high-fidelity Rydberg gates with single-site addressability. Phys. Rev. A 90, 032329 (2014), arXiv:1401.1858. Editor's suggestion.
[21]
G. Jäger, D. M. Reich, M. H. Goerz, C. P. Koch and U. Hohenester. Optimal quantum control of Bose-Einstein condensates in magnetic microtraps: Comparison of GRAPE and Krotov optimization schemes. Phys. Rev. A 90, 033628 (2014), arXiv:1409.2976.
[22]
M. H. Goerz, G. Gualdi, D. M. Reich, C. P. Koch, F. Motzoi, K. B. Whaley, J. Vala, M. M. Müller, S. Montangero and T. Calarco. Optimizing for an arbitrary perfect entangler. II. Application. Phys. Rev. A 91, 062307 (2015), arXiv:1412.7350.
[23]
P. Watts, J. Vala, M. M. Müller, T. Calarco, K. B. Whaley, D. M. Reich, M. H. Goerz and C. P. Koch. Optimizing for an arbitrary perfect entangler: I. Functionals. Phys. Rev. A 91, 062306 (2015), arXiv:1412.7347.
[24]
M. H. Goerz, K. B. Whaley and C. P. Koch. Hybrid Optimization Schemes for Quantum Control. EPJ Quantum Technol. 2, 21 (2015).
[25]
M. H. Goerz, F. Motzoi, K. B. Whaley and C. P. Koch. Charting the circuit QED design landscape using optimal control theory, npj Quantum Inf 3, 37 (2017).
[26]
A. A. Setser, M. H. Goerz and J. P. Kestner. Local gradient optimization of modular entangling sequences. Phys. Rev. A 97, 062339 (2018), arXiv:1804.08783.
[27]
M. H. Goerz and K. Jacobs. Efficient optimization of state preparation in quantum networks using quantum trajectories. Quantum Sci. Technol. 3, 045005 (2018), arXiv:1801.04382.
[28]
M. H. Goerz, D. Basilewitsch, F. Gago-Encinas, M. G. Krauss, K. P. Horn, D. M. Reich and C. P. Koch. Krotov: A Python implementation of Krotov's method for quantum optimal control. SciPost Phys. 7, 080 (2019).
[29]
[30]
G. Raithel, A. Duspayev, B. Dash, S. C. Carrasco, M. H. Goerz, V. Vuletić and V. S. Malinovsky. Principles of tractor atom interferometry. Quantum Sci. Technol. 8, 014001 (2022).
[31]
S. C. Carrasco, M. H. Goerz, Z. Li, S. Colombo, V. Vuletić and V. S. Malinovsky. Extreme Spin Squeezing via Optimized One-Axis Twisting and Rotations. Phys. Rev. Applied 17, 064050 (2022), arXiv:2201.01744.
[32]
M. H. Goerz, M. A. Kasevich and V. S. Malinovsky. Robust Optimized Pulse Schemes for Atomic Fountain Interferometry. Atoms 11, 36 (2023), arXiv:2212.12602. Special issue on Advances in and Prospects for Matter Wave Interferometry.
[33]
D. J. Tannor and Y. Jin. Design of Femtosecond Pulse Sequences to Control Photochemical Products. In: Mode Selective Chemistry, editors, J. Jortner, R. D. Levine and B. Pullman, 333–345. Springer (1991).
[34]
M. B. Giles. An extended collection of matrix derivative results for forward and reverse mode automatic differentiation. Technical Report NA-08-01, Oxford University Computing Laboratory (2008).
[35]
C.-H. Huang and H.-S. Goan. Robust quantum gates for stochastic time-varying noise. Phys. Rev. A 95, 062325 (2017), arXiv:1705.06150.
[36]
A. İmamoğlu and K. B. Whaley. Photoactivated biological processes as quantum measurements. Phys. Rev. E 91, 022714 (2015), arXiv:1408.5798.
[37]
L. C. Evans. An Introduction to Mathematical Optimal Control Theory (1983). Lecture Notes, University of California, Berkeley.
[38]
MATLAB, version 8.4 (R2014a). The MathWorks Inc., Natick, Massachusetts (2014).
[39]
E. Jones, T. Oliphant, P. Peterson and others. SciPy: Open source scientific tools for Python (2001–).
[40]
M. Lapert, R. Tehini, G. Turinici and D. Sugny. Monotonically Convergent Optimal Control Theory of Quantum Systems with Spectral Constraints on the Control Field. Phys. Rev. A 79, 063411 (2009), arXiv:0906.1051.
[41]
M. D. Grace, C. Brif, H. Rabitz, D. A. Lidar, I. A. Walmsley and R. L. Kosut. Fidelity of optimally controlled quantum gates with randomly coupled multiparticle environments. J. Mod. Opt. 54, 2339 (2007), arXiv:0712.2935.
[42]
M. Grace, C. Brif, H. Rabitz, I. A. Walmsley, R. L. Kosut and D. A. Lidar. Optimal control of quantum gates and suppression of decoherence in a system of interacting two-level particles. J. Phys. B 40, S103 (2007), arXiv:quant-ph/0702147.
[43]
J. Grond, G. von Winckel, J. Schmiedmayer and U. Hohenester. Optimal control of number squeezing in trapped Bose-Einstein condensates. Phys. Rev. A 80, 053625 (2009), arXiv:0908.1634.
[44]
J. Grond, J. Schmiedmayer and U. Hohenester. Optimizing number squeezing when splitting a mesoscopic condensate. Phys. Rev. A 79, 021603 (2009), arXiv:0806.3877.
[45]
E. Luc-Koenig, M. Vatasescu and F. Masnou-Seeuws. Optimizing the photoassociation of cold atoms by use of chirped laser pulses. Eur. Phys. J. D 31, 239 (2004), arXiv:physics/0407112 [physics.atm-clus].
[46]
C. P. Koch, U. Boscain, T. Calarco, G. Dirr, S. Filipp, S. J. Glaser, R. Kosloff, S. Montangero, T. Schulte-Herbrüggen, D. Sugny and F. K. Wilhelm. Quantum optimal control in quantum technologies. Strategic report on current status, visions and goals for research in Europe. EPJ Quantum Technol. 9, 19 (2022).
[47]
G. Turinici. Quantum control. HAL:hal-00640217 (2012).
[48]
A. Larrouy, S. Patsch, R. Richaud, J.-M. Raimond, M. Brune, C. P. Koch and S. Gleyzes. Fast Navigation in a Large Hilbert Space Using Quantum Optimal Control. Phys. Rev. X 10, 021058 (2020). HAL:hal-02887773.
[49]
A. M. Vecheck, C. McNamee, R. R. Pera and R. J. Usselman. Quantum Biology in Cellular Migration, bioRxiv:2022.09.09.507322 (2022).
[50]
Quantum Computation Roadmap (2004). Version 2.0; April 2, 2004.
[51]
T. Corcovilos and D. S. Weiss. Rydberg Calculations. Private communication.
[52]
J. Bradbury, R. Frostig, P. Hawkins, M. J. Johnson, C. Leary, D. Maclaurin, G. Necula, A. Paszke, J. VanderPlas, S. Wanderman-Milne and Q. Zhang. JAX: composable transformations of Python+NumPy programs.
diff --git a/previews/PR49/styling/index.html b/previews/PR49/styling/index.html index 63d95c9..7e702bc 100644 --- a/previews/PR49/styling/index.html +++ b/previews/PR49/styling/index.html @@ -23,4 +23,4 @@ ), plugins=[bib], # ... -) +) diff --git a/previews/PR49/syntax/index.html b/previews/PR49/syntax/index.html index 7c260ae..9e0d6a5 100644 --- a/previews/PR49/syntax/index.html +++ b/previews/PR49/syntax/index.html @@ -1,7 +1,7 @@ Syntax · DocumenterCitations.jl
GitHub

Syntax

Syntax for Citations

The following syntax is available to create citations in any markdown text:

  • [key](@cite) is the basic syntax, e.g., Refs. [GoerzQ2022](@cite) and [Tannor2007](@cite) which is rendered in the default numeric style as "Refs. [2] and [3]".

  • [key; note](@cite) allows to include a note in the citation, e.g., See Ref. [GoerzQ2022; Eq. (1)](@cite) which is rendered as "See Ref. [2, Eq. (1)]".

  • Multiple keys can be combined in a single citation, e.g., [BrumerShapiro2003, BrifNJP2010, Shapiro2012, KochJPCM2016; and references therein](@cite) renders as "[1, 4–6, and references therein]".

  • The direct [text](@cite key) can be used to link to a reference from arbitrary text, e.g., [the Semi-AD paper](@cite GoerzQ2022) renders as "the Semi-AD paper".

In […](@cite), the following variations can be used instead of @cite:

  • @citet: Text-style citation. This embeds the citation in the text flow, e.g., "As shown by Goerz et al. [2]…". For the default numeric citations, this is an alternative to "As shown in Ref. [2]"
  • @citep: Parenthetical citation. For the built-in styles, this is equivalent to just @cite.
  • @citet*: Like @citet, but with the full list of authors, e.g., Goerz, Carrasco and Malinovsky [2].
  • @cite*/@citep*: Like @cite/@citep, but with the full list of authors (for non-numeric styles where this makes sense).

Lastly, capitalizing the c in @citet or @citet* ensures that the first letter of the citation is capitalized so that it can be used at the beginning of a sentence, e.g., Von Winckel and Borzì [7] ([WinckelIP2008](@Citet)) versus von Winckel and Borzì [7] ([WinckelIP2008](@citet)).

The natbib commands @citealt, @citealp, and @citenum commands are also recognized. They are not supported by any of the built-in styles, but may be handled by custom styles.

See the Citation Style Gallery for examples of all the possible combinations.

Citations in docstrings

In docstrings, citations can be made with the same syntax as above. However, since docstrings are also used outside of the rendered documentation (e.g., in the REPL help mode), they should be more self-contained.

The recommended approach is to use a # References section in the docstring with an abbreviated bibliography list that links to the main bibliography. For example,

# References
 
-* [GoerzQ2022](@cite) Goerz et al. Quantum 6, 871 (2022)

in the documentation of the following Example:

DocumenterCitations.Example — Type
Example

An example object citing Ref. [2] with a "References" section in its docstring.

References

  • [2] Goerz et al. Quantum 6, 871 (2022)
source

(cf. the source of the Example type).

If there was no explicit numerical citation in the main text of the docstring,

* [Goerz et al. Quantum 6, 871 (2022)](@cite GoerzQ2022)

rendering as

would also have been an appropriate syntax.

Syntax for the Bibliography Block

Default @bibliography block

```@bibliography
+* [GoerzQ2022](@cite) Goerz et al. Quantum 6, 871 (2022)

in the documentation of the following Example:

DocumenterCitations.Example — Type
Example

An example object citing Ref. [2] with a "References" section in its docstring.

References

  • [2] Goerz et al. Quantum 6, 871 (2022)
source

(cf. the source of the Example type).

If there was no explicit numerical citation in the main text of the docstring,

* [Goerz et al. Quantum 6, 871 (2022)](@cite GoerzQ2022)

rendering as

would also have been an appropriate syntax.

Syntax for the Bibliography Block

Default @bibliography block

```@bibliography
 ```

renders a bibliography for all references that are cited throughout the entire documentation, see Cited References. As of version 1.0, the bibliography will not include entries that may be present in the .bib file, but that are not cited.

Full @bibliography

```@bibliography
 *
 ```

Renders a bibliography for all references included in the .bib file, not just those cited in the documentation. This corresponds to the pre-1.0 default behavior.

Multiple @bibliography blocks

It is possible to have multiple @bibliography blocks. However, there can only be one "canonical" bibliography target for any citation (the location where a citation links to). Any @bibliography block will automatically skip entries that have already been rendered in an earlier canonical @bibliography block. Thus, for two consecutive

```@bibliography
@@ -23,4 +23,4 @@
 ```

renders a bibliography only for the references BrifNJP2010, GoerzDiploma2010, and GoerzPhd2015:

[1]
C. Brif, R. Chakrabarti and H. Rabitz. Control of quantum phenomena: past, present and future. New J. Phys. 12, 075008 (2010).
[8]
M. Goerz. Optimization of a Controlled Phasegate for Ultracold Calcium Atoms in an Optical Lattice. Diplomarbeit, Freie Universität Berlin (2010).
[9]
M. Goerz. Optimizing Robust Quantum Gates in Open Quantum Systems. Phd thesis, Universität Kassel (2015).

The Pages = [] is required to exclude all other cited references. Note that the numbers [1, 8, 9] are from the main (canonical) References page.

Order of references

In the default numeric style, references in a @bibliography are rendered (and numbered) in the order in which they are cited. When there are multiple pages in the documentation, the order in which the pages appear in the navigation bar is relevant.

Non-cited references (* in a full bibliography) will appear in the order they are listed in the underlying .bib file. That order may be changed by sorting it explicitly:

bib = CitationBibliography("refs.bib")
 
 using Bibliography
-sort_bibliography!(bib.entries, :nyt)  # name-year-title

In general, the citation style determines the order of the references, see the Citation Style Gallery.

Syntax for the .bib file

The refs.bib file is in the standard BibTeX format. It must be parsable by BibParser.jl.

You will find that you get the best results by maintaining a .bib files by hand, specifically for a given project using DocumenterCitations. A .bib file that works well with LaTeX may or may not work well with DocumenterCitations: remember that in LaTeX, the strings inside any BibTeX fields are rendered through the TeX engine. At least in principle, they may contain arbitrary macros.

In contrast, for DocumenterCitations, the BibTeX fields are minimally processed to convert some common LaTeX constructs to plain text, but beyond that, they are used "as-is". In future versions, the handling of LaTeX macros may improve, but it is best not to rely on it, and instead edit the .bib file so that it gives good results with DocumenterCitations (see the tips below).

While we try to be reasonably compatible, "Any .bib file will render the bibliography you expect" is not a design goal, but "It is possible to write a .bib file so that you get exactly the bibliography you want" is.

Some tips to keep in mind when editing a .bib file to be used with DocumenterCitations:

  • Use unicode instead of escaped symbols.
  • You do not need to use braces to protect capitalization. DocumenterCitations is not always able to remove such braces. But, unlike bibtex, DocumenterCitation will preserve the capitalization of titles.
  • Use a consistent scheme for citation keys. Shorter keys are better.
  • All entries should have a Doi field, or a Url field if no DOI is available.
  • Use @string macros for abbreviated journal names, with the caveat of #31 and #32 in the BibParser.jl issues.

You may be interested in using (or forking) the getbibtex script to generate consistent .bib files.

Preprint support

If the published paper (Doi link) is not open-access, but a version of the paper is available on a preprint server like the arXiv, your are strongly encouraged to add the arXiv ID as Eprint in the BibTeX entry. In the rendered bibliography, the preprint information will be shown and automatically link to https://arxiv.org/abs/<ID>. If necessary, you may also add a Primaryclass field to indicate a category, see "BibTeX and Eprints" in the arXiv documentation.

Note that unlike in default BibTeX, it is not necessary to define Archiveprefix in the .bib file. A missing Archiveprefix is assumed to be arXiv. The field name Eprinttype (which in BibTeX is an alias for Archiveprefix) is currently not yet supported, nor is Eprintclass as an alias for Primaryclass.

For documents that are available only as an arXiv eprint, the best result is obtained with a BibTeX entry using the @article class, with, e.g., arXiv:2003.10132 in the Journal field, and, e.g., 10.48550/ARXIV.2003.10132 in the Doi field (but no Eprint field) [10].

Beyond arXiv, other preprint servers are supported. The Archiveprefix field for non-arXiv preprints is mandatory. For any defined Archiveprefix, Eprint, and Primaryclass fields, the rendered bibliography will include the preprint information in the format ArchivePrefix:Eprint [Primaryclass]. However, only certain preprint servers (known ArchivePrefix) will automatically be linked. Besides arXiv, the currently supported preprint servers are:

  • BiorXiv. The Archiveprefix is biorXiv. The Eprint ID should be the final part of the DOI, e.g. 2022.09.09.507322 [11].
  • HAL. The Archiveprefix is HAL. The Eprint ID should include the prefix (usually hal-, but sometimes tel-, etc.), e.g., Refs. [12, 13].

If you would like support for any additional preprint server, please open an issue.

+sort_bibliography!(bib.entries, :nyt) # name-year-title

In general, the citation style determines the order of the references, see the Citation Style Gallery.

Syntax for the .bib file

The refs.bib file is in the standard BibTeX format. It must be parsable by BibParser.jl.

You will find that you get the best results by maintaining a .bib files by hand, specifically for a given project using DocumenterCitations. A .bib file that works well with LaTeX may or may not work well with DocumenterCitations: remember that in LaTeX, the strings inside any BibTeX fields are rendered through the TeX engine. At least in principle, they may contain arbitrary macros.

In contrast, for DocumenterCitations, the BibTeX fields are minimally processed to convert some common LaTeX constructs to plain text, but beyond that, they are used "as-is". In future versions, the handling of LaTeX macros may improve, but it is best not to rely on it, and instead edit the .bib file so that it gives good results with DocumenterCitations (see the tips below).

While we try to be reasonably compatible, "Any .bib file will render the bibliography you expect" is not a design goal, but "It is possible to write a .bib file so that you get exactly the bibliography you want" is.

Some tips to keep in mind when editing a .bib file to be used with DocumenterCitations:

You may be interested in using (or forking) the getbibtex script to generate consistent .bib files.

Preprint support

If the published paper (Doi link) is not open-access, but a version of the paper is available on a preprint server like the arXiv, your are strongly encouraged to add the arXiv ID as Eprint in the BibTeX entry. In the rendered bibliography, the preprint information will be shown and automatically link to https://arxiv.org/abs/<ID>. If necessary, you may also add a Primaryclass field to indicate a category, see "BibTeX and Eprints" in the arXiv documentation.

Note that unlike in default BibTeX, it is not necessary to define Archiveprefix in the .bib file. A missing Archiveprefix is assumed to be arXiv. The field name Eprinttype (which in BibTeX is an alias for Archiveprefix) is currently not yet supported, nor is Eprintclass as an alias for Primaryclass.

For documents that are available only as an arXiv eprint, the best result is obtained with a BibTeX entry using the @article class, with, e.g., arXiv:2003.10132 in the Journal field, and, e.g., 10.48550/ARXIV.2003.10132 in the Doi field (but no Eprint field) [10].

Beyond arXiv, other preprint servers are supported. The Archiveprefix field for non-arXiv preprints is mandatory. For any defined Archiveprefix, Eprint, and Primaryclass fields, the rendered bibliography will include the preprint information in the format ArchivePrefix:Eprint [Primaryclass]. However, only certain preprint servers (known ArchivePrefix) will automatically be linked. Besides arXiv, the currently supported preprint servers are:

If you would like support for any additional preprint server, please open an issue.